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

Annotations already indicate a destructive, non-read-only operation, but the description adds substantial behavior beyond that: replacements must use GeneratedJsonSchema, unknown keywords are dropped (not rejected) and reported in ignored_keywords / applied_repairs, and database-linked edits operate on a working copy with conditional propagation. It also discloses a docs reference for the contract and edit workflow. No statement contradicts the 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?

Every sentence earns its place: purpose, auth, sibling routing, replacement invariants, linked-schema behavior, return value, and doc link. The most important scoping sentence is front-loaded. It is dense but not bloated, 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 complex mutation tool with 7 parameters, a destructive annotation, and linked-schema workflow nuances, the description covers what an agent needs to call it correctly: the target, the authorization check, the exact replacement format, the unknown-keyword behavior, the publish/gating semantics, and the return shape. An output schema exists for return details, so the description need not duplicate that.

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?

Input schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the field descriptions: it frames the operation as 'only supplied values change', imposes the GeneratedJsonSchema constraint on schema_content, and explains the working-copy/publish behavior that affects how parameters like schema_content behave on linked schemas. It does not enumerate each parameter, but the schema already does that, so the extra value is above baseline.

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 description opens with a specific verb-resource pairing: 'Edit a saved schema's metadata or replace its full schema_content without an LLM call.' It clearly distinguishes itself from sibling tools by naming update_schema_property, add_schema_property, and move_schema_property as the alternatives for single-property edits. The scope is unambiguous and it does not rely on the title alone.

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?

It explicitly states when to prefer alternative tools ('For one property, prefer update_schema_property, add_schema_property or move_schema_property') and conditions the sibling choices. It also gives concrete guidance for database-linked schemas, explaining that neutral edits propagate automatically while structural edits take effect after publish_schema. The requirement for an editor role and the pointer to the contract docs round out practical usage conditions.

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