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

Annotations only supply destructiveHint=true; the description adds the genuinely useful upsert semantics (insert or replace), the composite key it upserts on, and the blast-radius constraint that only the draft is touched. It does not cover auth requirements or rate limits, but the safety profile is well communicated.

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 tight sentences, front-loaded with the WRITE classification and the operation, followed by scope and endpoint detail. No filler, and each sentence carries distinct information.

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?

With 4 required params all documented at 100% schema coverage and a destructive upsert, the description covers the remaining gaps: what is replaced, what is untouched, and the return value ('the staged row') despite there being no output schema.

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 baseline is 3, but the description adds real meaning by disclosing the upsert key (draft_id, catalog_name), which tells the agent what constitutes identity for replacement rather than insertion, plus the verbatim pass-through nature of spec.

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: 'stage (insert or replace) a catalog spec inside a draft', prefixed with 'WRITE:' so the operation class is unambiguous. This clearly separates it from siblings like estuary_publish_draft and estuary_list_draft_specs.

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 clear context for when to use it: to modify spec content inside a draft, with the reassurance that live pipelines are unaffected until publication, which implicitly routes agents to publish_draft for going live. It stops short of naming alternatives or stating prerequisites explicitly.

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