apply_schema

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

Annotations already declare destructiveHint=true, but the description adds concrete specificity: applying the schema 'can drop collections and fields.' That is valuable beyond the generic destructive flag. It also clarifies that this changes the live data model, not a draft or preview. No contradiction with 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 tightly packed sentences with no filler. The core action and source of input are front-loaded, and the destructive consequence is positioned immediately after the action. Every word earns its place.

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, live-altering operation with three parameters and no output schema, the description covers the key decision factors: what the input is, what it does, and its destructive potential. The schema covers parameter-level details, and annotations cover the destructive hint. A small gap is not mentioning that applied changes may be irreversible or that confirmation parameters exist, but the overall context is sufficient for correct tool selection and invocation.

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 100%, so the baseline is 3. The description reinforces that the diff parameter is the output of diff_schema, but it does not add substantive semantics for force or confirm beyond what the parameter descriptions already provide. It is adequate but not additive.

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 action ('Apply') on a precise resource ('a schema diff produced by diff_schema'), and clearly distinguishes its role from diff_schema, which produces the diff. It also conveys the high-impact nature of the operation, so an agent can immediately tell this is the apply step rather than a preview or validation step.

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 establishes the prerequisite by saying the diff must come from diff_schema, which implies the correct workflow: run diff_schema first, then apply_schema. It does not explicitly name alternatives or state when not to use the tool, but the destructive warning and live-model language give enough context to avoid using it for read-only or validation purposes.

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