task_context

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

No annotations are provided, so the description carries the full burden and does well: adaptive budget by default, token_budget override, a per-item 'why' and expand handle, plus truncation and index version reporting. The ordering/ranking behavior is disclosed clearly. It stops short of stating idempotency or whether an index must exist first.

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?

Information-dense and front-loaded: the core purpose leads, then scope, budget behavior, and output traits. Every sentence earns its place, though the run-on structure packs several ideas into a single block.

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?

For a complex retrieval tool with an output schema present, the description gives the agent a solid mental model: what is returned, how ranking works, how to scope, how to control budget, and what metadata accompanies results. The undocumented max_symbols is the only notable gap.

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% for 5 parameters. The description explains scope (path prefix with an example), token_budget (override for adaptive budget), and implicitly include_source via 'with source for the strongest ones', but max_symbols (default 40) is never mentioned, leaving partial compensation for the coverage gap.

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?

States a specific verb and resource: a single call to gather task-relevant symbols, source, tests, and config/docs, with the BM25/PageRank retrieval mechanism named. An agent can tell it apart from repo_overview or find_symbols, though it never names a sibling explicitly.

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?

'One call to start a task' implies this is the task-entry point, which is useful framing. However, it never states when to prefer it over find_symbols, references, or repo_map, nor any exclusion. Usage is implied rather than stated.

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