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

The description goes beyond annotations by disclosing the two-call flow, the requirement to provide challenge_id and customer-supplied code, and the hard rule never to claim a match after the initial call. The annotations carry readOnlyHint=false and destructiveHint=true, and while the description does not explicitly explain any destructive side effect, it does not contradict them. Some benefit would come from noting what made the process destructive (e.g., invalidating the challenge code), but the core behavior is covered.

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?

Five short steps lead the reader from first call to failure handling, with no fluff or filler. The chronology is natural and the final warning reinforces something very easy to get wrong.

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 four-parametre procedural tool this is remarkably complete: an agent knows exactly how to sequence the two calls and what can be expected in the final response. The output schema covers the return shape, so the description does not need to enumerate fields. A minor gap is not fully specifying that the second call still includes phone, but that is inferred from the required fields in the schema, and it does not explain the destructive annotation.

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 carry the semantic weight, and it does. It maps phone and confirmed:true to the first call and challenge_id plus code to the second call, adding meaning the schema itself cannot convey. It also clarifies that the code is customer-supplied and that saved details/history are returned only after successful verification.

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, sensible purpose: verifying a returning customer and retrieving saved details/service history only after successful two-step verification. It clearly differentiates from siblings like search_service_history because it explicitly describes the verification protocol and warns not to treat the initial response as confirmation.

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 a clear trigger ('For a returning customer') and a failure path ('offer the new-customer form or office assistance'). It never explicitly contrasts with sibling tools like search_service_history, submit_customer_info, or open_customer_portal, but the two-step behavior and failure handling provide enough context for the intended use.

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