retrieve_evidence

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explicitly states 'Read-only; never builds or changes an index,' which is clear about side effects. However, it doesn't disclose what 'bounded' means (limits, truncation, citation format), whether results are ordered, or what the citation format looks like. Partial transparency.

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?

One concise sentence and one short note. Efficient and front-loaded, with the key safety constraint (read-only) stated immediately. No wasted words, though slightly more detail could be justified given the parameter count.

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?

This is a moderately complex tool (9 params, 4 modes, date filters, media_type, token budget) with 0% schema description coverage and no output schema. The description is far too thin to guide correct invocation of all these options. The agent cannot determine what each mode does, how bounding works, or what the response shape is. Incomplete for the tool's true complexity.

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 compensate for the 9 parameters. The description adds minimal param context: 'bounded' hints at token_budget/limit, 'local' hints at scope, and 'citations' hints at what output contains. But it doesn't explain 'context' (0-8), 'mode' semantics beyond names, or 'since/until' format. Some value added, far from sufficient for 9 undocumented parameters.

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 a verb+resource ('Return bounded cited local evidence') and notes optional local-vector retrieval. However, 'evidence' is somewhat vague and doesn't sharply distinguish this from siblings like search_messages or query_knowledge_catalog. The read-only guarantee is helpful but the core operation remains ambiguous in scope.

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?

No guidance on when to use this tool vs. alternatives like search_messages, ask_archive, or query_knowledge_catalog. Sibling tools are not referenced or contrasted. The read-only note implies a usage constraint but doesn't tell the agent what distinguishes 'evidence retrieval' from general search.

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