wire_discover

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

Beyond the readOnlyHint annotation, the description discloses valuable behavioral details: results are ranked, each candidate includes action_id, type, params, credit cost, and auth requirement, and the read/write distinction is explained with concrete examples. This gives the agent an accurate model of what the tool returns and how the results should be used.

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 core purpose and remains dense but well-structured: catalog context, read/write taxonomy, auth note, applicability, return contents, and follow-up actions. Every sentence contributes useful selection or invocation guidance, with no filler or redundancy.

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 discovery tool, the description covers purpose, when to use it, result contents, and next steps, and the presence of an output schema covers return-shape details. The only minor gap is lack of explicit differentiation from sibling discovery-related tools such as wire_catalog or agentic_search, but this does not materially hinder correct use.

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%, and the q parameter is already described as natural-language intent with examples, while limit has a default and bound in the schema. The description reinforces the intent-based nature of q but does not add significant parameter-level meaning beyond what the schema already provides.

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 opens with a specific verb and resource: 'Find Wire actions for a task from a natural-language intent.' It fully clarifies that this is a discovery tool over Wire's catalog, and the examples of READ and WRITE actions make the scope explicit without depending on the tool name alone.

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?

It clearly states when the tool is applicable: 'when a task may be achievable on a specific known site, for data extraction as well as interactions.' It also tells the agent how to proceed after discovery by routing to wire_read_action or wire_write_action, though it does not explicitly name discovery alternatives or when to avoid using this tool.

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