Match Behavioural Links

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

With no annotations, the description carries the safety burden well: it discloses payment, a non-writing and non-charging estimate mode, consent requirements, charging at actuals, proposal-only persistence, and the fact that nothing is declared. It also documents 402 when the caller cannot cover the charge, 409 `nothing_to_match`, and 404 when the caller may not start paid work.

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 scope and paid nature are front-loaded, and estimate versus execution is easy to locate through "Without" and "With it." The second paragraph is dense and could be easier to scan as bullets, but its length is largely justified by consent, billing, persistence, follow-up, and error details.

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 paid mutation with no annotations, the definition supplies nearly all operational context, while the output schema removes the need for a full return-value explanation. The notable remaining gap is the required `server_version`, whose role is unexplained in both the schema and description.

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?

The two-mode explanation substantially expands `confirm_estimate` beyond its brief schema description, clarifying both its dry-run and execution behavior. However, required `server_version` has neither a schema description nor an explanation in the prose, leaving one required parameter's purpose and expected value unclear.

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 opening sentence gives a specific verb, resources, target, and scope: only behavioural elements and zones marked `never_matched` are matched against the inventory. References to `get_behavioural_links`, the statement that it "declares nothing," and the named acceptance tool also distinguish it from read, declaration, and proposal-decision siblings.

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 gives an explicit workflow: identify `never_matched` nodes, call without `confirm_estimate` for nodes and an estimate, relay that estimate, and confirm only after the person agrees. It also explains when there is nothing to match and routes the agent to `get_behavioural_links` and `accept_behavioural_link_proposals` for subsequent review and acceptance.

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