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

Beyond annotations, the description discloses that it sends JSON only, cannot upload files, asks confirmation for DELETE, returns raw API responses, and has no caching, pagination, or retries. It also states typical cost/time. This substantially exceeds what annotations alone convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than typical, but every sentence earns its place: purpose, path constraints, alternatives, body/format limits, confirmation behavior, performance, and caveats. It is front-loaded with the core purpose and structured logically, with no repetition or 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 generic passthrough tool with no output schema, the description covers path formulation, host restriction, HTTP methods, body/query, file upload exclusion, DELETE confirmation, cost, and limitations. This is sufficient for a model to decide when to call it and what to expect.

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?

All four parameters are already documented in the schema (100% coverage), so the baseline is 3. The description adds genuine extra meaning by explaining that the path must target the configured Qase host and that full URLs are refused, while also clarifying the default GET method and optional body/query.

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 a clear resource ('any Qase REST endpoint'), and explicitly frames it as the fallback for 'the few things no dedicated tool covers.' This differentiates it from the dedicated sibling tools immediately and explains the path format and optional body/query.

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 instructs to 'Prefer a dedicated tool wherever one exists' and explains why, then routes file uploads to qase_attachment_upload. This gives the agent crisp when-to-use vs. alternatives guidance with no ambiguity.

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?

Beyond annotations, the description discloses important behavior: uploads alone attach nothing, hashes are returned in input order, requests over 20 files/32 MB per file/128 MB total are refused before being sent, and there is one API call per request with cost implications and base64 inflation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and the most critical usage constraints, and it is dense rather than padded. It is slightly longer than strictly necessary and some details repeat schema descriptions, but the extra cost and performance context earns most of its space.

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 correctly explains the return value (hashes) and how those hashes are consumed by sibling tools. It covers validation limits, the local/remote filesystem distinction, and the integration path into attachments fields, so an agent has enough context to call 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?

Even though schema coverage is 100%, the description adds real selection semantics: single-file forms via file_base64/file_path plus filename, multi-file form via files, and the exact condition for choosing file_base64 over file_path. It also clarifies that hashes come back in the same order as the files.

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: uploading files and returning the hashes other tools reference. It names example content types (screenshots, logs, HAR files, videos) and distinguishes itself from siblings by noting it is the only tool that sends multipart/form-data, which qase_api cannot do.

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 gives explicit when-to-use guidance: use file_base64 unless the server is local, since a remote server cannot see the filesystem. It also names the alternative (qase_api) and why it cannot handle this case, and advises reusing hashes instead of re-uploading per case.

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?

The description discloses atomicity ('batch is validated as a whole, so an invalid item means nothing is created'), return behavior ('Returns the IDs in the order submitted'), and performance characteristics ('four times faster and one tenth of the calls'). These go well beyond the annotations, which only indicate openWorldHint and non-destructive 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?

The description is dense but every sentence earns its place: it front-loads the core purpose and sibling distinction, then explains batch behavior, return format, and performance. The structure flows logically from what to use, to how it behaves, to cost/benefit. 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?

Given the tool's complexity (nested steps, multiple enum fields, shared steps), the description covers the essential behavioral aspects that an agent must know: atomicity, return order, and the relationship to qase_case_upsert for field semantics. It also covers the performance consideration for deciding between batch and individual calls. Nothing critical is missing 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 coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it clarifies enum handling ('labels ("high", "blocker") or numeric IDs both work'), steps formats ('steps classic or Gherkin'), and the atomicity of the `cases` parameter. This enhances understanding of how parameters behave, moving beyond the schema's field-level 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?

Clearly states the tool creates up to 100 test cases in one request and explicitly positions itself as the batch form of qase_case_upsert. The verb and resource are specific, and the description immediately distinguishes it from the sibling tool, making purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use it: 'the right tool whenever more than one case is being written.' Also provides exclusion guidance: 'This creates only; to change an existing case use qase_case_upsert with its `id`.' Additionally advises splitting larger imports across multiple calls, covering both when and when-not scenarios.

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 readOnlyHint=false and destructiveHint=false, but the description adds substantive behavior: enum labels and numeric IDs are normalized by the server, steps support classic/Gherkin/shared-hash references, and direct writes may be gated by 'Test case review.' It even discloses measured latency and cost tradeoffs, which no annotation captures.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core create/update behavior, then moves through enum normalization, steps, bulk alternative, review caveat, and cost data. Every sentence carries distinct information; there is 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 21-parameter nested-object tool with no output schema, the description covers the operational decisions an agent actually needs: when to create vs. update, when to switch to bulk, how enum values are normalized, how shared steps are referenced, and how review may block writes. The tradeoff of not stating the success return payload is minor against the richness of the schema and the behavioral guidance provided.

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?

The schema has 100% parameter description coverage, so the baseline is 3, but the description adds genuinely useful cross-cutting semantics: the label-or-ID normalization rule, the boolean-accepted-for-is_flaky behavior, and the classic-vs-Gherkin step distinction. This goes well beyond restating individual parameter schemas.

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 clear verb-resource pair: 'Create or update a single test case.' It immediately explains the id-based branch that selects create vs. update, and it explicitly distinguishes itself from qase_case_bulk_create. An agent can tell 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?

The description gives explicit routing guidance: 'Writing more than one case? Use qase_case_bulk_create instead.' It also explains when to consult qase_discover_tools for review-enabled projects. This is direct when-to-use and when-not-to-use guidance, not just implied context.

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 indicate readOnly=false, openWorld=true, idempotent=false, destructive=false, so mutation is expected. The description adds valuable behavior beyond that: it guarantees no half-open run if the agent stops early, auto-splits batches larger than 200, caps at 2000 results, and states cost/latency tradeoffs versus three separate calls. No contradiction with 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?

The description is longer than average but front-loads the core purpose and usage, then layers in parameter notes, batching, cost, and latency. A small amount of redundancy exists between 'creates the run, records every result, and completes it' and the later replacement list of sibling calls, but each paragraph 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?

Given the tool's complexity, an output schema exists, and the annotations and schema cover safety and constraints, the description is complete: it explains the orchestration, alternatives, result requirements, batching limits, cost profile, and completion behavior. Nothing essential is missing 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 coverage is 100%, so the baseline is 3. The description adds some meaning by emphasizing that each result needs a numeric case_id plus a status and may carry duration, comment, stacktrace, and attachment hashes, but these map directly to schema properties and do not substantially deepen their semantics.

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 names a specific composite action ('Report a whole CI run in one call') and enumerates the three sub-steps it performs: creates the run, records every result, completes it. It explicitly distinguishes itself from qase_run_upsert, qase_result_record, and qase_run_complete, making the tool's role unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'tool for a pipeline that has just finished.' It also names alternatives with conditions: use qase_result_record when the run already exists and results arrive in stages, and qase_run_upsert when the run needs to be left open. This is exactly the routing information an agent needs.

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?

Beyond the annotations, the description discloses crucial behavioral traits: required fields for creation, server-side severity mapping, the status pass-through and dedicated resolve endpoint, the lack of ability to attach runs/results, and the cost (one API call plus a cached lookup). These are non-obvious behaviors that materially affect how the agent invokes the 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?

The description is well-structured and front-loaded with the core purpose, then covers requirements, label semantics, alternatives, a limitation, and cost. Every sentence contributes actionable information; no redundancy or filler. It is concise despite its length because it packs unique insights.

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 9-parameter tool with no output schema, the description covers all essential aspects: creation requirements, label handling, status behavior, alternative routing, duplicate prevention, and operational cost. It also clarifies a critical limitation (no attaching runs/results). Nothing an agent needs 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 significant semantic value: it explains the create vs update logic for `id`, the required-fields constraint for creation, the label-to-ID mapping for `severity`, and the resolve behavior for `status`. This goes well beyond the schema's bare descriptions and helps the agent set parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Create or update') and the resource ('defect'), and explicitly distinguishes it from qase_triage_defect. It also explains the create/update behavior based on presence of `id`, making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on when to use this tool vs alternatives: 'When the defect comes from a specific test failure, use qase_triage_defect instead.' It also advises finding existing defects with qql_search before filing a duplicate, preventing redundant calls. This is exactly what an agent needs.

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?

The description goes well beyond the annotations. It explains the activation mechanism (notifications/tools/list_changed), the in-memory matching behavior, the cost (no API call, ~3ms), and the idempotent nature (free to call as often as needed). It also warns about a potential failure mode (client not acting on the notification) and how to handle it. This is rich behavioral context that annotations alone don't 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?

The description is dense but well-organized, front-loading the core purpose and then providing usage details. It's longer than ideal, but every sentence earns its place: the search strategy, activation mechanism, fallback to qase_api, and cost note are all actionable. The only minor issue is that the cost and 'free to call' details could be seen as slightly redundant with the idempotentHint annotation, but they add practical context.

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 discovery tool with an output schema and rich annotations, the description is complete. It covers what the tool does, how to use it effectively, what to expect after activation, and how to handle edge cases. The output schema presumably describes the list of activated tools, so the description doesn't need to explain return values. Nothing an agent needs to call this 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 schema already documents all three parameters. The description adds value by explaining the query matching semantics (every word must appear in a tool's name or description) and the activation default behavior. It doesn't add much about the category parameter, but the schema's enum and description cover that adequately. The description's query guidance is genuinely useful 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?

The description clearly states the tool's purpose: find and activate hidden tools. It uses a specific verb ('find and switch on') and resource ('tools that are hidden by default'), and distinguishes itself from siblings by explaining that only core tools appear in the list and this tool discovers the rest. It also names the sibling qase_api as an alternative for a specific scenario, which helps an agent differentiate.

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 provides explicit guidance on when to use this tool: whenever a capability seems missing, search here first before concluding it's absent. It also gives concrete search strategies (use two or three words, every word must match) and explains when to use qase_api instead (if activation notification wasn't acted on). This is exemplary usage 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 declare readOnly, idempotent, openWorld, and non-destructive behavior. The description goes further by adding cost/latency data, a loop-vs-search performance comparison, entity-scoped code requirements, and default include behavior for external issue links — all useful behavioral context beyond 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?

The description is information-dense but not padded: purpose first, then usage constraints, then the alternative with concrete performance evidence. The measured benchmark numbers are slightly detailed but directly support the warning against looping.

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 five-parameter tool covering many entity types with no output schema, this description leaves little to inference. It covers invocation pattern, entity scoping, field narrowing, include defaults, alternatives, and performance tradeoffs. Only exact return shape is absent, which is not critical for a single-record fetch.

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 each parameter already has a description, so the baseline is 3. The description adds meaningful nuance: code is required for project-scoped entities but can be omitted for global ones, fields narrows the payload, and include overrides the default external-issue links for cases/runs.

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?

Clearly states the action ('Fetch one known record by type and ID') and enumerates the supported entity types, so an agent knows exactly what the tool returns. It also distinguishes itself from qql_search by noting it is for a single known record.

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 this tool ('only when you already know the ID and want a single record'). It then names the alternative (qql_search) and specifies when to use it instead: for several records, filtered/cross-project queries, or loops.

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?

Despite annotations already covering the read-only/idempotent safety profile, the description adds substantial behavioral context: cost (six API calls behind one call), cold latency (0.5-1.3s), response size (16-48KB), a 5-minute cache with ~5ms repeat calls, and the truncation/coverage semantics per collection. The warning to check the coverage field before assuming completeness is exactly the kind of behavior an agent needs to know.

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?

Every sentence earns its place, and the structure is optimally front-loaded: purpose first, then when to call, the truncation caveat, alternatives, then cost/caching details. The length looks long, but for a tool that aggregates six calls and has real cost and truncation implications, the density is justified and there is zero 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 complex seeding tool, the description covers everything an agent needs: what is returned, truncation behavior and how to detect it, how to get the full set, cost and latency, caching, and routing to alternatives. The presence of an output schema means return shapes need no description, and the annotations carry the safety profile, so this is complete rather than padded.

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. The description adds meaningful semantics to the `full` parameter beyond the schema: when to use it (collection reported as truncated), its cost model (one extra call per 100 entities), and its risk (can return thousands of items, prefer targeted tools). The `code` parameter gets no additional description-level semantics, but the schema already fully covers it. One step above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-plus-resource statement ('Seed everything about a project in one call') and enumerates the exact contents (project details, suite tree, milestones, environments, custom fields, users). It actively distinguishes itself from siblings by noting it replaces six list calls and by naming qase_get and qql_search as cheaper or better-suited alternatives for other scenarios.

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 when-to-use guidance is front and center: 'This is the first call to make when starting work on a project.' It also names concrete when-not-to-use cases with alternatives ('For a single record you already have the ID for, qase_get is cheaper; for filtered or cross-project questions, use qql_search') and reiterates the preference for targeted tools in the full parameter's schema description. 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?

Beyond the annotations, the description discloses that the tool costs two API calls behind one tool call, roughly 1s latency growing with resolved case count, and that it opens a run but does not close one. These are concrete side effects and operational traits not inferable from readOnlyHint=false and destructiveHint=false.

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 sentences with a clear flow: capability, use case, sibling alternatives, cost/latency. No filler or repetition of schema fields; 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 an 8-parameter mutating tool with a rich description, annotations, and output schema, this is nearly complete. The only gap is that the 'or' among source types is not made an explicit exactly-one-of rule, and the schema does not enforce it, so an agent could call with none or several sources.

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. The description adds value by framing plan_id, suite_ids, and include_cases as alternative 'sources' and explaining that the tool resolves cases itself, which is meaning beyond individual property descriptions. It does not detail per-parameter syntax, but the schema already carries that burden.

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 and resource: 'Build and start a test run from a suite, a test plan, or an explicit list of case IDs.' It also names sibling tools (qase_run_upsert, qase_ci_report) and clarifies what this tool is not ('it does not close one'), so an agent can distinguish it without inspecting 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 explicit when-to-use guidance ('launch a regression cycle without first querying for cases') and when-not-to-use routes: hand-assembled runs go to qase_run_upsert and finished pipelines to qase_ci_report. This is direct alternative selection, not just implied context.

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 are minimal (only hints), so description carries the burden. It discloses non-read-only nature, batching behavior, refusal of over-limit lists, cost (one API call, latency scaling with payload), and that status accepts only labels (no numeric IDs). This far exceeds 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?

Front-loaded with the main purpose, then logically builds to usage, alternatives, status rules, and cost. Each sentence adds value without redundancy or 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 tool with no output schema and complex batching rules, the description covers purpose, when to use, batching limits, alternative path, status semantics, and cost. Nothing critical is missing 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 has 100% coverage, so baseline is 3. The description adds meaningful semantics: explains status label enum, that result requires a run, and clarifies the batching parameter. It also clarifies the 'code' and 'run_id' indirectly through the run-existence context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: 'Record up to 200 results into an existing run.' It also distinguishes itself from qase_ci_report and clarifies the relationship between case and result, making it unambiguous among 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?

Explicitly says when to use qase_ci_report instead (when run doesn't exist and CI job is finished), and advises batching multiple results in one call. It also warns against exceeding the 200 limit and how to handle longer lists.

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 readOnlyHint=false and idempotentHint=true, but the description adds crucial non-obvious behavior: completing does not seal the run; the API still accepts later results and changes counts. This is a significant behavioral nuance beyond the annotations. The cost estimate also adds transparency. No contradiction with 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?

Every sentence earns its place: purpose, usage trigger, consequence, behavioral caveat, alternative, and cost. The purpose is front-loaded, and the caveat is essential context. Nothing is redundant or tangential.

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 tool with no output schema and no nested objects, the description covers all needed aspects: what it does, when to call it, the non-locking behavior, the alternative tool, and cost. An agent has everything necessary to decide and invoke 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% for both parameters (code and id), so the schema already fully documents them. The description does not add any parameter-level detail, but it doesn't need to. Baseline of 3 is appropriate because the schema carries the burden and the description adds no extra 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?

The description opens with a specific verb ('Mark') and resource ('a test run'), and states the precise effect: 'so it reports as finished rather than in progress.' It clearly differentiates from the sibling qase_ci_report by noting that tool does this as its final step, so an agent can distinguish when to use each.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'Call it once the results are in' and explains the consequence of not doing so (skewed dashboards). It also explicitly names the alternative (qase_ci_report) and the condition under which this tool is not needed, leaving no ambiguity about 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 already signal this is a non-read, non-idempotent write, and the description builds on that by explaining create-vs-update behavior, the need to open a run before recording results, and that qase_ci_report avoids leaving half-finished runs. It adds meaningful operational context without contradicting annotations, though it could more prominently surface Qase's limited update support.

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?

Five sentences with zero waste: the core operation and id-based mode switch are front-loaded, followed by lifecycle context, alternatives, and cost. Every sentence earns its place, and none of it merely repeats 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 13-parameter mutation tool with no output schema, the description covers operation mode, sequencing with qase_result_record, alternative sibling tools, optional scoping, and cost. The schema covers detailed field semantics, so the agent has everything necessary to select and invoke the tool 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 coverage is 100%, so the baseline is 3, but the description adds value by mapping id to the create/update control flow and grouping optional parameters into meaningful scoping dimensions (milestone, environment, plan, explicit case IDs). This helps an agent decide which parameters matter, even though per-field details are left to 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?

The description names a clear verb-resource pair ('Create or update a test run') and immediately disambiguates the two modes by presence of id. It also distinguishes itself from siblings such as qase_regression_run, qase_ci_report, and qase_result_record, so an agent can tell it apart 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 explicitly tells the agent when to call this tool ('open it before calling qase_result_record') and when not to: use qase_regression_run for suite/plan expansion and qase_ci_report for finished CI jobs. This is strong when/when-not 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 indicate readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the description doesn't need to restate those. It adds behavioral context by disclosing the cost (one API call, ~0.5s) and the single-call-per-node limitation, which is not available from annotations. It also hints at non-idempotency by noting the upsert behavior, though that is also clear from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are already documented. The description adds workflow-level meaning beyond the schema: it explains that parent_id should be sourced from project_context and that the returned IDs should be reused when building deep trees. This adds practical value to understanding how to combine parameters effectively, which is above the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates or updates a test suite ('the folder cases live in'), with a specific verb and resource. It distinguishes it from similar tools like qase_case_upsert by explicitly naming the resource type. The id-based create/update behavior is stated upfront, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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

The description goes well beyond the annotations by explaining API rejection behavior for missing required fields, the impossibility of attaching existing runs/results, why no link will appear, and the cost profile (about 0.5s per call, one call per defect). This gives the agent crucial execution expectations. There is no contradiction with 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?

The description is dense but every sentence earns its place: purpose, required fields, a key API limitation, alternative tool, cost, and triage strategy. It is front-loaded with the core purpose and stays focused despite covering a complex behavioral caveat.

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?

Given the tool's complexity, 8 parameters, and output schema, the description covers the essential operational context: when to use it, what the API rejects, what to expect in the UI, how to handle failure context, and how to batch triage efficiently. The output schema exists, so not restating return values is acceptable.

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. The description adds meaningful guidance beyond the schema, especially for actual_result: 'reference the failing results inside actual_result instead' and 'do not expect a link to appear'. It also reinforces that title, actual_result, and severity are mandatory, which complements the schema's required list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and resource: 'Create a defect from a test failure' and clarifies the distinguishing scope, including what the tool is not for by pointing to qase_defect_upsert for unrelated defects. This clearly separates it from sibling 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?

The description gives explicit when-to-use guidance: use for test failures, and for unrelated defects use qase_defect_upsert. It also provides practical usage advice for batch triage: cluster identical failures and file one defect per distinct cause rather than one per failed test.

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?

Beyond the readOnly/idempotent annotations, the description discloses that this makes no API call, returns static text, costs about 2ms, and is free. It also explains QQL's rejection behavior for nonexistent attributes, which is important context for the agent's subsequent query-writing 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?

The description is dense but well-structured, front-loading the crucial instruction, then listing topics, key caveats, and cost. Every sentence adds practical value, and the repeated topic list serves as an orienting summary rather than pure 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 one-parameter static-help tool with strong readOnly/idempotent annotations, the description fully covers when to call, how to call, why it matters, what it costs, and what behavior to expect. No output schema is needed because the tool returns static reference text, which the description clearly states.

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?

The schema already documents each topic in detail, so the baseline is 3. The description adds meaning by highlighting entities and enumValues as critical topics and warning that field names differ from those in write tools, which goes beyond the schema's enumerated list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear imperative—'Read the QQL reference before writing a query'—and defines the tool as the QQL syntax reference with a bounded topic set. It distinguishes itself from qql_search by positioning itself as the pre-query reference step rather than the query execution tool.

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 explicitly says to call this tool before the first qql_search, once per session, and 'rather than guessing and retrying.' It also names the sibling qql_search and provides a cost rationale for using help first, giving clear when-to-use 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the lower bar applies and the description earns credit for adding context beyond them: performance characteristics (0.5-0.9s for up to 50 records, 0.9-2.8s for 100), a one-API-call cost, and the rejection behavior for unknown attributes. This is genuinely useful disclosure that annotations do not provide, though it does not describe return structure (covered by the output schema).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the flow is logical, but the tail carries two-and-a-half sentences of benchmark numbers (0.5-0.9s, 0.9-2.8s, 1.2s vs 5.3s) that are excessive for tool selection and repeat the same point twice: 'fetch many records at once instead of looping over qase_get' and later 'Prefer one search over N single fetches'. The cost-comparison redundancy could be trimmed to a single sentence.

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 QQL search tool with cross-project scope, the description is near-complete: it covers when to use it, the error behavior for bad queries, performance expectations, and the prerequisite of qql_help. Return values are covered by the existing output schema, so nothing the agent needs to invoke it correctly is missing. Only the verbosity of the benchmark data keeps this from a 5.

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 parameter already ships with syntax examples, so the baseline of 3 applies. The description adds the advisory to 'Call qql_help first for the syntax, the fields available per entity, and the enum values,' which is useful query-parameter guidance, but it adds no format or syntax detail beyond what the schema already provides. It sits at baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource-capability statement: 'Search any entity with Qase Query Language: filtering, cross-project queries, sorting, and aggregation.' It then explicitly contrasts itself with the sibling qase_get by enumerating the non-ID questions it covers ('cases without automation', 'results that failed this week'). An agent can tell this tool apart from any sibling without inspecting 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?

It explicitly says when to use it ('the right tool for every question that is not give me this one record by ID'), names the exact alternative ('Use qase_get instead when you already know the entity and its ID'), and instructs calling qql_help first for syntax. Both exclusions and the routing condition are spelled out with concrete examples — 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.