update_candidate

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

With no annotations, the description carries the full behavioral burden. It correctly discloses partial-update semantics ('only changes fields you provide'), which is the most important trait, but says nothing about permissions/auth, failure modes, or the fact that tags/phones/emails are wholesale replacements — that last point lives only in the schema descriptions, not the prose.

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?

Front-loaded with the operation and its key constraint, then a compact workflow block. The quoted user phrasing ('update Sarah's title to Senior Engineer') is mildly decorative but does aid intent matching, so the text is efficient without being minimal.

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?

An output schema exists, so return values need no explanation, and the description covers the required lookup chain for candidate_id and custom field IDs. For a 9-parameter mutation it could still note auth/permission requirements, leaving a minor gap.

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 schema already documents every parameter, including the replace-all semantics for tags, phones, and emails. The description adds only the routing hint that custom_field IDs come from list_custom_fields, which is a small increment over the baseline for a fully documented schema.

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 (update a candidate's profile) and immediately scopes the behavior: 'only changes fields you provide.' It also distinguishes this tool from the single-tag siblings by naming add_tag_to_candidate / remove_tag_from_candidate as the alternative for tag edits.

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?

Gives an explicit invocation workflow: to obtain candidate_id use search_candidates_by_name → get_candidate, and to obtain custom field IDs use list_custom_fields and match by name. It also names when to use the tag siblings instead, so both the setup path and the alternative-tool decision are spelled out.

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