Fraya Tools

Fraya's available tools and how to use them.

Use the simplest sufficient tool. Start with documentation. Use domain-specific tools only when the task depends on repository data that the docs alone cannot provide.

get_brain

Use for:

  • documentation lookup;
  • repository policies, standards, and contracts;
  • high-level system explanations;
  • finding the smallest relevant documentation context before answering.

Default behavior:

  • start with overview.md at the beginning of a conversation;
  • search before reading a full document;
  • use full-document reads only when the excerpts are not enough.

Search first

Use search when:

  • the document is not yet known;
  • the question is narrow and evidence-based;
  • a few excerpts are enough to answer safely.

Read only when needed

Read a full document when:

  • the search excerpts are incomplete;
  • the best match points to one specific document;
  • the answer depends on exact wording or full context.

Use the brain as the default overview source

  • Use overview.md alone for broad identity, overview, orientation, and capability questions when it is already sufficient.
  • Do not run additional search just to restate what that document already covers.
  • Search further only when the user asks for a narrower domain or when the overview leaves a meaningful gap.

Keep the search narrow

  • Use the most specific question possible.
  • Limit scope when the domain is already clear.
  • Prefer 2–4 strong matches over a long noisy list.

Use the strongest matches

  • Use the highest-scoring matches that answer the question directly.
  • Ignore matches about docs retrieval itself unless the question is specifically about the docs or brain API.
  • Do not list every match when one or two are enough.
  • If the top match is enough, answer directly.

Escalate only when needed

  • Stay in documentation by default.
  • Escalate to prompt or injection files only when the task depends on exact current runtime behavior, exact prompt wording, or verification that the docs match the active files.
  • Do not jump to prompts or injections on the first step unless the task explicitly asks for active runtime logic.

fraya_tool_course_search

Use for:

  • finding a specific course;
  • retrieving only the course fields needed for the current task;
  • grounding course-related answers in repository-backed data.

Default behavior:

  • use it when the task depends on an actual course record rather than general documentation;
  • keep projection_query narrow and ask only for the fields needed right now;
  • do not use it for broad policy or documentation questions.

render_prompt

Use for:

  • inspecting the exact current prompt contract once the prompt name is known;
  • returning the stored prompt template text from GET /api/prompts/:name;
  • rendering prompt text with runtime inputs through POST /api/prompts/:name;
  • exposing example_request and structured_output_schema for workflow setup or debugging.

Default behavior:

  • use prompt discovery first when the exact prompt_name is unknown;
  • use info mode when you need the stored prompt text or metadata without rendering;
  • render only when the task depends on exact runtime wording with real inputs;
  • do not use this tool for broad documentation questions when get_brain is enough.

Prompt discovery flow:

  • use POST /api/prompts/query or GET /api/prompts to find the right prompt name;
  • then inspect the prompt through GET /api/prompts/:name or the shared render_prompt tool;
  • render through POST /api/prompts/:name only when exact filled prompt text is required.
  • Overview — Fraya identity and documentation map
  • API — HTTP endpoints used by tools and integrations