Create or update shared step

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

Annotations only carry destructiveHint=false, so the description carries most of the behavioral load. It discloses the key non-obvious trait — that an update mutates every case referencing the step — plus operational cost (~0.5s, one API call). It does not discuss permission requirements, but the cascade warning is exactly the context annotations cannot supply.

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?

Four short clauses, each load-bearing: resource definition, create/update fork, identifier cross-reference, cascade risk, and cost. The operative facts (hash → update) are front-loaded 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?

With no output schema, the description covers the semantics an agent needs to invoke it correctly: mode selection, cascade effect, and latency. The one plausible gap is not saying what the call returns (presumably the shared-step hash needed for later reuse), but everything required for a correct invocation is present.

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%, including the create/update meaning of `hash`, so the structured data already does the heavy lifting. The description reinforces `hash` semantics and adds the cross-tool link (that qase_case_upsert consumes the hash in a step's `shared` field), which is marginal added value over a fully documented schema.

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 pair (create/update) and resource (shared step), then defines the resource in-line as 'a block of steps written once and reused across cases'. It also relates itself to qase_case_upsert, so an agent can distinguish it from siblings like qase_case_upsert and qase_shared_step_delete without opening any schema.

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 an explicit selection rule for the two modes: 'With hash it updates, without it creates'. It also flags the consequence of choosing update ('changes every referencing case'), which functions as a when-to-be-careful cue. No explicit 'when not to use' or pointer to qase_shared_step_delete for removal, so it stops short of 5.

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