context_search

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

The description discloses that results contain opaque refs and provenance, and that these refs can be passed to context_read. However, it does not mention whether the operation is read-only or has any side effects, and no annotations are provided to clarify safety or destructiveness.

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 concise and well-structured, consisting of two clear sentences. It avoids unnecessary details and gets straight to the point, making it easy to understand at a glance.

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 provides enough context about when to use the tool and what to do with the results (pass refs to context_read). It also ties the tool to the broader context of the current pack. However, it does not elaborate on all parameters or provide explicit alternatives, so it is not fully comprehensive.

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?

Only one of seven parameters (kinds_json) is explained in the description, and the schema provides no descriptions for any parameter. The meaning of query, max_items, space_ref, company_ref, project_ref, and token_budget is left entirely to their names, giving low coverage of parameter semantics overall.

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's purpose: searching durable context when the current pack lacks specific evidence. It uses the verb 'search' and specifies the resource (durable context) and the condition under which to use it, which distinguishes it from other search tools.

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 a clear condition for use ('when the current pack lacks specific evidence') and a follow-up action (passing selected refs to context_read). While it does not explicitly compare with alternative search tools, the condition and follow-up offer practical guidance on when and how to use it.

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