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

Annotations only carry destructiveHint=true, so the description carries real weight: it discloses PATCH semantics, that only passed fields change, and critically that list fields (emails, phones, links, social_links) REPLACE rather than append. That replacement warning is exactly the behavior an agent would otherwise get wrong and is not present in the schema or annotations.

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 tightly packed sentences, front-loaded with the WRITE marker and the operation, followed by the partial-update rule and the replacement hazard, ending with the API path. Nothing is padding.

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 7-parameter mutation with no output schema, the description covers the operation, mutation semantics and the list-replacement trap. It could still note whether fields can be cleared or whether cover_letter is controllable, but nothing essential for a correct call 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 description coverage is 100%, so the baseline is 3, but the description adds meaning beyond it by clarifying partial-update semantics ('only the fields you pass change') and the full-replacement contract for list parameters, which the schema's per-field descriptions do not state.

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?

States a specific verb+resource ('WRITE: update a candidate') and even names the fields affected, which separates it from create_candidate and add_candidate_tags. Minor imprecision: it scopes the update to 'name or contact details' while the schema also exposes cover_letter, so the stated scope is narrower than the tool's actual capability.

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?

No when-to-use guidance and no routing to alternatives (e.g. use add_candidate_tags for tags, or create_candidate for new records). The only disambiguation is implicit in the verb 'update', leaving the agent to infer selection from the name alone.

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