search_experience

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

With no annotations provided, the description carries the behavioral burden and does disclose meaningful traits: lexical matching behavior, the contents of each hit, verification status, evidence references, why it matched, prerequisites, cautions, and applicability flagging via version context. It still does not explicitly confirm read-only behavior or mention pagination, rate limits, or permissions.

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 front-loaded with the main purpose and gives practical query advice early. It is reasonably concise, though the list of hit contents is somewhat verbose given that an output schema exists.

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 covers the purpose and some key input guidance, and an output schema exists so return values need not be fully explained. But for a 10-parameter tool with no annotations and 0% schema description coverage, leaving most parameter semantics and all sibling routing unaddressed is a clear completeness 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% across 10 parameters, so the description must explain parameter meaning, but it only addresses query, current_os, and current_versions. It leaves k, mode, tool, repo_id, language, error_type, and verified_only unexplained, which is a significant gap for a 10-parameter search tool.

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 states a specific verb and resource: searching recorded experience, specifically lessons and failed episodes, for an error or task. It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools such as get_episode_evidence or report_task_outcome.

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 gives useful usage advice for the query parameter by recommending pasting the exact error line, and it explains why current_os/current_versions should be supplied. However, it does not say when to use this tool versus sibling alternatives, nor does it give conditions for when not to use it.

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