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

Beyond the annotations (which only declare write, idempotent, open-world), the description adds real behavior: stale-write rejection via expected, a rename propagating to the Quo card only when the business write setting allows, and an invariant that a contact always keeps a name, phone or email. The remaining gap is null semantics — the schema allows null on most fields but the description never says whether null clears a value or is ignored.

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?

Dense and front-loaded: the action and field set lead, then concurrency, propagation and retry caveats follow. The long comma-separated field enumeration is functional but stringy; it could be grouped (contact info vs. notes vs. operations) for faster scanning without adding length.

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 16-parameter mutation with 6% schema coverage and no output schema, the description covers the highest-risk traps (partial update, concurrency, idempotency, invariants) but leaves notable holes: no statement of return value, no clarification of null-clearing behavior, nothing on audit/notification side effects beyond the Quo rename. Adequate to call safely for simple field edits, incomplete for edge cases.

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 6%, so the description must carry parameter meaning, and it compensates for some: expected is explained as "field -> the value you read" with its stale_write consequence, address's "keep its zip if it had one" warns about read-then-write fidelity, and phone notes "with area code". The rest is a bare name list that restates schema property names without explaining contact_type's enum values, preferred_cleaner being staff-scoped, or the has_pets/pet_details relationship.

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 ("Edits a contact") and enumerates exactly which fields are editable, which is far more informative than the title. The analogy "as the contact card's pencil does" anchors the scope, though it never names its nearest sibling edit_contacts (bulk) to distinguish single-record editing from batch editing.

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?

"Send only the fields to change" establishes partial-update semantics clearly, and "Pass the same idempotency_key when retrying" gives concrete retry guidance. It stops short of naming when to prefer edit_contacts or create_client, and gives no prerequisites (permissions, whether the contact must already exist).

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