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

Annotations carry only destructiveHint=false, so the description does real work: it discloses JSON-only payloads, that DELETE triggers a confirmation prompt like the dedicated delete tools, and an expected cost/latency (one API call, 0.3-1.5s). It stops short of covering auth expectations or how errors from arbitrary endpoints surface, which for an unbounded passthrough tool would be useful.

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 tight sentences, front-loaded with what the tool is and the routing rule, then the constraints (JSON, uploads, DELETE confirmation) and finally the cost. No sentence is redundant.

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 an unbounded REST passthrough with no output schema, the definition covers routing, format, confirmation behavior and cost. The remaining gap is error/response handling for arbitrary endpoints (e.g., how non-2xx responses are surfaced), which a generic caller would benefit from knowing.

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 genuinely new meaning by noting that dedicated tools 'normalize enums and validate' while this one does not — implying callers must supply raw, unvalidated values. It also clarifies the path is 'on the configured host' and that body/query are optional.

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 (call) and resource (any Qase REST endpoint) and immediately positions itself as the escape hatch 'for the few things no dedicated tool covers'. It is unmistakable against siblings like qase_get or the dedicated *_upsert/*_delete tools.

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 when-to-use rule ('only where no dedicated tool covers it'), an explicit preference ('Prefer a dedicated tool where one exists') with the reason (they normalize enums and validate before spending a call), and a named exclusion/alternative (uploads go through qase_attachment_upload).

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

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

Goes well beyond the lone idempotentHint annotation: it discloses that references remain dangling while the file itself is removed, that the action is irreversible, that user confirmation is requested, and even the cost (one API call, ~0.4s). These are exactly the consequences an agent needs before firing a destructive call.

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?

A single tight sentence front-loads the action and its key, then stacks consequence, irreversibility, confirmation, and cost without padding. Every clause carries information an agent can act on.

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 one required parameter, no output schema, and no nested objects, the definition covers everything needed: what to pass, where to get it, what happens after, and the interaction cost. Nothing material is missing for a correct 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 coverage is 100% so the 'hash' parameter is already documented, but the description adds provenance ('from qase_attachment_upload'), telling the agent where a valid value comes from rather than just its type. That is genuine added meaning over the thin schema description.

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?

Opens with a specific verb+resource ('Delete an attachment') and identifies the identifying key ('by its hash'), immediately distinguishing it from siblings like qase_attachment_upload. An agent knows exactly what this tool does without opening the 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?

Points the agent to qase_attachment_upload as the source of the hash and notes a user-confirmation step before execution. It gives clear context for invoking the tool but does not enumerate when-not-to-use conditions, which is minor for a terminal delete operation.

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

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

Annotations only carry destructiveHint=false, so the description does the real work: it discloses the hash-return contract, the remote-vs-local file_path limitation, the multipart/form-data uniqueness, and a cost model ('one API call per request, dominated by size'). These are behavioral traits no annotation conveys.

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?

Front-loads the payoff (get back hashes), then layers mode selection, the attach step, and cost. Every sentence carries distinct, non-redundant information; nothing is padding.

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 still explains the return value (ordered hashes) and the follow-up requirement, plus where limits live (qase_tool_help). For a 6-param upload tool with a two-step workflow, nothing critical is missing.

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 cross-parameter logic the schema doesn't state — single-file form (file_base64+filename) vs multi-file form (files), and the conditional validity of file_path based on server locality. It doesn't cover the deprecated `file` param or the code pattern, keeping it just below the top.

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+resource ('Upload files') and immediately names the output artifact (hashes other tools reference them by). It also differentiates itself from the qase_api sibling by explaining that this is the only tool that sends multipart/form-data, so an agent knows why to pick this one.

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?

Explicitly distinguishes the three input modes: file_base64+filename for a single file, files for several, and file_path only when server and file share a machine (never on the hosted connector). It also discloses the two-step workflow — 'uploading alone attaches nothing' and the hash must be passed in an `attachments` field — so the agent knows this tool is not sufficient on its own.

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

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

Annotations only supply destructiveHint=false. The description adds that this tool creates only (never updates), the 100-case batch ceiling, and a concrete cost profile (one API call, 1.2s vs 5.6s). It stops short of disclosing failure behavior for a partially invalid batch, which is the notable residual gap.

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?

Front-loads the limit and the sibling relationship before the cost justification. The benchmark sentence is longer than strictly necessary but does earn its place by justifying batch use over loops.

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?

A 2-parameter batch-create tool with full schema coverage and no output schema needs little more. The one gap is atomicity: the description doesn't say whether a bad case rejects the whole batch or is skipped, which matters for a 100-item call.

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 batch fields and step structure are already documented in the schema. The description adds only that field and enum handling match qase_case_upsert, which is a light pointer rather than new per-parameter meaning.

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 (create) and resource (test cases) with scope (up to 100 per request) and explicitly positions itself as the batch form of qase_case_upsert. An agent can distinguish it from the single-case sibling without opening either 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 — 'the right tool whenever more than one case is being written' — and names the alternative for the other case (update through qase_case_upsert with `id`). Both when-to-use and when-not-to-use are covered.

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

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

Annotations only supply idempotentHint, so the description carries the destructive profile and does so well: it discloses collateral damage ('its execution history goes with it'), irreversibility ('cannot be undone'), the one-per-call limitation, and a human confirmation requirement. It even quantifies cost at one API call / ~0.4s. Nothing contradicts idempotentHint=true.

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 compact sentences ordered by importance: what it does, what is destroyed plus the safer alternative, then the batching and cost constraints. No filler or repetition of the title.

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 two-parameter destructive tool with no output schema, the description covers the full decision surface: scope, irreversibility, execution-history loss, the non-bulk constraint, the confirmation requirement, and the alternate safe path. An agent has everything needed to call it correctly or avoid it.

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 both parameters (code, id) are already documented with pattern and range constraints. The description only restates that identification is by project code and ID, adding no format or edge-case detail beyond the schema. Baseline 3 applies.

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 ('Delete a test case') and narrows the identifier to 'by project code and ID', which maps directly onto the two schema properties. An agent can distinguish it from qase_case_upsert and other *_delete siblings without opening a 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?

Explicitly routes to an alternative ('consider marking it deprecated through qase_case_upsert instead') and states an exclusion ('No bulk delete — one call each, each asking the user for confirmation'). Both when-to-use and when-not-to-use are covered.

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

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

With only destructiveHint=false in annotations, the description carries most of the burden and does well: it discloses the review-gating workflow, per-operation latency cost, and the enum label-vs-numeric-ID convention. It does not state what happens to fields omitted on an update (partial merge vs. overwrite), which for an upsert tool is the remaining behavioral unknown.

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?

Six tight sentences, front-loaded with the create/update rule, then scaling guidance, then prerequisites, then cost. No filler and nothing buried at the end that an agent needs first.

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 21-parameter tool with nested step objects and no output schema, the description covers the operation branch, sibling routing, and the review gate. The one omission is update semantics for partially supplied parameters, though 100% schema coverage and the absence of an output schema limit the severity.

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 adds the useful convention that enum fields accept a label like 'high' or a numeric ID, but the schema already repeats 'label or numeric ID' on each such parameter, so the added meaning is marginal rather than substantial.

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+resource pair ('create or update a single test case') and immediately disambiguates the upsert semantics: id present means update, absent means create. This cleanly separates it from sibling qase_case_bulk_create and qase_case_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?

Explicitly routes multi-case writes to qase_case_bulk_create with the reason ('one request instead of one per case'), and names qase_discover_tools with the 'review' query when the project has Test case review enabled. Both an alternative and a conditional prerequisite are given, not implied.

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

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

Annotations only declare destructiveHint=false, so the description carries most of the burden and does well: it discloses the composite nature (three API operations behind one call), the automatic batch splitting over 200, the 2000 ceiling, and an approximate latency. It stops short of stating auth/permission requirements, which keeps it from a 5.

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 front-loaded sentences with zero waste: the operation, the routing alternative, the batching constraint, and the cost. Each sentence adds a distinct piece of decision-relevant 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?

For a six-parameter composite tool with no output schema, the description covers the operation, the alternative, batching limits, and cost. The main omission is what the call returns (e.g., run id) and permission requirements, but these are minor against an otherwise complete definition.

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 fields like case_id, status enum, complete, and is_autotest are already documented in the schema. The description only restates that each result needs a numeric case_id and a status, adding no syntax or semantic detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 precise compound verb+resource: creates a run, records every result, and completes it. It explicitly names the sibling it is not (qase_result_record) and the condition that selects it, so an agent can distinguish it from qase_run_upsert and qase_result_record without opening schemas.

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 when-to-use rule ('whole finished CI run in one call') and a named alternative with the distinguishing condition ('when the run already exists and results arrive in stages, use qase_result_record'). Nothing is left to inference.

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

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

Annotations only declare idempotentHint, so the description carries the safety burden and does so richly: workspace-wide reach, that it removes the field and its entered values from every project, that it 'cannot be undone', and that it asks the user for confirmation first. It even discloses cost/latency, well beyond what annotations provide.

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?

Front-loaded with the core action, then scope/irreversibility, then the alternative, then confirmation and cost. Each sentence earns its place with no redundancy.

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 single-parameter delete with no output schema, the description covers everything an agent needs: scope, irreversibility, confirmation behavior, and the sibling route to a narrower operation. Nothing material is missing.

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% with a single required `id` parameter, and the description only adds 'by ID'. The schema already documents the field, so the baseline 3 is appropriate.

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 ('Delete a custom field by ID') and immediately distinguishes itself from the sibling `qase_custom_field_upsert` by name. An agent can tell this apart from the upsert tool without opening either 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?

Explicitly describes the condition that selects an alternative: 'To remove it from one project only, edit `projects_codes` with qase_custom_field_upsert.' This gives both when-to-use and a named alternative, leaving nothing to inference.

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

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

With only destructiveHint=false in annotations, the description does real work: it discloses that entity/type are fixed forever after create, that fields are workspace-wide with projects_codes/is_enabled_for_all_projects scoping, and gives per-call cost and latency. It omits one important behavior for an upsert with 12 params — whether an update merges or replaces unspecified fields.

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 action, then the immutability constraint, then scoping, read alternative, and cost. No filler; each clause adds an actionable fact.

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 12-parameter, no-output-schema mutation tool it covers purpose, key constraints, scoping, read alternatives, and cost. The only notable omission is update merge/replace semantics, which leaves one gap for correct 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 schema already documents every parameter, including the id create-vs-update semantics and the projects_codes/is_enabled_for_all_projects precedence. The description largely restates what the schema already conveys, yielding the baseline 3.

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 (create or update) plus resource (custom field), and the pairing with the qase_custom_field_delete sibling is unambiguous. The added note that entity/type are required on create and immutable afterwards further pins down what this tool does versus a generic upsert.

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?

It routes the agent to alternatives for the read path ('Read existing fields with qase_project_context or qase_get') and effectively distinguishes create vs update via the id parameter. It stops short of stating when NOT to use it (e.g., use the delete tool to remove a field), so no explicit exclusions.

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

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

Annotations only declare idempotentHint, so the description carries the real behavioral load: cascading loss of result links, irreversibility ('cannot be undone'), the confirmation gate, and a cost/latency estimate. That is exactly the context an agent needs before invoking a destructive operation.

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 front-loaded sentences: impact, recommended alternative, then workflow and cost. Nothing is redundant and the destructive warning comes before the softer routing advice.

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 two-parameter delete with no output schema and minimal annotations, the description covers consequences, reversibility, confirmation behavior, and alternatives. Nothing an agent needs to call this safely is missing.

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% with both parameters documented (id as entity ID, code as project code with pattern/length constraints). The description restates 'project code and ID' without adding format or edge-case detail, so baseline 3 applies.

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 (Delete) and resource (a defect), plus the scoping keys (project code and ID). It also distinguishes itself from the sibling qase_defect_upsert, so an agent can route between the two without opening schemas.

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?

Explicitly names the alternative path ('Usually resolving it through qase_defect_upsert with `id` is the right move, so the record survives') and gives the condition that favors it. It also states the workflow prerequisite that user confirmation is requested first.

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

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

Only `destructiveHint: false` is annotated, so the description carries most of the burden and it does so well: it explains the create-vs-update switch, that severity/status labels are normalized for the caller, and gives a cost estimate (one API call, ~0.5s). It stops short of stating auth requirements or how partial updates merge with existing fields.

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?

Front-loaded with the create/update branch rule, then alternatives, then cost. Dense and mostly waste-free; the trailing latency note is mildly expendable but useful for planning.

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?

Covers the 9-parameter, nested-object surface adequately: mode selection, conditional required fields, label normalization, sibling routing, and cost. With no output schema, it could say more about the returned defect identifier, but nothing essential for a correct call is missing.

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 genuinely new conditional semantics: it says title, actual_result and severity are required when creating, which the schema's static `required` list ([code, title]) does not capture. The label-mapping note for severity/status is also 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 verb pair and resource (create or update a defect) and immediately disambiguates the two modes via the `id` parameter. It also names the sibling it is not (qase_triage_defect) and the search tool to use, so an agent can distinguish it 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 explicit routing rules: use qase_triage_defect when the defect originates from a specific test failure, and search with qql_search before filing a duplicate. The when-to-use and when-to-use-something-else conditions are both stated directly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context the annotations cannot convey: no API call, in-memory matching, ~3ms cost. It does not describe result ordering or result-count limits.

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?

Front-loaded with purpose before usage guidance and cost, and there is no filler. The inline query examples overlap with the schema's own examples, which is mild redundancy, but the single-paragraph structure is tight.

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 carries the return-value burden and does so adequately ('matching tools with their descriptions'). Both optional parameters are documented in the schema, and the cost/behavior note is present. Only result cap/ordering is unspecified.

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%, and the query examples ('milestone', 'attachment', 'suite') appear in the schema itself as well. The description adds the illustrative query terms inline but nothing about how query and category combine, so baseline 3 applies when the schema does the heavy lifting.

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 (search) and resource (the tool catalogue) plus the intent-based matching mechanism and the return value (matching tools with their descriptions). It is immediately distinguishable from every sibling, all of which are Qase domain operations rather than meta-tool discovery.

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: 'use this when you do not know which one fits, rather than re-reading the whole list.' That names the alternative behavior to avoid. It does not explicitly contrast with the closest sibling, qase_tool_help, so it falls just short of full when/when-not routing.

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

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

Annotations supply only idempotentHint, so the description carries most of the burden and delivers: runs lose their environment attribution, history filtering by that environment breaks, the action is irreversible, and the tool will ask the user to confirm first. It also gives a cost estimate (one API call, ~0.4s), which is uncommon and useful.

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 short sentences with the core action front-loaded, followed by consequences, then cost. No filler and nothing repeated from the schema.

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 two-parameter tool with no output schema, the description covers what is destroyed, that it cannot be undone, that confirmation is requested, and the operational cost. Nothing an agent needs to call this safely is missing.

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 both parameters (id, code) are already documented with format constraints in the schema. The description only restates that the call is keyed by project code and ID, adding no syntax or edge-case detail beyond the 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 and resource plus the two lookup keys: 'Delete an environment by project code and ID.' Among siblings it cleanly separates from qase_environment_upsert and from the many other *_delete tools tied to different resources.

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 makes the stakes of deleting clear (attribution loss, irreversibility) and notes a confirmation prompt, which implicitly signals caution. However, it never states when to use this versus qase_environment_upsert (i.e., to modify instead of remove), so the routing guidance is only implied.

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

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

Annotations only supply destructiveHint=false, so the description carries most of the burden, and it does add useful non-schema behavior: idempotent upsert semantics keyed on `id` and a concrete cost profile ('one API call, about 0.5s'). It does not disclose what happens to omitted fields on update (overwrite vs. preserve), which is the main remaining risk for a mutate tool.

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 short sentences, zero filler: purpose first, the decisive id rule second, the discovery hint and cost last. Nothing is buried and nothing repeats structured fields verbatim.

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 6-parameter mutation tool with full schema coverage and no output schema, the description covers purpose, create/update routing, discovery and cost — enough to call it correctly. It leaves unaddressed what the call returns on create (e.g., generated id) and the update-merge behavior, which are the only meaningful gaps.

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 schema already documents id, code, host, slug, title and description. The description's only parameter-level statement ('with `id` it updates') duplicates the schema's own id description, adding no new syntax or constraint detail. Baseline 3 applies.

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 and resource ('create or update an environment') and clarifies the domain concept ('a named target such as staging or production that runs are attributed to'). The upsert duality is resolved immediately, so an agent can distinguish this from qase_environment_delete or the other *_upsert siblings without opening the 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 the decisive routing rule — 'With `id` it updates, without it creates' — and points to qase_project_context as the place to discover existing environments, which is real guidance rather than implication. It stops short of stating when not to use it (e.g., bulk creation or deletes), so it is clear but not exhaustive.

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

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

Adds real behavioral context beyond the annotations: only Jira Cloud/Server are supported, a case accepts multiple issues while a run holds exactly one and a new link replaces it, and the whole batch costs one API call (~0.5s). The annotations already cover safety (idempotentHint, destructiveHint=false), and the description usefully discloses the replacement semantics and cost, though it says nothing about permissions or failure behavior.

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 compact sentences, front-loaded with the tool's identity and scope, then the linking model, then cost and the read-back route. No filler sentences.

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 5-parameter mutation tool with no output schema, it covers scope, tracker constraints, per-entity link cardinality, batch cost, and how to verify results. Nothing an agent needs to invoke it correctly is missing.

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% and the enums for entity/action/type are self-documenting, so the schema already carries the parameter meaning. The description's note about a run holding one issue largely restates the 'issues' schema description, adding little beyond 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?

States a specific verb pair (link/unlink) and resource (test cases and runs to Jira issues), and names the supported tracker scope, which immediately separates it from the defect/result/case tools in the sibling list.

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 a clear routing rule for the read side ('Read links back with qase_get') and explains the case-vs-run linking model, so an agent knows which path to take. It does not state when not to use this tool or contrast it with any write-side sibling, so it stops short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes beyond them with measured cost/latency data ('one API call, 0.3-0.5s; ten in sequence measured 5.3s against 1.2s for one qql_search') plus a default-behavior note about external issue links. This is genuine behavioral context an agent can use for batching decisions.

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?

Front-loaded with the core action, then the routing exclusion, then the cost rationale. Three sentences, no filler, and the most decision-relevant information (when to pick qql_search) appears early.

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 read tool with no output schema, the description covers invocation and routing well, and the schema handles parameters exhaustively. Its one gap is that it doesn't characterize the returned payload shape at all, which matters slightly more given there is no output schema to fall back on.

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 and the schema already documents id/code/fields/include in detail. The description restates entity types and the ID-lookup notion but adds no syntax or format detail beyond what the schema provides.

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?

Specific verb + resource + scope: 'Fetch one known record by type and ID', followed by an enumeration of entity types. It also explicitly distinguishes itself from the sibling qql_search, so an agent can route correctly without opening either 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?

States the precise precondition ('only when you already have the ID') and the disallowed cases ('for several, anything filtered, or a loop over IDs, use qql_search'), naming the alternative tool. This is exactly the when/when-not/alternative structure the dimension rewards.

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

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

With only idempotentHint in annotations, the description carries the burden and delivers: runs/cases survive but lose the association, downstream release reporting breaks, the action is irreversible, the user is prompted for confirmation first, and it costs one API call (~0.4s). These are concrete behavioral facts beyond anything in the annotations, and they are consistent with idempotentHint=true.

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 short sentences, front-loaded with the action, then consequences, then operational cost. No sentence is filler; each adds decision-relevant 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?

For a two-parameter destructive tool with no output schema and minimal annotations, the description covers irreversibility, side effects on related entities, confirmation behavior, and cost — everything an agent needs to invoke it safely.

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 both parameters (code, id) are already documented with patterns and constraints. The description only restates 'by project code and ID' and adds no format or validation nuance, which is the baseline case.

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 (delete) and resource (milestone) scoped by the two required identifiers, which cleanly distinguishes it from the sibling qase_milestone_upsert. An agent can route here without opening the 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?

The description gives clear context for when this matters (milestones that release reporting is built on) and notes a confirmation prompt will occur, which informs the decision. It does not explicitly name an alternative or state exclusions, so it falls short of the top score.

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

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

Annotations only declare destructiveHint=false, so the description carries most of the burden. It adds real value with the cost estimate ('one API call, about 0.5s') and the discovery path via qase_project_context, but it does not disclose the key upsert semantics — whether an update overwrites or clears omitted optional fields like status and due_date — nor what the call returns. Useful but incomplete for a mutation tool.

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 short sentences, zero filler, with the core create/update distinction and the domain gloss front-loaded before the discovery hint and cost note. Every sentence carries information an agent needs.

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 6-parameter mutation tool with no output schema and minimal annotations, the description covers mode selection, prerequisite discovery, and latency cost. The remaining gap is the effect of partial updates on unmentioned fields, which matters for an upsert but is not addressed.

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%; every parameter is already documented in the schema, including the id create-vs-update semantics and the status enum. The description adds no parameter-level detail (formats, date handling, code constraints) beyond what the schema provides, so the baseline of 3 applies.

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 or update) plus the resource, and defines what a milestone is in domain terms ('a dated marker, typically a release, that runs and cases are grouped under'). It also disambiguates the two modes: with `id` it updates, without it creates. An agent can distinguish this from qase_milestone_delete without opening either 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 the mode-selection rule (id present = update, absent = create) and a concrete prerequisite pointer: fetch existing milestones from qase_project_context before deciding. It does not state when to prefer create-over-update beyond that rule, nor name alternatives such as qase_milestone_delete, so it falls short of a full when/when-not treatment.

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

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

Annotations only supply idempotentHint, so the description carries the real burden and does so well: it discloses exactly what is destroyed (the plan only), what survives (cases and runs), the downstream consequence (anything launching by ID breaks), irreversibility, and confirmation behavior. Cost and latency are added bonuses.

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 tight sentences with zero filler, front-loaded with the core action and progressively layering impact, irreversibility, and the alternative. Every clause 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 two-parameter destructive tool with no output schema, the description covers everything an agent needs: scope of destruction, side effects, irreversibility, confirmation requirement, and the correct sibling for the adjacent intent.

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% and both required parameters are fully documented there, so the description adds no format or constraint detail beyond "project code and ID." Baseline 3 applies when the schema does the heavy lifting.

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 ("Delete a test plan") and pins the scope with "by project code and ID." It also names qase_plan_upsert as the sibling for a different intent, so an agent can route without opening either 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?

Explicitly routes case-modification intent to qase_plan_upsert and explains the prerequisite context (user is asked for confirmation). It gives a clear context for use but no explicit statement of when NOT to delete, so it stops short of the top band.

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

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

Annotations only declare destructiveHint=false, so the description must carry the behavioral load. It does add cost/latency context ('one API call, about 0.5s, growing with the number of cases'), which is genuinely useful beyond annotations. However, it never says what happens to the existing case list on update (replace vs. append) or what is returned — a meaningful gap for an upsert tool.

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 dense sentences, front-loaded with the core create/update rule, followed by the related-tool pointer and cost note. No filler and nothing redundant.

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 5-parameter upsert with no output schema, the description covers the create/update duality, object meaning, sibling routing, and call cost. The remaining gap is the update-overwrite semantics for `cases` and any return value, which an upsert tool should ideally disclose.

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 every parameter is already documented in the schema, including the create-vs-update meaning of `id`. The description's mention of `id` semantics largely restates that schema text and adds no syntax or format detail beyond it, so the baseline 3 is appropriate.

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) plus the resource, and defines the domain object plainly ('a named, reusable set of case IDs such as a smoke or regression pack'). It also names the sibling it hands off to (qase_regression_run), so the agent can distinguish it from adjacent tools without opening a 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 a concrete routing rule: supply `id` to update, omit it to create, and points to qase_regression_run for turning a plan into a run. It does not state exclusions (e.g. when to prefer qase_plan_delete or a bulk case tool), but the context is clear enough to select correctly.

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

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

Annotations only declare read-only/idempotent/non-destructive; the description adds real operational detail beyond them — each collection caps at 100, a `coverage` signal indicates truncation, and the cost profile (six API calls, 0.5-1.3s cold, 5-minute cache) lets the agent plan. No contradiction with the readOnlyHint.

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?

Front-loads the payload ('seed everything about a project in one call') before paging rules, sibling routing, and cost. Every clause carries a distinct decision-relevant fact with no filler.

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 still tells the agent what comes back (the named collections, capped at 100 each) and surfaces the `coverage` field it must inspect, plus latency/caching expectations. Nothing needed to call it correctly is missing.

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 workflow meaning the schema lacks: `full: true` should be driven by what `coverage` reports, and the cost of paging is deferred to qase_tool_help. That is genuine value beyond the field descriptions.

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 ('seed everything about a project in one call') and enumerates the exact resources covered: details, suite tree, milestones, environments, custom fields and users. It also names the siblings it is not (qase_get, qql_search), so an agent can place it immediately.

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 explicit routing rules: 'make it first when starting on a project', 'for one record by ID qase_get is cheaper', 'for filtered questions use qql_search'. Both the when and the when-not are stated with named alternatives.

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

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

Annotations only declare destructiveHint=false, so the description carries most of the load and does so well: it discloses the uniqueness constraint on code, the critical irreversibility fact that title/code/access cannot be changed later, and a cost/latency estimate (one API call, ~1.5s). These are exactly the traits an agent needs before committing to a write.

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 sentences, front-loaded with the action and constraint, followed by the sibling pointer and cost. No filler and no repetition of schema fields.

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 6-parameter creation tool with a nested settings object and no output schema, the description covers the risk profile (irreversibility, uniqueness) but never says what comes back (e.g. created project id) or how to handle a code collision. Given 100% schema coverage the remaining gap is modest.

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, but the description adds meaning beyond the schema by marking title, code and access as immutable-after-creation and restating code uniqueness as a workspace-level constraint. It does not clarify the settings object or the access/group dependency, leaving a small gap.

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 opens with a specific verb and resource ("Create a project") and explicitly routes reads to the sibling tool qase_project_context, so an agent can distinguish it from qase_project_delete and qase_project_context 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?

It tells the agent when to act deliberately ("no update endpoint afterwards... choose them deliberately") and names the alternative for reading existing projects. It stops short of stating exclusions such as permission prerequisites or what to do if the code collides, so it is clear but not exhaustive.

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

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

Annotations only carry idempotentHint, so the description does the heavy lifting: it discloses irreversibility ('no trash to recover from; this cannot be undone'), severity ranking ('most destructive call in the API'), a mandatory confirmation gate, and cost/latency ('one API call, about 0.5s'). Nothing here is derivable from the structured fields.

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?

Front-loads the destructive scope in the first clause, then adds recovery, confirmation, and cost in compact clauses. Every sentence earns its place and the ordering matches what an agent needs to decide before acting.

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?

No output schema exists and the tool has one fully-documented parameter, so the description's job is risk framing and preconditions — both are covered. An agent has everything it needs to decide whether to call this and how to prepare.

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% for the single 'code' parameter, so the schema already documents the format and pattern. The description only restates 'by code' and adds a verification step, which is marginally useful but not new semantic detail.

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 ('Delete an entire project by code') and immediately enumerates the blast radius ('every case, suite, run, result, defect and milestone in it'). This clearly distinguishes it from the granular siblings such as qase_case_delete and qase_suite_delete without opening either 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 a concrete prerequisite ('confirm the code with qase_project_context first') and the confirmation workflow ('does not proceed without it'), which is clear usage context. It stops short of explicitly routing narrower deletions to the granular delete siblings, which is the one missing piece of when-not guidance.

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

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

Only destructiveHint=false is annotated, so the description carries most of the burden, and it does add real context: it resolves cases itself, it is an open-only operation, and it costs two API calls (~1s). It stops short of stating whether it is idempotent on repeated calls or what happens if the run title collides, which are the remaining relevant traits for a create tool.

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 sentences, zero filler: the core action, the negative scope with its two routing alternatives, then the cost note. The most decision-relevant content (what it builds) 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?

With 8 parameters, no output schema, and minimal annotations, the description supplies the operational context an agent needs — what it does, what it does not do, and latency. It is near-complete, missing only guidance on combining or prioritizing the case-source parameters.

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's framing of three case sources loosely maps to plan_id/suite_ids/include_cases but adds no mutual-exclusivity rules, precedence between the modes, or fallback behavior when more than one source is supplied.

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 ('Build and start a test run') and enumerates the three accepted case sources — suite, plan, or explicit case IDs — in one step. An agent can distinguish it from qase_run_upsert and qase_ci_report 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?

Explicitly scopes the tool as an opener, not a closer ('it opens a run, it does not close one'), and names both alternatives with the condition that selects them: qase_ci_report for a finished pipeline, qase_run_upsert for hand assembly. Nothing is left to inference.

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

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

Annotations only declare idempotentHint=true, so the description carries most of the burden and does so well: scope of destruction ('the case and the rest of the run are untouched'), irreversibility ('cannot be undone'), a downstream side effect ('pass rates shift'), an interactive confirmation step, and a cost/latency estimate. Not a 5 only because it doesn't state auth or permission requirements; 'cannot be undone' is consistent with (not contradictory to) idempotentHint.

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 sentences, front-loaded with the core action and target, then routing, then consequences, then cost. No filler; every sentence adds a distinct decision-relevant fact.

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 three-parameter destructive tool with no output schema, the description covers scope of impact, reversibility, the sibling alternative, the confirmation gate, and expected cost. An agent has everything needed to call it correctly and warn the user appropriately.

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 schema already documents code, run_id and hash, and the description adds no syntax or sourcing detail (e.g., where a result hash comes from or whether it can be retrieved). It merely restates that run ID and hash identify the target — baseline 3.

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 (Delete), a precisely scoped resource (one result from a run), and the identifying keys (run ID, result hash). It also names the sibling it is not — qase_run_delete — so an agent can distinguish it from the whole-run deletion without opening a 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?

Explicitly routes the agent: discard a whole run -> qase_run_delete, and single result -> this tool. It also discloses a precondition that changes invocation behavior ('Asks the user for confirmation first'), which is usage 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.

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

Annotations only declare destructiveHint=false, so the description does real work: it discloses the batch ceiling (200), the cost profile (one API call, about 0.5s), and that status is a label only rather than a gating value. It stops short of stating what happens on re-recording a case already in the run or whether a completed run accepts results, which matters for a mutation tool with thin annotation coverage.

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 sentences, each earning its place: capability, status semantics, and alternative-tool routing, with cost last. The batch limit and the sibling routing are front-loaded where an agent will read them.

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 three-parameter write tool with no output schema and only a destructiveHint annotation, the description covers batching, cost, status semantics and the sibling alternative. The remaining gap is run-state preconditions (must the run still be open?) and duplicate/overwrite behavior, neither of which is answered by the 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 description coverage is 100%, so code, run_id and the results array (1–200) are already documented, and the description essentially restates maxItems and the status enum. The one genuine addition is the interpretive note that status is a label only, which is mild value over structured data.

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+resource with scope ('Record up to 200 results into an existing run'), enumerates the payload fields, and names the sibling it is not (qase_ci_report) together with the condition that selects that sibling. An agent can distinguish it from qase_ci_report and qase_run_complete 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 when-not rule: 'If the run does not exist yet and the job is finished, qase_ci_report creates, records and completes in one call.' This directly routes the agent between the two competing tools on a concrete state condition, and the 'one call, not one per test' phrasing tells it not to loop.

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

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

Annotations only declare destructiveHint=false. The description adds real behavioral context beyond that: the one-API-call cost model regardless of batch size, and the API's lack of approve/merge/decline endpoints. It doesn't restate the atomic all-or-nothing validation (that lives in the schema), so it complements rather than duplicates structured data.

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?

A single tight paragraph with the core purpose and sibling relationship front-loaded. Every clause carries information; density is high but not padded.

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 mutation tool with no output schema, it covers cost, field inheritance from the single-create sibling, and API limitations. It leaves return-value/reporting format and permission requirements implicit, which is a minor gap rather than a blocking one.

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 schema already documents both parameters thoroughly. The description's only added semantics is the case_id edit-vs-create distinction, which the schema also states ('Omit for a new-case draft'). Baseline 3 is correct when the schema does the heavy lifting.

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 (bulk create case reviews) and explicitly frames itself as 'the batch form of qase_review_create.' An agent can distinguish it from the single-create sibling without opening either 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 a clear selecting condition ('for proposing more than one change') and routes to alternatives: qase_review_create for the single case and qase_review_list to read status. It also rules out approving/merging/declining as UI-only. No explicit when-not-to-use beyond the batch-size condition, but coverage is strong.

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

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

Annotations only declare destructiveHint=false, so the description carries real weight here: it discloses that approval/merge/decline are UI-only (a non-obvious capability gap that prevents futile calls) and gives a latency/call-cost estimate. It stops short of describing the review's resulting state (draft vs pending) or permission requirements beyond what the schema states.

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 tight sentences, front-loaded with purpose and the case_id decision, then alternatives, then the API limitation. No filler and no repetition of schema content.

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 22-parameter mutation tool with nested step objects and no output schema, the description covers routing, the edit/create branch, alternatives, cost, and the API's missing lifecycle endpoints. Nothing an agent needs to decide and call correctly is absent.

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 schema already documents all 22 parameters, including the edit-vs-create meaning of case_id. The description reinforces the case_id branch but adds no syntax, format, or default detail beyond the schema — the baseline 3 applies when the schema does the heavy lifting.

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 ('Open a test case review') and frames it memorably as 'the pull-request flow for cases', which immediately distinguishes it from case creation. It also names the two sibling tools an agent might confuse it with (qase_review_bulk_create, qase_review_list).

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 branch condition: pass `case_id` to edit, omit it to create, and 'send only the fields that change' for edits. It routes bulk work to qase_review_bulk_create and status checks to qase_review_list, and warns that approve/merge/decline have no API surface.

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

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

Annotations supply only idempotentHint, so the description carries the destructive profile and it does so well: irreversible ('cannot be undone'), human-in-the-loop ('asks the user for confirmation first'), side-effect boundaries (case untouched, merged reviews rejected), plus a cost/time estimate. This is exactly the behavioral context structured fields do not provide.

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 compact sentences, front-loaded with the core action, then the disambiguation, then the constraints and cost. No sentence is redundant with the name, title, or schema, and the operational cost note is short enough to earn 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 2-param destructive delete with no output schema and only a single annotation, the description covers everything an agent needs: target identity, irreversibility, confirmation requirement, failure cases, and blast radius of the mutation. Nothing material is left unspecified.

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% and both params (id with exclusiveMinimum, code with pattern/length) are fully documented inline, so the schema does the heavy lifting. The description repeats only 'by ID' and adds no format, validation, or project-scoping nuance, which is the baseline expectation at full coverage.

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?

Opens with a specific verb+resource ('Delete a review by ID') and immediately disambiguates the operation from a superficially similar one ('this removes the proposal entirely — it does not decline it'). It also states the scope boundary that merged reviews are not deletable and the case is untouched, so an agent can distinguish this call from qase_review_update or qase_review_list without opening a 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 clear negative conditions: not for declining (UI-only), not for merged reviews. That tells the agent when this tool will fail. It stops short of naming a positive alternative neighbor (e.g. qase_review_update / qase_review_bulk_create) or stating prerequisites, so it is strong but not exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes further with two facts the structured data cannot convey: that approving/merging reviews has no API endpoint (UI-only), which bounds what this tool can ever return, and a cost/latency figure (~0.5s, one call). Neither statement contradicts the 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?

Three sentences, front-loaded with purpose, then the alternative-tool routing, then cost. No sentence is redundant and the most decision-relevant constraint (no API path to approve/merge) appears early.

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 nine-parameter read-only list tool with no output schema, the description supplies the decision-relevant boundary (state is observable but not actionable via API) and a cost estimate. It stops short of describing result shape or how paging behaves in practice, but the offset/limit params in the schema largely cover that, so the gap is minor.

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 all nine parameters are already documented in the schema (including status enum values, case_id and author/reviewer filters). The description only adds a light hint about using the status filter to find open reviews, which is marginal over the schema. Baseline 3 is correct.

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+resource ('List a project's reviews') plus the payload dimension ('with their current state'), and explicitly names the sibling alternative qase_get for single-review retrieval. An agent can distinguish this from qase_review_create/update/delete and qase_get 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 explicit when-to-use ('the only way to learn what happened to a review you opened'), when-not-to ('For one review by ID, qase_get is cheaper'), and a concrete usage pattern ('Filter by status to see what is still open'). Alternatives and their selecting conditions are both stated.

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

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

Goes beyond the annotations by disclosing a real side effect — changing the proposal resets all existing approvals while editing only `reviewers` preserves them — plus cost and runtime. Minor tension worth noting: an operation that silently discards approvals while `destructiveHint: false` is declared; the description resolves it for the agent, but the annotation pair is not fully aligned with the behavior.

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 tight clauses, front-loaded with the purpose, then the destructive caveat, then the capability boundary, then cost. Every sentence carries actionable information and nothing is padded.

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 22-parameter mutation tool with no output schema, the description supplies the two things an agent cannot infer from the schema — the approval-reset side effect and the fact that approve/merge/decline live only in the UI — so a caller has everything needed to invoke it safely.

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% and the schema itself already documents the reviewers-replacement/reset semantics, so the description largely restates what the parameter docstrings provide. Baseline 3 is appropriate; it adds no syntax or format detail beyond the 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 and resource ('Update an open review') plus the exact editable surface (proposed case fields, reviewers, or both) keyed by review ID. This clearly separates it from qase_review_create, qase_review_delete and qase_review_list.

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?

Explicitly routes the agent: approvals/merging/declining are UI-only and not callable here, and status is read via qase_review_list. It also gives the decision rule between editing the proposal versus only `reviewers`, which is exactly the when/when-not guidance this dimension rewards.

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

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

Goes well beyond the idempotentHint/destructiveHint annotations by disclosing the key semantic that completion is a reporting state, not a lock, and that later results still land and change counts. It also gives an operational cost estimate (one API call, ~0.4s), which annotations cannot express.

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 short sentences, front-loaded with purpose, then the non-obvious state semantics, then the alternative and cost. 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?

For a two-parameter mutation with no output schema, everything an agent needs is present: what it does, that it is non-destructive and idempotent in effect, how it interacts with later writes, and when the sibling qase_ci_report already covers it.

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% (id and code are both documented with format, pattern and bounds), so the schema carries the parameter burden. The description adds no extra meaning about the two parameters, making the baseline 3 correct.

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 ('Mark a test run complete') plus the observable outcome ('reports as finished'), which cleanly separates it from qase_run_delete and qase_run_upsert among the siblings.

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?

Names a concrete alternative and the condition that selects it: 'If all results are in hand at once, qase_ci_report does this as its final step,' implying this tool is for the incremental/standalone case. No explicit statement of when not to call it, but the routing is clear.

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

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

Annotations only carry idempotentHint, so the description properly carries the behavioral load: it discloses irreversibility, the cascading destruction of all contained results, a user-confirmation prompt, and the cost (~1 API call, ~0.4s). This is exactly the destructive-operation context an agent needs before invoking.

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 action and scope, followed by the alternative routing and the safety/cost note. Every sentence carries distinct information; no filler.

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 two-parameter destructive tool with no output schema, the description covers scope, cascade effect, irreversibility, confirmation behavior, alternatives, and cost. An agent can decide and call correctly with nothing missing.

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% (id and code both documented with format/pattern), so the schema does the heavy lifting. The description names the two keys but adds no format or constraint detail beyond it, making the baseline 3 correct.

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 ('Delete a test run'), names the exact scoping keys (project code and ID), and discloses the cascade ('together with every result in it'). It is immediately distinguishable from qase_result_delete and qase_run_complete.

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?

Explicitly frames when NOT to use it ('Rarely what you want') and routes to the right alternatives with the condition that selects each: qase_run_complete to stop accepting results, qase_result_delete to fix a single result. Nothing is left to inference.

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

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

With only destructiveHint=false in annotations, the description carries most of the burden and delivers real context: the cost profile (one API call, ~0.5s) and the ordering requirement relative to qase_result_record. It does not disclose what an update does to pre-existing run data or that update support is limited, which is a gap for an upsert of 13 parameters.

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 sentences, front-loaded with the operation and workflow role, then scoping, then alternatives and cost. No filler; the em-dash clause is dense with useful information rather than padding.

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 13-parameter mutation tool with no output schema, the description covers purpose, ordering, alternatives and cost. It omits what the caller gets back (notably the run ID needed for the subsequent qase_result_record call) and any idempotency/update-overwrite behavior, but no output schema exists so return shape is not strictly required.

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 every parameter is already documented in the schema. The description adds framing by grouping milestone, environment, plan and case list as scoping axes, but does not add syntax, defaults, or interaction rules beyond what the schema says. Baseline 3 is appropriate.

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+resource ("Create or update a test run") and immediately explains what the resource is for in the workflow ("the container results are recorded into"). It differentiates itself from siblings by naming qase_regression_run and qase_ci_report and the conditions that select them.

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?

Explicit sequencing guidance ("open it before qase_result_record") plus two named alternatives with their own selection conditions: qase_regression_run for suites/plans and qase_ci_report for finished CI jobs. The agent has everything needed to route correctly without opening any schema.

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

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

Annotations provide only idempotentHint, so the description carries the real burden and does so well: it discloses the cascade blast radius (every referencing case loses those steps), irreversibility, a user confirmation prompt, and cost/latency. These are exactly the operational facts an agent needs before a destructive call.

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 sentences, no filler: impact warning first, then safeguards and the alternative, then confirmation behavior and cost. The most decision-relevant fact (wide reach) 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 two-parameter destructive tool with no output schema, the description covers scope, alternatives, irreversibility, confirmation, and cost — everything needed to invoke it correctly and safely.

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% and both parameters (code, hash) are documented in the schema with format hints. The description merely restates them as 'project code and hash' without adding new syntax or constraint meaning, so baseline 3 applies.

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 (Delete) and resource (shared step) with the identification keys (project code + hash), which is unambiguous against siblings like qase_shared_step_upsert. An agent can distinguish it from the other *_delete tools immediately.

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?

Explicitly routes the agent: use qase_shared_step_upsert to change content rather than delete, and check references before deleting. It also flags that the operation is irreversible, giving a clear when-not-to-proceed condition.

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

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.

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

With only idempotentHint in annotations, the description carries the real burden and delivers: it discloses the cascade (cases inside and child suites deleted with history), flags that delete_cases has no effect, notes the confirmation prompt, and gives cost/latency. This is exactly the context annotations cannot express for a destructive tool.

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?

Front-loads the action, then the WARNING, then the recovery advice, confirmation behavior, and cost. Dense but every sentence carries decision-relevant information; nothing is padding.

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?

No output schema exists, yet for a destructive delete the description covers cascade effects, the misleading parameter, prerequisite context, confirmation behavior, and cost. An agent has everything needed to call it safely.

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 all three parameters are already documented. The description mentions project code and ID and reinforces the no-op nature of delete_cases, but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 ('Delete a test suite') plus the identifying scope (project code and ID). An agent can distinguish it from qase_suite_upsert and the other *_delete siblings 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 a clear prerequisite workflow ('Read the tree from qase_project_context and move what matters first') and notes it asks for user confirmation. It doesn't explicitly contrast with alternatives like qase_suite_upsert, but the destructive-warning framing makes the when-to-use condition unambiguous.

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

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

Annotations only carry destructiveHint=false; the description adds genuinely new operational context (one API call, ~0.5s cost), which helps an agent budget calls. However, for a mutation tool it omits the important update semantics — whether omitted fields like description/preconditions are cleared or preserved on update — and says nothing about the return value. Useful but incomplete behavioral disclosure.

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 short sentences, front-loaded with purpose, then the id branch, then the prerequisite pointer, then cost. Every sentence carries information an agent needs; nothing is padding.

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 should cover return behavior, and it does not — an agent cannot tell whether the new/updated suite ID comes back, which matters for nesting child suites afterward. The update-merge semantics for optional fields (description, preconditions) are also unstated. Adequate but with real gaps for a 6-parameter upsert.

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 schema already documents all six parameters including id ('if provided, updates; if omitted, creates') and parent_id ('Parent suite ID for nesting'). The description restates those same semantics for id and parent_id rather than adding format or constraint detail, so the baseline 3 applies.

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+resource ('Create or update a test suite') and immediately clarifies the domain concept ('the folder cases live in'). The upsert split is spelled out: 'With `id` it updates, without it creates.' An agent can distinguish this from qase_suite_delete and qase_case_upsert without opening a 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?

Explicitly states the branch condition selecting update vs create, and gives a concrete prerequisite/alternative path: read the tree from qase_project_context rather than guessing parent IDs. This is the rare 'when to use it and how to prepare' guidance that prevents incorrect calls.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lowered, and the description still adds useful facts: no API call, static text, about 1ms, and that it surfaces limits and irreversible actions. It does not mention caching, session scope persistence, or error behavior for a bad tool name, keeping it below a 5.

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?

Front-loaded with the core instruction and rationale, and each sentence contributes either a usage rule or a cost/benefit claim. It is slightly longer than strictly needed for a one-parameter meta-tool, with a touch of persuasive framing, but no sentence is pure filler.

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 low-complexity meta-tool with rich annotations and no output schema, the description covers what it returns (argument semantics, limits, irreversible actions, alternatives), when to call it, and its cost profile. An agent has everything needed to invoke it correctly.

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% and there is a single required 'tool' parameter, so the baseline is 3. The description's 'Pass the tool name exactly as listed' merely reinforces the schema's own wording rather than adding new syntax or format detail.

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 — 'Read the full documentation of one tool' — and explains its role relative to the rest of the tool list. It does not, however, explicitly distinguish itself from sibling help/meta tools such as qase_discover_tools or qql_help, so it stops short of full sibling differentiation.

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 a clear activation condition: read it before calling a tool for the first time in a session, which implies it is unnecessary on subsequent calls. It also frames the value proposition against blindly calling a tool ('Cheaper than one rejected call'), but names no alternative meta-tool to use in other situations.

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

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

Annotations only declare destructiveHint=false, so the description carries the real burden and delivers: it discloses an API capability gap ('no way to attach runs or results to a defect') with the workaround of embedding references in actual_result, plus cost (~one API call, ~0.5s). It stops short of covering permissions or duplicate/error behavior.

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 dense sentences, front-loaded with the action and required fields, then the capability limitation, then the alternative tool and cost. No filler and every clause carries 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?

For an 8-parameter mutation with a nested custom_field object and no output schema, the definition covers required fields, the attachment/result limitation, the alternative tool, and the per-cause batching rule. Nothing needed to call it correctly is missing.

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 schema already documents all 8 parameters including code, severity enum, attachments hashes, and custom_field shape. The description only restates which fields are required, adding no syntax or format detail beyond structured data.

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+resource+source ('Create a defect from a test failure') and names the sibling it is not for ('For a defect unrelated to a failure use qase_defect_upsert'), so an agent can route without opening either 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?

Explicit routing rule to qase_defect_upsert for the non-failure case, plus a cardinality rule ('file one defect per distinct cause') that tells the agent how many calls to make. Both when-to-use and when-not-to-use are present.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real context the annotations do not: zero API-call cost, ~2ms latency, one section per call, and the failure mode where a query naming an unknown attribute is rejected.

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?

Front-loaded with the action and the parameter, then the topic list, then the cost/rationale. Every clause carries information, though the enum list is partially duplicated in the schema and could have been trimmed.

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 documentation-lookup tool with no output schema, the description covers what is returned (reference sections), call cost, and the sequencing rule for a first query. Only the exact return shape (text vs structured) is unspecified, which is minor.

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% and the schema fully enumerates and explains all eight topic values, so the baseline is 3. The description restates the enum list but adds little syntax guidance beyond it, apart from the cross-entity field-name warning.

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?

Specific verb+resource: 'Read the QQL reference before writing a query', with the exact selector parameter named. It is clearly distinguishable from qql_search (which executes queries) and qase_tool_help (general tool help).

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?

Explicitly says when to use it: before writing a query, and specifically 'read `entities` first' when field names are unfamiliar. It also gives a concrete cost-based rationale ('cheaper than one rejected qql_search'), which is actionable routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds valuable context beyond them: per-page latency (0.5-0.9s), page-based costing, and a measured comparison against the loop alternative (1.2s vs 5.3s). It stops short of describing the result shape or pagination termination behavior.

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?

Front-loaded with the core purpose, then routing (qql_help), then the alternative (qase_get), then cost evidence. Four compact sentences, none redundant, all actionable.

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 search tool with no output schema, the description covers purpose, prerequisites, alternative routing, and cost/pagination framing. It could say more about what a page of results looks like, but nothing essential to invoking it correctly is missing.

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 all three parameters (query, limit, offset) are already documented with examples. The description's 'per page' phrasing hints at paging but adds no syntax or format detail beyond the schema, so baseline 3 is appropriate.

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+resource ('Search any entity with Qase Query Language') and enumerates scope: filtering, cross-project, sorting, aggregation. It explicitly contrasts with the sibling qase_get, so an agent can tell the two apart without opening a 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 explicit when-to-use ('the right way to fetch many records at once instead of looping over qase_get'), a prerequisite ('Call qql_help first for syntax, fields and enum values'), and an alternative with its selecting condition ('Use qase_get when you already know the one ID you want').

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