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

Even with annotations present, the description adds substantial behavioral context beyond them: JSON-only requests, no file uploads, DELETE confirmation behavior, passthrough of raw API responses, cost/latency expectations, and no caching/pagination/retries. This is exactly the kind of operational transparency a passthrough tool needs.

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, invocation pattern, external reference, dedicated-tool preference, response behavior, file-upload limitation, DELETE handling, and performance expectations. It is front-loaded with the most 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 generic, open-ended API passthrough with no output schema, this description covers the essential operational and selection context: what it returns, what it cannot do, how it behaves for DELETE, cost/latency, and the lack of caching/pagination helpers. Nothing critical is missing for an agent 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%, so the baseline is 3. The description mentions passing the HTTP method, a /v1/ path, and optional body/query, but the schema already documents these parameters and their constraints. The description adds little new parameter-level meaning beyond pointing to the external API reference.

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 begins with a specific verb and resource: 'Call any Qase REST endpoint directly,' and immediately scopes it to 'the few things no dedicated tool covers.' This clearly distinguishes qase_api from the dedicated sibling tools, making its role unmistakable.

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 'Prefer a dedicated tool wherever one exists' and gives concrete reasoning: they normalize enums, validate arguments, and shape responses. It also names a sibling alternative for multipart uploads ('qase_attachment_upload'), giving agents clear when-to-use and when-not-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 are minimal (only readOnlyHint, openWorldHint, etc.), so the description carries the full behavioral burden. It discloses that uploading alone attaches nothing, that the returned hash must be passed on, that file_path fails on remote servers, and gives cost/performance characteristics (base64 inflation, sub-second for screenshots). This is rich, non-obvious behavior beyond 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?

Every sentence earns its place: purpose, parameter choice, usage workflow, and cost are all covered with zero filler. The critical distinction between file_base64 and file_path is front-loaded, and the 'hash must be passed on' warning is placed prominently.

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 file-upload tool with no output schema, the description is exceptionally complete: it states what is returned, how the return value is consumed by other tools, the required parameter format, the only multipart/form-data sender, reuse guidance, and performance expectations. Nothing an agent needs to correctly invoke it 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 baseline is 3. The description adds value by clarifying the required extension in filename, differentiating file_base64 vs file_path with explicit guidance on when to use each, and noting that the 'file' field is deprecated. This goes beyond the schema descriptions, warranting a 4.

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?

Description states a specific verb ('Upload') and resource ('a file'), and makes the purpose explicit by explaining the returned hash is used by other tools. It 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?

Provides clear when-to-use guidance: it tells the agent to prefer file_base64 unless the server is local, explicitly names qase_api as the alternative it is not, and advises to reuse hashes instead of re-uploading. These exclusions and conditions leave 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?

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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds valuable behavioral context: hidden tools are activated and become callable, matching happens in memory, there is no API call, and it costs about 3ms. This goes well beyond the annotations and clearly communicates side effects, performance, and cost.

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 moderately long but every sentence earns its place: it explains the problem, provides concrete examples, gives query-tuning advice, sets expectations about cost, and instructs the agent not to assume missing capabilities. The most important purpose is front-loaded, and the practical usage rules follow naturally.

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?

The description is complete for an agent to call this tool correctly: it explains why the tool exists, how to search, what activation means, when to use it as a fallback, and the cost profile. The output schema covers return values, so the absence of return-value detail in the description is not a gap.

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 three parameters. The description adds meaningful guidance about the query parameter—search by intent, matching rules, and preference for short queries—which enhances the agent's ability to use it effectively. It does not add detail about category or activate, but the schema covers those adequately.

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 a specific verb and resource: 'Find and switch on tools that are hidden by default.' It goes on to enumerate exactly what kinds of hidden tools exist, making the purpose highly concrete and distinguishing it from the qase_* sibling tools, which are the tools being discovered.

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?

Provides explicit usage guidance: search by intent, use two or three words instead of a full sentence, and 'Never conclude a capability is missing without searching here first.' It also explains the matching constraint that every word must appear in a tool's name or description, which directly informs query formulation.

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 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?

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.