Create or update suite

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

Annotations indicate readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the description doesn't need to restate those. It adds behavioral context by disclosing the cost (one API call, ~0.5s) and the single-call-per-node limitation, which is not available from annotations. It also hints at non-idempotency by noting the upsert behavior, though that is also clear from the schema.

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 three sentences, each carrying essential information: the core purpose, the create/update distinction, and the nesting workflow plus cost. There is no redundancy or filler; every sentence earns its place, and critical info (upsert semantics) is front-loaded.

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 tool with 6 parameters and no output schema, the description covers the key operational necessities: how to determine create vs update, when to consult project_context, the per-node call limitation, and the need to reuse returned IDs. It does not explicitly describe the return format, but it implies the tool returns IDs (reuse the IDs returned), which is sufficient for correct invocation. Minor gaps remain, but for the complexity it is fairly complete.

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 parameters are already documented. The description adds workflow-level meaning beyond the schema: it explains that parent_id should be sourced from project_context and that the returned IDs should be reused when building deep trees. This adds practical value to understanding how to combine parameters effectively, which is above the 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 clearly states the tool creates or updates a test suite ('the folder cases live in'), with a specific verb and resource. It distinguishes it from similar tools like qase_case_upsert by explicitly naming the resource type. The id-based create/update behavior is stated upfront, making the purpose unambiguous.

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 gives explicit when-to-use guidance: it says to read qase_project_context first rather than guessing parent IDs, and explains the one-call-per-node constraint for deep trees, telling users to create parents before children. This directly aids in correct usage and points to a sibling tool for needed context.

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