set_contact

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

Annotations only mark it as a non-read, non-open-world write; the description adds the traits that matter: partial update (unspecified fields are preserved), a 'clear' sentinel for deleting optional values, whole-list replacement for `links`, and the return payload ('the `contact` as saved in profile.yaml') — valuable here since there is no output schema. The `links` replacement semantics go beyond, not against, destructiveHint=false, since it is a scoped setter for an explicitly whole-list field.

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?

Four tight sentences, each doing distinct work: scope, boundary against siblings, mutation semantics, return value. The most decision-relevant facts (what it covers and what it does not) are front-loaded.

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 6-parameter, all-optional mutation with no output schema, the definition covers scope, partial-update behavior, value-removal syntax, list-replacement behavior, and the return shape. Nothing an agent needs to call 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 is 3, but the description adds real meaning the schema lacks: the 'clear' sentinel for removing an optional field and the fact that `links` replaces rather than appends. It does not explain the `profile` resolution path beyond what the schema already says, so it stays short of a 5.

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 and resource ('Update the person's contact details on the CV') and immediately scopes which fields belong to it (name, email, phone, location, links). It explicitly hands off roles and education to other tools, so an agent can distinguish it from upsert_role/upsert_education without opening any 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?

Gives both when-to-use (contact fields) and when-not (roles, education and the rest have their own tools), which is the routing decision an agent actually faces among 30+ siblings. It also states the partial-update contract ('Only the fields given change'), removing the main source of misuse.

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