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

Annotations already carry destructiveHint=true and readOnlyHint=false, but the description adds critical behavioral detail beyond them: the WHOLESALE replace semantics, that description is set to exactly what you pass, that an empty/omitted description CLEARS it, and that display_name is required and cannot be blank. This surfaces the destructive edge cases the annotation only hints at.

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?

A single dense paragraph, front-loaded with the core purpose and scoping before the wholesale warning. Every sentence carries information, though it is somewhat long and could be split for scanability. Slightly above average for a tool with complex destructive semantics.

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 destructive mutation with no idempotentHint, the description fully covers the failure modes: what is and isn't changed, the clearing behavior, the required field, and the safe procedure for partial updates. With an output schema present, return-value documentation is not needed. 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 schema already documents all three parameters, including 'Set wholesale — an empty value clears it' for description. The description adds the cross-parameter interaction (must pass both to change one) which is genuinely useful, but the schema carries most of the parameter burden, so baseline 3 applies.

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+fields: 'Update a schema's display_name and description'. Explicitly scopes itself to metadata-only and distinguishes from the sibling create_schema_version (which authors the JSON Schema body), so an agent can tell them apart without opening schemas.

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 explicit when-not guidance (this does NOT change the JSON Schema body; use create_schema_version for that) and names the alternative for safe partial updates (read current values with get_schema first). Also notes the immutable slug. Nothing is left to inference.

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