query_codebase

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. It states the output ('synthesized answer plus the source file excerpts'), the automatic resource fallback behavior, and that top_k controls grounding. It could add a note about failure modes or index requirements, but it covers the main observable behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly structured, front-loading the core purpose, then usage guidance, then parameter documentation. Every sentence adds value, and the examples are illustrative without being padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a RAG search tool: it covers when to use it, what it returns, how each parameter behaves, and the automatic resource resolution. Since an output schema exists, detailed return-value documentation is not required.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter documentation, and it does. All three parameters (query, resource, top_k) are explained with semantics beyond their schema types, including defaults, max value, and automatic fallback behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Fuzzy/semantic RAG search over a codebase indexed by ragd.' It goes beyond the name by explaining the mechanism (RAG, semantic) and directly distinguishes the tool from exact-match tools like Grep/Glob.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to prefer this tool: 'Prefer this over Grep/Glob when the question is conceptual rather than an exact string/symbol match.' Concrete examples and the condition for choosing an alternative make the routing decision unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.