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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses two behavioral facts the annotations cannot: the answer is refused unless it identifies the person, and confirming conditionally writes the profile link onto the record only when a prior search/lookup returned that link at the named company. That is exactly the kind of side-effect and failure-mode detail an agent needs before invoking a write tool.

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?

Three sentences, front-loaded with the action and the source of the input, followed by the validation rule and the side effect. The final sentence is dense but every clause carries decision-relevant information; only minor tightening is possible.

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?

With annotations covering the safety and idempotency profile and an output schema covering return values, the description supplies the remaining pieces an agent needs: the prerequisite sibling, the refusal condition, and the conditional profile-link write. Nothing essential to calling it correctly is missing.

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 coverage is 100%, so the baseline would be 3, but the description adds a cross-field rule not present in the schema: the answer must be anchored to the person via name, company, e-mail or profile link. It also clarifies how profile_url interacts with the conditional write, giving extra semantic value over the per-parameter descriptions.

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 object ('Record the customer's answer about a possible match') and ties the resource directly to the sibling that produces it, find_person_in_crm. An agent can distinguish this from find_person_in_crm and update_crm_record without opening the schema.

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 makes clear this is the follow-up step after find_person_in_crm yields a possible match and the customer has responded, and it states the precondition that the answer must identify the person. It doesn't explicitly name a when-not case or an alternative tool, keeping it short of a 5.

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