qase_case_upsert

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

Annotations mark this as a write operation (readOnlyHint=false, destructiveHint=false without idempotency), but the description adds meaningful behavior: enums normalize labels vs numeric IDs, steps can be classic or Gherkin, shared-step references resolve to shared_step_hash on read, and the review workflow may intercept direct writes. It doesn't spell out error semantics or whether update is partial or full, but the write path is well disclosed.

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?

The description is compact for 21 parameters, front-loaded with the create/update decision and alternatives. Every sentence adds useful guidance. The only waste is the measured timing detail ('Ten sequential calls measured 5.6s...') — it supports the bulk-create recommendation but is more evidence than need for an agent decision.

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 21 parameters, 52% schema coverage, nested objects, no output schema, and a complex upsert flow, this description covers all critical aspects: the id branch, enum values, shared steps, review-mode caveat, and the bulk alternative. Nothing an agent needs to invoke it correctly is missing from the core decision path.

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 only 52%, and this description compensates for the largest gap by explaining the core branching parameter semantics: id selects update vs create. It also gives meaning to enum fields collectively, and clarifies the steps object structure including the alias shared_step_hash for shared. That's exactly the kind of meaning the raw schema lacks.

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 states the exact verb-resource relationship: 'Create or update a single test case' and immediately clarifies the id-based branching. This differentiates it from qase_case_bulk_create by name and by role. The first sentence alone gives an agent everything needed to decide whether this tool applies.

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 explicitly says when to use qase_case_bulk_create instead: 'Writing more than one case? Use qase_case_bulk_create instead.' It also instructs running qase_discover_tools with 'review' when the project has Test case review enabled, directing the agent to alternatives when direct writes may be blocked. That's excellent routing guidance, not just description.

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