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

Beyond annotations, which already flag mutation, idempotency, and destructiveness, the description discloses optimistic concurrency protection, retry safety, and a concrete side-effect guarantee that invoice recipient snapshots never change automatically. This is valuable behavioral context not derivable from 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?

Two short sentences, front-loaded with the action and key guarantees. Every clause earns its place with no filler or repetition.

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 12-parameter mutation tool, the critical non-obvious semantics are covered: version guarding, idempotent retries, and non-cascading snapshot behavior. The output schema and annotations carry the remaining load, though optional-field semantics and explicit sibling routing are not addressed.

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 only 25%, leaving nine optional fields mostly undocumented, and the description does not compensate by explaining them. It does map 'optimistic version protection' and 'retry safety' to expectedVersion and idempotencyKey, but the meaning of fields such as attention or businessNumber remains unclear.

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 verb 'Partially update' plus the resource 'saved client' precisely identifies a PATCH-style mutation and clearly distinguishes it from create/get/list siblings such as create_client and get_client. Adding 'optimistic version protection and retry safety' further clarifies the operation mode.

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?

The description implies the tool is for modifying an existing saved client, but it never explicitly states when to prefer it over create_client or how to route between update_client and update_invoice. There is no when-not-to-use guidance or alternative naming, so an agent must infer applicability from the wording 'saved client'.

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