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

Annotations declare destructiveHint=true and idempotentHint=false, and the description usefully explains why a flag edit is destructive: 'Renaming a label renames it on every conversation that carries it.' It also clarifies partial-update semantics ('Only the fields you pass change'), which is real behavioral content beyond the annotations. It stops short of noting permission requirements or whether the rename is reversible.

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 short sentences, front-loaded with the action and field list, followed by the highest-value warning (rename propagation) and the partial-update rule. No filler or restatement of the tool name.

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 five-parameter mutation with no output schema, the description covers the important behavior: scope of the change, which fields are affected, and the cross-conversation side effect of renaming. Remaining gaps are minor — no mention of the label_id target, permissions, or error conditions — and the safety profile is already carried by annotations.

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?

With 0% schema description coverage, the description is the only source of field meaning, and it names four of the five parameters in plain language (title, description, colour, show_on_sidebar). However it omits the label_id target and gives none of the constraints the schema encodes only as pattern/type (hex colour format, lowercase-title pattern, max lengths), so it only partially compensates for the coverage gap.

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 ('Change a label') and enumerates exactly which attributes are mutable (title, description, colour, sidebar visibility), so the agent knows this edits the label entity itself. It does not explicitly distinguish itself from the label-assignment siblings (contact_add_labels, conversation_add_labels) or from delete_label/create_label, leaving that routing to inference.

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?

Usage is implied by the field list and by 'Only the fields you pass change', which tells the agent this is a partial update rather than a full overwrite. There is no explicit when-to-use/when-not guidance and no named alternative for attaching labels to contacts or conversations, so the agent must infer that this tool edits the label definition, not a label's memberships.

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