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

With no annotations provided, the description fully carries the burden of disclosing behavior. It introduces critical behavioral constraints: 'MANDATORY FINALITY' (return output directly, run no other tools), precondition handling, and inherited scope. It also tells the agent to follow formatting instructions exactly, which is very useful. This goes beyond a basic read-only expectation.

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 well-structured with headers (MANDATORY FLOW, MANDATORY FINALITY, Usage) and front-loaded with a clear purpose. It is somewhat long but every sentence carries essential information. The use of examples and explicit do's/don'ts makes it easy to follow, though it could be tightened slightly.

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?

Given the tool's complexity (combined search/fetch, mandatory ordering, finality rules) and the absence of an output schema, the description provides comprehensive guidance. It covers query format, repository scope, call frequency, preconditions, and response handling, leaving little ambiguity for an AI agent.

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 100% for both parameters, so the schema already provides solid definitions. The description adds value by constraining query length ('2-4 words') and adding a constraint on repos ('must be inside inherited scope'), which is not stated in the schema. This justifies a score above the baseline 3.

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 clearly states the tool searches reference repos and returns source code snippets in one call, explicitly mentioning 'ONE call does everything: searches file trees, fetches matching code, returns snippets.' This distinguishes it from siblings like search_code or get_file by highlighting its combined search-and-fetch behavior.

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 provides explicit usage instructions: mandatory order (suggestion first), call once, short keyword queries, and inherited repository scope. It also explains the precondition response if suggestion wasn't called. However, it doesn't explicitly name alternative tools or describe when to use something else, so it misses the 'alternatives' criterion for a 5.

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