Firedrill

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

Adds substantial behavior beyond the annotations: it clarifies what is NOT affected (customer agent clock, wall-clock leases, no rewind, no target execution) and warns that 'complete receipt means action recorded, not destination reached', directing the agent to inspect result.reachedUs and failures. This receipt-vs-effect distinction and the reconcile-with-exact-key guidance are exactly the kind of operational context annotations can't 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?

Front-loaded with the core action and every sentence carries operational weight (permissions, exclusions, receipt caveat, idempotency). Dense but not padded; the only cost is high information density in one block, which slightly reduces scannability.

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 10-param destructive mutation with no output schema, the description covers preconditions, side-effect boundaries, the result fields to check (reachedUs, failures), and uncertainty handling via operationKey. An agent has everything needed to invoke and reconcile 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 only 10% (only operationKey documented), so the description carries most of the burden and does well: toUs is clarified as an absolute clock target, maxEvents as the event processing cap, and the prerequisite inputs (virtualTimeUs, instance, epoch) are tied to where to read them. It still leaves some parameters (reason, service, projectId, environmentId) unelaborated, so not a full 5.

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

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

States a precise verb+resource+scope: 'Advance one active run's managed Tool clock to absolute toUs, processing at most maxEvents (1–1000) scheduled events.' No sibling tool touches the managed clock, so the agent can distinguish it immediately, and the scope (one active run, absolute target, bounded events) is explicit.

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 concrete preconditions ('Read run_services for explicit clockAdvance permission, current virtualTimeUs, instance and epoch first. Requires service-control.2 clock.advance in the retained recipe') and explicit exclusions ('Does not advance the customer agent clock, extend wall-clock leases, rewind, or execute a target'), including the non-obvious rule that invoke authority never implies clock permission.

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 establish readOnly/idempotent/non-destructive/non-open-world, and the description adds genuine operational context beyond that: the native CLI/SDK validates digest, size and media type without redirects or executing files, remote MCP does not write local files or return binary contents, and missing capture/durability must not be inferred. This is substantive disclosure that the annotations alone do not provide; it is dense and slightly cryptic but earns its place.

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 lead sentence is front-loaded and identifies the resource plus its two download affordances. The remainder is a run-on of dense clauses with terse jargon ('same-scope local CLI download template', 'exact API references') that is harder to parse than it needs to be, though most sentences carry distinct facts.

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

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

For a read-only listing tool with no output schema, the description covers the return surface reasonably (scoped API download paths, CLI template, large manifests retaining API references, no binary contents). The significant hole is the complete absence of parameter meaning for a three-identifier tool, which an agent needs in order 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 0% for all three required parameters (projectId, environmentId, runId), and the description never explains any of them beyond the phrase 'for one run'. With three undocumented identifiers and no enums, the description fails to compensate for the schema gap, leaving relationship between project/environment/run ambiguous.

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 verb (List) and resource (actual retained files/documents for one run), which is unambiguous and unique among the sibling tools. It stops short of naming any sibling to distinguish against, but the resource is distinctive enough that an agent can match it without opening a schema.

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

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

It gives real when-not guidance ('Pending uploads are not available evidence', 'Never rerun a target to retrieve evidence', 'API-only runs need not have screenshots'), which steers behavior. However, it never names an alternative tool or states the precondition for choosing this over, say, firedrill_retention or firedrill_report, so usage is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real behavioral context beyond them: the pagination contract (cursor must be replayed with the same run/scope), the fact that large records are returned as metadata pointers rather than inline, and the caveat that reassessment records are not extra executions. This is meaningful disclosure for a list tool.

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

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

Three dense sentences, front-loaded with the resource and then the operational rules. No filler, though phrases like "frozen evidence digests" and "exact authenticated API metadata pointers" are terse to the point of being opaque without prior domain familiarity.

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

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

For a read-only, non-paginated-schema-free list tool this covers pagination and pointer behavior, which are the main risks. It still leaves the assessment record's shape and the meaning of projectId/environmentId/limit unexplained, and there is no output schema to fill that 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 0% across 5 parameters, so the description must compensate. It only gestures at run and "scope" via prose, names a cursor as "nextCursor" while the actual schema property is "cursor" (a naming mismatch), and says nothing about limit, projectId, or environmentId semantics or constraints.

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

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

States a specific verb+resource: paging "versioned assessments of one run," with the additional content types (frozen evidence digests, evaluator usage). An agent can distinguish it from firedrill_reassess and firedrill_report reasonably well, though the description never explicitly contrasts those 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?

Gives genuine operational guidance — "Follow nextCursor with the same run and scope until null; a page is not the entire history" — which is the key usage rule. However, it never says when to prefer this over firedrill_report, firedrill_summary, or firedrill_reassess, so alternative selection is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description adds real domain behavior: the document is 'bounded' and 'service-owned', recipe fields may be omitted and require reference-following, and completion state must not be conflated with assessment success. The explicit 'this read does not execute the recipe' reinforces readOnly with domain-specific meaning.

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

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

Three sentences, each carrying distinct load: what is returned, how to chase omitted fields, and a semantic caveat. No filler, and the core purpose 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?

There is no output schema, so the description usefully enumerates the returned contents, and the reference-following note covers the main downstream need. Gaps remain around error/not-found behavior and the meaning of the three identifier scopes.

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 0%, so all three required identifiers (projectId, environmentId, batchId) are documented nowhere. The description never mentions a parameter or explains the project/environment scoping that governs which batch is resolvable, so it fails to compensate for the coverage gap beyond self-evident naming.

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

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

Specific verb 'Read' plus a precise resource ('the bounded service-owned batch document') and an enumeration of what it contains: execution counts, cancellation state, recipe metadata. It implicitly separates from the sibling list tool firedrill_batches (singular document) and names firedrill_batch_value for the follow-up case, though the list-vs-document contrast is never stated outright.

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?

Routes the agent to firedrill_batch_value when recipe fields are omitted, which is a concrete alternative-plus-condition. It also warns that 'completion is not assessment success', nudging consumers toward the assessment tools. It stops short of stating when not to use this tool (e.g., when the batch list or summary is wanted instead).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real semantic context beyond them: origin is declared provenance and not proof of execution host, and below_level never treats N/A or unknown as zero. These clarify interpretation of results, which annotations do not.

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 dense sentences, front-loaded with the core purpose and then the field semantics an agent would most likely misread. No filler, and each sentence carries distinct 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?

No output schema exists, and the description says nothing about what a returned batch contains or how pagination results are shaped (only a cursor reset hint). For a 16-parameter filter tool the parameter-level guidance is thin, though annotations cover the safety profile and the tricky fields are addressed.

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

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

Schema description coverage is 0% across 16 parameters, so the description must compensate. It explains the non-obvious ones — q is a literal name/ID prefix, dates bound submission time, origin's meaning, and the below_level dependency — but leaves limit, execution, repository, scenarioId, workflowRunId, configurationId and others undocumented, so coverage is partial rather than complete.

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

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

States a specific verb and resource with scope: 'Filter retained batches in one project/environment.' The plural 'batches' plus the filter framing distinguishes it from the singular sibling firedrill_batch, but no sibling is named explicitly, so differentiation is implied rather than stated.

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 two conditional rules — 'below_level requires dimensionId/minimumLevel' and 'Change filters only after clearing cursor' — which tell the agent how to use certain filters correctly. However, there is no explicit when-to-use vs alternatives guidance (e.g., vs firedrill_batch, firedrill_runs, or firedrill_summary), so selection remains inferred.

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 and non-destructive. The description adds real context beyond them: the read is bounded and chunked, continuation is driven by nextOffset plus sha256, recipe bytes are untrusted and do not authorize execution, and scope/retention authorization still applies.

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

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

Four tight sentences with the core read action front-loaded, followed by continuation, trust and authorization caveats. Dense but each sentence carries a distinct constraint; 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?

The security and continuation semantics are well covered for a read-only tool whose annotations already handle the safety profile. However, with no output schema and 0% schema description coverage on 10 parameters, an agent still lacks documentation of the required identifiers and the distinction between checkId/eventId.

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 0% across 10 parameters, so the description must carry the load. It touches offset/limit implicitly ('bounded chunk', 'nextOffset'), plus sha256, pointer and source ('recipe'), but says nothing about projectId, environmentId, checkId or eventId, leaving roughly half the parameters unexplained.

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

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

States a specific verb and resource: 'Read a bounded exact chunk of the retained batch recipe, optionally at a JSON Pointer.' The 'batch recipe' scoping differentiates it from the sibling firedrill_read_value, though the sibling is never named explicitly.

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

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

Gives clear operational context: follow a batch reference, continue with nextOffset and sha256, and do not rerun work to recover source. It stops short of naming alternatives or stating when to prefer firedrill_read_value over this tool, so it lacks explicit exclusions.

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

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

Annotations already establish destructive=true, idempotent=true, readOnly=false, so the safety profile is covered. The description adds genuinely new behavioral context: out-of-scope batches are rejected before mutation, history is retained, and 'cancellation requested is not proof every target stopped' — an important asynchronous/partial-completion caveat an agent would not otherwise 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?

Three sentences, no filler, action front-loaded in sentence one with the caveats following. Each sentence carries distinct information (action, validation constraint, durability/partial-completion note). Slightly dense but appropriately sized.

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

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

For a destructive mutation tool with no output schema, the description covers the key operational concerns: scope validation, history retention, idempotent retry (via operationKey in schema), and the caveat that cancellation is not confirmed stoppage. The remaining gap is the thin parameter documentation, but the overall operational picture is reasonably 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 only 25% — operationKey is documented with retry semantics, but batchId, projectId, and environmentId carry no descriptions. The description partially compensates by implying the scope relationship ('explicit project/environment', 'batch outside the selected scope'), but it does not explain the roles of the three undocumented identifiers, leaving a real gap.

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

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

The description states a specific verb ('cancel') and resource ('batch'), and refines it into two distinct actions: canceling unclaimed work and requesting cancellation of active customer-owned runners. It scopes to the explicit project/environment, which lets an agent distinguish this batch-cancel tool from siblings like firedrill_create_batch or firedrill_batch, though it does not name an alternative 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 conveys a usage constraint ('a batch outside the selected scope is rejected before mutation'), which implies the caller must supply a batch within the target scope. However, it never states when to use this versus other lifecycle tools, nor any prerequisites or authorization expectations. Usage is implied rather than explicitly guided.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the description's extra value is real: it discloses pagination via nextCursor and a non-obvious domain caveat that 'notification sent means provider acceptance, not delivery'. Missing is any note on authorization failure behavior or result ordering.

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

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

Three short sentences, zero filler, with the core action front-loaded and the caveat placed where a reader will see it. Every clause carries information the agent could act on.

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

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

There is no output schema, so the description is the only source of return-shape information, and it never says what a capacity request record looks like or what status values appear. Pagination and the acceptance-vs-delivery nuance are covered, but the record payload and terminal-condition detection ('when does nextCursor stop?') are left implicit.

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 0%, so the description must carry the burden, and it only partially does: 'Follow nextCursor' explains the cursor's role and the project/environment constraint explains the two required IDs. The limit parameter (default 25, max 100) is never mentioned, leaving a quarter of the surface undocumented.

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

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

Specific verb ('Read') plus resource ('saved capacity requests') plus scope ('one authorized project/environment'). The closing clause 'Does not change capacity or run simulations' implicitly separates it from the mutating sibling firedrill_request_capacity, though that sibling is never named.

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?

Usage is implied by 'Read saved capacity requests in one authorized project/environment' and the negative 'Does not change capacity or run simulations' tells the agent this is not a write path. However, no alternative is named for the write case (e.g. firedrill_request_capacity), so the agent must infer the routing itself.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: records only exist after an authorized workflow is verified, and no repository is inferred from a recipe or name. It still doesn't disclose pagination behavior or result ordering.

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

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

Three sentences, front-loaded with purpose, then the semantics, then the exclusions. Every sentence carries content, though the final negative list is slightly sprawling.

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

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

For a read-only list tool with no output schema, the description should at least hint at what a 'connection' record contains and how cursoring works. The verification caveat is valuable, but the pagination and return-shape gaps leave an agent under-informed about repeated calls.

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 0% across 4 parameters. The description clarifies that project/environment are the required scope, but says nothing about limit (max 100, default 25) or the opaque cursor, leaving pagination semantics entirely unexplained in both schema and prose.

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

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

States a specific verb and resource ('List verified GitHub repository/workflow connections') plus the scope ('explicit project/environment'), so an agent knows exactly what is returned. It also pre-empts the natural confusion with App installation / connection creation tools by stating those are out of scope.

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 negative clauses ('Does not install the App, create a connection, execute a simulation or change repository access') effectively tell the agent when this tool is NOT the right one. It stops short of naming the sibling tool to use instead for those actions, so it is clear context without explicit alternatives.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds meaningful behavior beyond them: it never publishes, never requests a workflow identity token, and never reruns an agent. This directly characterizes the absence of side effects and the token-handling boundary, which is valuable context for an agent deciding how to proceed.

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

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

Three front-loaded sentences that each carry weight: what is returned, that it is side-effect free, and where publication actually happens. Tight and well ordered, with only minor overlap between the read-only claim and the no-publish statement.

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?

There is no output schema, and the description compensates by naming the return content (publication status, verified repository metadata, check/comment URLs). The remaining gap is the two undocumented required parameters, but for a read-only tool the behavioral and return coverage is otherwise sufficient.

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 0%, so the description must carry parameter meaning, yet it only implies batchId (via 'one retained batch's' and the CLI BATCH_ID reference). projectId and environmentId are required but receive no explanation of what they scope, leaving two of three parameters undocumented.

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 (Read) and a precisely scoped resource (one retained batch's GitHub App publication status and verified repository metadata, including check/comment URLs). Clearly distinct from generic siblings like firedrill_report or firedrill_batches, though it does not name a specific sibling tool to differentiate against.

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 gives both when-to-use (reading retained publication status) and when-not-to-use, directing the agent to run 'firedrill ci report BATCH_ID' in the authorized GitHub Actions job for actual publication. It also warns against pasting workflow identity tokens into MCP/model context, closing off the wrong path.

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/idempotentHint/destructiveHint=false, so the safety profile is structured. The description still adds real context: it runs no simulation ("runs nothing"), pages are bounded, and oversized fields are truncated while retaining "exact authorized resource pointers" — output-edge behavior not present in 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?

Front-loaded with the core action and sibling routing in the opening sentences; each sentence carries information. Minor waste in restating read-only ("This is read-only and runs nothing") which the annotations already cover.

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

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

For a six-parameter, four-required tool with no output schema and zero schema description coverage, the description covers purpose, routing, and truncation behavior but leaves all parameter semantics unexplained. Adequate to identify the tool, thin for invoking 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 0% across six parameters, so the description must carry the burden, yet it never defines baselineBatchId vs candidateBatchId, nor the meaning/range of limit and cursor. Only a faint hint exists via "bounded paired-dimension page," which gestures at pagination without explaining the fields.

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

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

States a specific verb and resource with scope: "Compare two authorized batches in the same project/environment," and adds what it returns (matching counts with a bounded paired-dimension page). It explicitly distinguishes itself from firedrill_summary and firedrill_compare_pairs, so an agent can pick it without opening schemas.

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

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

Routes the agent away from itself toward siblings: "firedrill_summary for individual populations and firedrill_compare_pairs for every pair rather than summary samples." That is clear alternative selection guidance, though it frames choices around output sampling rather than stating hard when-not-to-use conditions for this tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description adds genuine traits: no target execution or assessment occurs, pagination must restart if the retained population changes, and a metadata projection preserves real nextCursor/total. These are non-obvious behaviors the annotations do not convey, though the final sentence about 'exact authorized API resource' is opaque.

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 text is short, but it is dense and jargon-heavy: 'A metadata projection preserves the actual nextCursor/total; omitted items are available from its exact authorized API resource' is convoluted and hard to act on. Some sentences earn their place, but the projection sentence does not read cleanly.

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 does usefully describe pagination stability and the projection of nextCursor/total, and it clarifies this is a pure read with no execution. But the total absence of parameter documentation for a 6-param tool leaves a clear gap for correct invocation.

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

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

Schema description coverage is 0% across 6 parameters, so the description must carry the burden and it largely does not. It references baseline/candidate broadly and mentions cursor/total via the projection, but never explains limit, cursor format, or how the four required IDs (projectId, environmentId, baselineBatchId, candidateBatchId) relate. It only partially compensates for the coverage gap.

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

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

The opening sentence gives a specific verb ('Page') and resource ('every comparison case') scoped to baseline/candidate run references, including the edge case of missing/incompatible pairs. It separates this from the evidence-reading siblings by pointing to 'report reads' for either run's evidence. A little more crispness about what a 'comparison case' is would push it to a 5.

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 redirects evidence lookups to report reads ('Use report reads for either run's evidence'), which is a real alternative-tool routing. It also gives a usage constraint for pagination ('Restart at the first page if the retained population changed'). However, there is no explicit when-not guidance and no statement of prerequisites for the batch IDs.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-structured context: it clarifies this is not an account-creation path and discloses output truncation semantics (large restriction lists are omitted and replaced with exact authorized resource pointers rather than being downgraded to unrestricted/null authority).

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

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

Three tight sentences, no filler, with the core read action front-loaded. The final clause about 'never converted to unrestricted/null authority' is information-dense but slightly cryptic in isolation, keeping it just below a 5.

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 zero-parameter read with no output schema, the description covers the essential behavior including how oversized restriction data is returned. It does not enumerate the full shape of the returned context (e.g. authority fields), but annotations carry safety and the omission behavior is disclosed, so it is largely 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it does not invent parameter-like concepts.

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 verb (read) and a concrete resource set (authenticated organization, project/environment restrictions, available authority), so the agent knows this is an inspection tool. It stops short of differentiating itself from domain siblings like firedrill_projects or firedrill_discover, which is why it lands at 4 rather than 5.

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?

There is no explicit when-to-use statement, no prerequisites, and no named alternative among the many firedrill_* siblings. The only situational hint is the negative 'Does not create an account', which clarifies what the tool is not rather than when to reach for it.

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=false, idempotent=true, destructive=false, openWorld=false. The description adds real context beyond them: it does not start the local laptop process, a queued batch is not a completed simulation, submissionOrigin/ciContext are immutable caller declarations rather than attestations, and the operation key should be retained. This is substantive async/idempotency semantics the annotations do not 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?

Purpose is front-loaded in the first sentence and each following sentence addresses a distinct operational pitfall. There is mild redundancy between 'immutable caller declarations… retain them with the operation key' and 'Remote MCP does not infer the customer's CI environment', but the text is dense and waste-free overall.

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 an extremely large nested recipe schema, 6 parameters, and no output schema, the description adequately covers operational semantics but leaves recipe construction entirely to the schema and never indicates what a successful call returns (e.g., a batch id for later polling via firedrill_batch). For a tool of this complexity, that is a meaningful 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 only 17%, so the description must compensate, and it does for the hardest parameters: it clarifies that submissionOrigin and ciContext are immutable caller declarations (not target-source or workflow attestations), that the operation key is the retention handle, and that the recipe must already be validated. It still says nothing about the recipe's internal structure or projectId/environmentId format, but adds genuine meaning for the ambiguous fields.

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 first sentence gives a specific verb pair (persist a validated recipe, queue its runs) and names the resource and scope (explicit project/environment). It is distinguishable from siblings like firedrill_validate_recipe (validation), firedrill_preview, and firedrill_batch (read a batch), though it never names those alternatives explicitly.

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?

Usage is implied rather than stated: 'a validated recipe' hints that validation precedes this call, and 'queued batch is not a completed simulation' tells the agent what to do next (continue with the customer-owned runner). But it never says when to choose this over firedrill_preview, firedrill_validate_recipe, or other batch tools.

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?

duplicate key guard

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?

Two sentences, zero filler. The atomic creation scope is front-loaded and the authorization caveat follows as a qualifier; 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?

With only two parameters, no nested objects, and no output schema, the definition covers what an agent needs to decide and call: atomic scope, idempotency via the schema's operationKey text, and the authorization gate. Return shape and conflict/duplicate-name behavior are the only meaningful omissions.

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 50%: operationKey is well documented in the schema (reuse the same key and input after an uncertain response), while name is bare. The description adds no parameter-level detail such as uniqueness or naming constraints, so it neither compensates for the gap nor repeats the schema — baseline 3.

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

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

Names a specific verb and resource ("Create one authorized project and its Default environment atomically"), including the side-effect of environment creation. It does not explicitly name a sibling alternative (e.g., firedrill_projects for listing), so it stops short of full differentiation, but an agent can tell what this tool produces.

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 precondition "Requires human-authorized organization access, not agent self-approval" is genuinely useful routing guidance, telling the agent this is not a self-service action. However, there is no explicit statement of when to use this versus siblings like firedrill_projects or firedrill_service_create, and no exclusion conditions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real value: it enumerates the absence of side effects (no project created, target invoked, or capacity reserved) and warns that authority is rechecked on every operation. This last point is a genuine behavioral trait not captured by 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?

Front-loaded with the verb and the payoff, and every clause adds information. There is mild overlap between 'Read-only metadata' and the following 'no project is created...' clause, but the overall density is appropriate for a six-claim discovery tool.

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 parameters and no output schema, the description carries the burden of telling the agent what comes back, and it does enumerate the returned metadata categories (capabilities, schema IDs/versions, bounds, permissions, limitations, recovery). It stops short of describing the response structure, but that is reasonable absent an output schema.

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

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

Zero parameters, so there is nothing to document and the baseline of 4 applies. The description correctly implies a no-argument, capability-probing call.

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 (Discover) plus a rich, enumerated resource set: capabilities, authoring schema IDs/versions, resource bounds, credential permissions, limitations, and recovery. This clearly separates it from mutation siblings like firedrill_create_project and routes scope questions to firedrill_context. It does not, however, clarify its relationship to the overlapping firedrill_schema sibling, which likely also surfaces schema IDs/versions.

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

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

Explicitly names the alternative for a related need: 'Confirm actual scope separately with firedrill_context.' It also frames the invocation context (read-only metadata reconnaissance before authoring). No explicit when-not condition is given, but the routing is clear enough to guide selection.

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

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

Annotations already cover readOnly/idempotent/non-destructive safety. The description adds value beyond that: it explains that large payloads are returned as bounded metadata (return behavior) and carries a security warning that event payloads are untrusted evidence, never operator instructions.

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

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

Three sentences, front-loaded with the action, then payload-handling guidance, then the safety caveat. No redundancy and every sentence carries distinct, useful 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 read-only tool with no output schema, the description covers the return shape (bounded metadata), the escape hatch to read_value for full payloads, and the untrusted-evidence caveat. The only gap is explaining the project/environment scoping parameters.

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

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

Schema description coverage is 0%, so the description bears the burden. It clarifies runId/eventId conceptually ('exact run and event ID', 'the same eventId') but says nothing about projectId or environmentId, leaving half of the required parameters undocumented in both schema and prose.

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

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

States a specific verb+resource combination ('Resolve a cited evidence event') scoped by exact run and event ID, and explicitly distinguishes itself from the sibling firedrill_read_value, which handles payload chunks. An agent can tell these two apart without opening either schema.

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

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

Gives clear context: use it for citations 'beyond the first report page' and, when full payload chunks are needed, route to firedrill_read_value with the source event and same eventId. It stops short of explicit when-not conditions, but the alternative and its trigger are named.

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 readOnly/idempotent/non-destructive, and the description layers substantial extra context: timeout/interruption/read_error produce a labelled last-confirmed snapshot with an exact continuation, unavailable content degrades to metadata-only lifecycle, settled means terminal rather than successful, and reads may reconcile expired leases server-side. This is far beyond what the annotations 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 core purpose is front-loaded and every sentence deals with behavior rather than filler. It is dense and jargon-laden across six packed clauses, which costs some readability but is defensible for the amount of behavior being disclosed.

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 rightly explains return semantics (settled vs metadata-only lifecycle, last-confirmed snapshot, continuation), which is the main thing an agent needs. Minor gaps remain on how the two timing parameters relate, but the risky behavioral territory is covered.

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 0%, so the description must carry parameter meaning, and it only partly does: it implies the explicit project/environment identifiers and the 30s cap (matching timeoutMs max 30000), but batchId and pollIntervalMs semantics and their interaction are left unstated. Partial compensation for a 5-parameter, undescribed schema.

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

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

States a specific verb and resource (observe one existing batch) with scope (explicit project/environment) and a hard bound (at most 30 seconds). The negative framing (starts no target, claims no work, cancels nothing, requests no assessment) cleanly separates it from create/cancel/assess 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?

The exclusions (does not start, claim, cancel, or assess) give an agent clear context for when this tool applies versus mutating siblings, and the 30s observation window is implicit guidance. It stops short of naming an explicit alternative or a when-not condition, so it is not a full 5.

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

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

Annotations already declare destructive, idempotent, and non-read-only, so the safety profile is covered. The description adds genuinely non-derivable context: it mutates synthetic state, consumes no target invocation, and is attributed to the operator rather than the target, plus the retry/reconcile guidance. Return format is left unstated but no output schema exists to cover it.

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

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

Front-loaded with the core action, then prerequisites, behavior, and caveats in five dense sentences. Every sentence carries information; the wording is terse but not padded.

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

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

For a 10-parameter destructive mutation with no output schema and 10% schema coverage, the description covers behavior and workflow well but leaves parameter semantics and the expected acknowledgement/return largely unexplained. It is adequate but has clear gaps for a tool of this complexity.

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 only 10% (just operationKey), yet the description compensates only partially: 'alias, instance, epoch and controlOperations' loosely maps to service/instanceId/epoch, and 'Save exact input/key' gestures at operationKey. The remaining seven required parameters (projectId, environmentId, runId, reason, operationId, arguments, operationKey semantics) are undocumented in both places.

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 (Apply) and resource (one explicit permitted control operation to an active run's Tool), which is more precise than most siblings. However, it does not explicitly distinguish itself from the similar-looking siblings firedrill_service_control or firedrill_service_invoke, leaving the agent to infer the boundary.

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

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

Gives a clear prerequisite workflow ('Read run_services first for current alias, instance, epoch and controlOperations') and a when-not condition ('Arbitrary reset/clock/fault operations are not implied'). It also warns against retrying as a new intervention. It stops short of naming a specific alternative tool to prefer.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description materially adds that results include complete, failed, and uncertain receipts (not a success-only view) and that results are paginated, which is genuine behavioral context beyond the structured fields.

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

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

Three short sentences, front-loaded with the operation and its scope, with no filler. The final clause about nextCursor is compact but introduces a field name that does not exist, which slightly undercuts the otherwise tight structure.

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, zero-coverage, no-output-schema list tool, the description covers what is returned (state-preserving receipts) but omits how to scope the query, what limit/offset mean, and what the response shape is. Combined with the misnamed cursor, an agent still lacks enough information to call it correctly on the first try.

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 0%, so the description must carry all parameter meaning, and it does not: the required projectId, environmentId and runId scoping fields and the limit parameter are unexplained. Worse, it instructs the agent to 'follow nextCursor' while the schema's pagination parameter is named 'cursor' and is an integer, giving an agent a name it cannot match to any field.

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

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

States a specific verb and resource ('Read retained operator interventions') bounded to 'one scoped run', and explicitly excludes adjacent concepts ('not customer-target actions or new simulations'), which separates it from sibling tools like firedrill_intervene and the simulation-related tools. An agent can distinguish it without opening any schema.

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

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

Usage is only implied: the exclusions ('not customer-target actions or new simulations') clarify what the data is rather than when to call this tool versus alternatives. It never names a sibling to prefer, nor states a prerequisite or condition that selects this tool, so guidance is present but inferential.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. Beyond that, the description adds meaningful behavior: it is metadata-only, keeps working after content expiry or deletion, and performs no side-effectful actions. It does not describe return shape or pagination, but the added constraints (retention tolerance, no content retrieval) exceed what the annotations supply.

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

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

Three compact sentences, front-loaded with the core action followed by the retention caveat and the negative boundary. No filler sentences. The negative list is dense but useful, not redundant.

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

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

With no output schema, the description carries return-value meaning, and it does so reasonably: metadata-only completeness and cleanup/recovery facts. It covers retention longevity and explicit non-behaviors. The only real gap is per-parameter meaning, which is minor for a uniformly scoped-ID read tool.

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 0% and none of the three required parameters (batchId, projectId, environmentId) are explained. "For one batch in exact selected scope" hints at a batch plus scope triple, but says nothing about ID format, relation between project and environment scope, or what "exact selected scope" means. The description fails to compensate for the coverage gap.

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

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

The description uses a specific verb ("Read") on a named resource ("metadata-only evidence completeness and cleanup/recovery facts") scoped to "one batch". It differentiates itself from siblings by explicitly excluding restore, launch, cleanup-claim, and reassess behaviors. The phrasing is jargon-heavy but an agent can distinguish it from adjacent tools like firedrill_reassess or firedrill_artifacts.

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 states the key operating condition ("Works while metadata is retained even after recipe/output expiry or deletion") and delineates when NOT to reach for it ("Does not restore content, launch a target, claim successful cleanup or reassess evidence"). These exclusions implicitly route to reassess/launch siblings, though no alternative tool is named directly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine context beyond them: determinism, that it produces a recipe rather than executing anything, that it must be reviewed/saved before admission, and that large outputs should go through the CLI continuation instead of flooding agent context.

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

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

Front-loaded with the core operation, then mechanism, then exclusions. Five sentences, each carrying information, with no filler; slightly dense but well ordered.

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 a very large nested recipe schema and no output schema, the description conveys the essential role, non-effects, and next step (review/save recipe) adequately. It leaves the deep recipe structure undocumented, but that is largely a schema concern.

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 0% across 5 parameters, so the description must compensate. It explains 'axes' (JSON Pointer paths relative to each scenario input) and 'selection' (matrix expands all combinations, seeded sample selects count cases), but says nothing about projectId, environmentId, or the structure of the large 'recipe' object, leaving significant gaps.

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 and resource ('Prepare a deterministic explicit case population') and explains the mechanism (JSON Pointer axes expanded by matrix or seeded sample). This is clear enough to distinguish it from a validation or run tool, though it never names the sibling alternatives it differs from.

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 exclusions — 'Does not run a target, allocate services, save scenarios or assess results' — which routes the agent away from batch/run/save/assess siblings, and adds workflow guidance ('Review/save the returned recipe before admission', use CLI continuation for large recipes). No sibling is named by name, but the when/when-not context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real value by defining the scope of 'nonallocating' — no target/provider probing, no Tool allocation, no capacity reservation, no evaluator-availability guarantee. It also flags the auth requirement ('Authenticated'). It stops short of error modes or failure behavior.

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

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

Two sentences, zero filler, and the affirmative definition of the operation is front-loaded ahead of the negative disclaimers. Every clause carries distinct 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 complex nested-schema tool with no output schema, the description usefully summarizes the return payload (bindings, expanded counts, bounds, admission) and draws clear behavioral boundaries. The main gap is parameter-level detail, which is assessed separately; nothing else an agent needs to decide to call 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 description coverage is 0% and there are three required params (projectId, environmentId, and a deeply nested recipe object), so the description carries the full burden. It says only 'explicit recipe/scope', which gestures at the recipe param but gives no meaning for projectId/environmentId and nothing about the recipe's nested structure. It does not compensate for the coverage gap.

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

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

States a specific verb and resource ('nonallocating preview of an explicit recipe/scope') and enumerates exactly what the preview surfaces (declared bindings, expanded counts, service bounds, advisory admission). It does not name a sibling (e.g. firedrill_validate_recipe or firedrill_materialize), so the agent must infer the boundary from the negative clauses rather than an explicit contrast.

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?

Usage is only implied: 'preview' plus the negative list ('does not probe... allocate... reserve') tells the agent this is the safe pre-flight step before a materialize/run, but no sibling is named and there is no explicit when/when-not or prerequisite statement. The routing signal exists but is left for the agent to infer.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context about oversized listings returning authorized API references and not inventing page cursors, but the wording is cryptic enough that the value is partially lost.

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?

It is short and front-loads the core purpose, which is good. However, the second and third sentences are terse to the point of opacity ('Oversized listings return exact authorized API references; no nonexistent page cursor is invented'), so they do not fully earn their place as written.

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 zero parameters and no output schema, the description carries the burden of conveying the return shape; it names the returned entities (projects and their Default environments) and gestures at truncation behavior, which is adequate. It stops short of clarifying what an agent sees when results are oversized, leaving a gap for a listing tool.

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 tool takes no parameters, so the baseline is 4 and the description has no parameter semantics to explain. Nothing misleads the agent about inputs.

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 first sentence gives a concrete verb and resource: it lists authorized projects together with their 'real Default environments', which is more specific than the bare title 'List projects'. It does not explicitly contrast itself with siblings such as firedrill_create_project or firedrill_context, so it falls just short of full sibling differentiation.

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

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

There is no statement of when to call this tool versus alternatives, nor any prerequisites. The fragment 'No missing scope means all accounts' hints at scope behavior but is too ambiguous to function as usage guidance, especially since the tool takes zero parameters.

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

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

Annotations already cover read-only/idempotent/non-destructive/non-open-world, but the description adds substantial behavior: bounded chunking, offset+sha256 continuation semantics, the caveat that a check's canonical digest differs from the serialization digest, and the hard limits (no recovery of removed content, no target invocation). These are non-obvious operational traits not inferable from 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?

Front-loaded with the read scope, then pagination, then limits; each sentence carries distinct information. It is dense and jargon-heavy ('not an omitted check's different canonical digest'), but for a 10-parameter tool the overall length is disciplined.

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 tool with no output schema and 0% schema descriptions, the description does mention returned signals (nextOffset, serialization sha256), which helps. It still does not describe the shape/nature of the returned chunk, the meaning of 'bounded', or how the nine source modes differ in practice, leaving real gaps for an agent invoking it blind.

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 0%, so the description carries the full burden for 10 parameters. It meaningfully explains the interdependent ones (offset first-omit then nextOffset, sha256 as exact serialization digest, pointer as JSON Pointer field selection, checkId pairing with check_actual/check_expected), but leaves limit bounds, projectId/environmentId/runId roles, and the source enum's practical distinctions to inference.

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 ('read') and a precise, enumerated resource set: bounded chunks of retained run output/input/scenario/configuration/target/assessment, a cited event, or check_actual/check_expected operands. An agent can tell this is a targeted evidence-extraction tool rather than a lister. It stops short of naming which sibling (e.g., firedrill_event, firedrill_artifacts) it displaces.

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 procedural guidance ('omit offset initially; continue with returned nextOffset and sha256') and a when-not ('cannot recover missing/removed content or invoke a target'), which is real exclusion context. However, across 45 siblings it never routes the agent to an alternative for the cases where this tool is the wrong choice.

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

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

Goes well beyond the annotations by disclosing that out-of-scope runs are rejected before evaluation, that the original is preserved (reinforcing destructiveHint=false), that it consumes separate evaluator capacity, that it never reruns the target, and that assessment-create authority is required. This is rich, actionable behavioral context.

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

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

Four tight sentences, front-loaded with purpose and scope, and each subsequent sentence (scope rejection, capacity cost, authority requirement) carries distinct information. Dense but not padded.

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

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

Behavior is well covered, but with no output schema and a complex nested rubric parameter, the description leaves the agent guessing about the rubric argument and the returned assessment. It is adequate on behavior yet incomplete on the inputs/outputs an agent must handle.

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 only 20% (just operationKey), and the nested rubric object is entirely undocumented. The description gestures at project/environment scope and saved evidence but adds no field-level semantics, syntax, or format guidance, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Request a new bounded assessment of saved evidence') plus scope ('explicitly selected project/environment'), which is enough to separate it from listing tools like firedrill_assessments and from firedrill_compare. The 'preserving the original' and 'never reruns the target' clauses pin down exactly what kind of assessment this is.

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?

Implied usage is present: this is for reassessing already-saved evidence without rerunning the target. However, it never names an alternative tool or a when-not condition, so the agent must infer when to prefer this over firedrill_assessments or a fresh run.

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 it discloses that candidates are retained unchanged (no mutation of inputs despite readOnlyHint=false), that operationKey must be persisted before dispatch, that pending/unavailable is provider state and never agent failure, and that scores are ordinal guidance rather than calibrated probabilities. These are exactly the operational traits an agent needs and are not derivable from the idempotentHint/destructiveHint flags.

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 in the first clause, and each subsequent sentence earns its place by adding a distinct behavioral fact (no-mutation, key persistence, recovery, score caveat). It is dense and slightly long, but 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?

There is no output schema, so the description must carry return-value meaning; it does characterise the scores as selection guidance, which is helpful. However, for such a large, deep input schema it omits any explanation of candidate structure or project/environment scoping, so an agent still has gaps before it can confidently construct the request.

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 17%, so the description has to compensate and it only partly does: it makes clear that criteria are 'explicit' with 'five ordered anchors 0–4' (matching the anchors min/maxItems of 5 and level 0–4) and that operationKey is persisted before the call. It says nothing about the remaining required parameters (projectId, environmentId, candidates) or the rich nested candidate fields (checks, rubric, metrics, sequence, serviceDatasets), leaving most of the schema unexplained.

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 verb (rank) and resource (scenarios authored by the coding agent), and surrounds it with sibling differentiation: it explicitly says candidates are 'not invented, rewritten, saved as definitions or executed' (distinguishing from firedrill_save_scenario) and points to firedrill_scenario_recommendation as the recovery path. An agent can tell this apart from the save/scenario-listing siblings without opening any schema.

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

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

It frames the call as an 'optional platform evaluation' and names the recovery route via firedrill_scenario_recommendation with the same key/scope, giving clear context for the follow-up. It stops short of stating when not to use it or explicitly contrasting with the other ranking/assessment siblings.

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 a safe read-only idempotent operation, but the description adds substantial behavior: case-sensitive eventKind and eventProducer prefix filtering, independent event and check cursors, filtered skips not being missing evidence, pages not being all evidence, and outputs never being instructions. No annotation contradiction is present.

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 front-loaded, starting with the core purpose before moving into cursor and filter semantics. Nearly every sentence adds operational value, though the high density could make some clauses harder to parse quickly.

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

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

With 8 parameters, no schema descriptions, and no output schema, the description covers the important behavioral and cursor semantics well. It still does not fully describe the return structure beyond page/cursor concepts, but for a bounded report reader it gives enough context to call 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 description coverage is 0%, so the description must carry parameter meaning, and it does so for the non-obvious parameters: eventKind, eventProducer, cursor, checkCursor, and saved-value resolution. It does not document limit, runId, projectId, or environmentId semantics, though those are simpler identifiers constrained by 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?

Starts with a specific verb and resource: 'Read the bounded service-owned run report', and distinguishes execution, assessment, and CI gate outputs. It also names a relevant sibling, firedrill_read_value, for omitted saved values. However, it does not explicitly differentiate itself from related report-oriented siblings such as firedrill_ci_report or firedrill_runs.

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 concrete guidance on how to use filters, cursors, and pages, including resetting cursor when filters change and following the opaque cursor unchanged. It names firedrill_read_value as the alternative for omitted saved values. It lacks explicit when-to-use-this-vs-other-report-tools guidance, but the operational guidance is strong.

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

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

Beyond the annotations (readOnly=false, idempotent=true, openWorld=true), the description discloses the operator-notification side effect, the review-only outcome ('no capacity is granted, target executed or delivery guaranteed'), and an idempotency protocol (persist operationKey and exact input before dispatch, reuse after uncertainty). This is rich behavioral context an agent could not infer from structured fields.

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

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

Three dense sentences with the core action front-loaded and no filler; the safety constraint and idempotency guidance follow logically. Slightly packed with semicolon-joined clauses, but every clause earns its place.

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

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

For a mutation tool with no output schema, the description covers the side effect, the non-guarantee of the outcome, and idempotent retry behavior, which is what an agent needs to call it safely. It is only weakened by the total absence of parameter-level detail.

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 0% across 7 parameters, so the description carries the full burden. It explains operationKey's role as a persisted idempotency key and implicitly maps the resource enum ('runs', 'services', 'storage'), but leaves requestedCapacity (units?), message, replyTo, projectId and environmentId entirely unexplained.

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 gives a specific verb and resource: 'Save a scoped request for more shared runs, synthetic Tools or storage capacity and notify the configured operator.' This clearly distinguishes it from read-side siblings like firedrill_capacity_requests, but it never names that sibling to make the contrast explicit, so it stops short of a 5.

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 provides an affirmative trigger ('Requires user intent') and concrete exclusions ('do not include credentials or simulation contents'), which is genuine when-to-use guidance. However, it never names an alternative tool or states when a different sibling should be chosen instead, so it lacks explicit 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?

Beyond the readOnly/idempotent/non-destructive annotations it adds real behavioral context: preview is gated on current data:delete authority, fences/deletes nothing, expired or deleted content does not surface as an empty success, backups have separate retention, and no deletion/cascade/reconciliation/credential issuance is exposed. The phrasing is hedged and indirect ('advertised', 'never truncated consent'), which slightly blunts otherwise rich disclosure.

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

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

Purpose is front-loaded, which is good, but the remainder is a dense chain of clause-heavy, abstract sentences with overlapping negatives ('No deletion, cascade consent, reconciliation, target execution or credential issuance is exposed') that an agent must parse slowly. Some wording earns its place; several phrases are redundant restatements of 'read-only'.

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

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

With no output schema, the description carries the return-semantics burden and does so for the surprising cases (expired content is not an empty success; backups separate) plus pagination behavior. Permission requirements are flagged. Remaining gaps are the per-parameter details and any routing versus firedrill_lifecycle/firedrill_preview.

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 0% on a nested oneOf with effectively eight distinguishable fields. The description names the three action modes and mentions metadata cursors, but never explains id, kind, limit, or removalId (including its removal_<hex> pattern), so it only partially compensates for the coverage gap.

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

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

The opening sentence names a specific verb (inspect) and three concrete resources (data-lifecycle policy, retained metadata, removal receipt), which maps cleanly onto the three oneOf request variants. It is less clear at differentiating from siblings with similar scopes such as firedrill_lifecycle or firedrill_preview, which the description never mentions.

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 states usable conditions ('Available even in readonly mode') and an explicit when-not: removal is performed by human owners through CLI/SDK confirmation, not this tool. It does not, however, contrast itself against any named sibling tool, so routing among the ~45 related tools is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real behavioral context: 'Large fields become explicit metadata references' describes the return shape, and 'clear cursor when changing filters' describes pagination etiquette. It does not disclose rate limits or auth requirements, but it goes meaningfully 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?

Front-loaded with the core purpose in the first clause, then dense but relevant supporting clauses. The semicolon-separated run-on is slightly heavy for one paragraph, but every clause carries information and nothing is 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 17-parameter tool with 0% schema coverage and no output schema, the description is not complete enough: it explains purpose, cursor handling, and a few params plus a hint about metadata references, but omits the meaning of most filters and gives no sense of the result shape. Adequate to start invoking, but gaps remain.

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 0% across 17 parameters, so the description must carry the load and only partially does. It usefully explains the opaque ones — 'q is a literal run/scenario ID or scenario-name prefix' and 'Dates and origin refer to batch submission' — but leaves roughly a dozen params (issue, execution, minimumLevel, dimensionId, repository, workflowRunId, etc.) undocumented. The high-value clarifications on ambiguous params lift it above a bare minimum.

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

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

States a specific verb+resource: 'Filter actual executions in one authorized batch,' and clarifies the resource granularity with 'Each run is one scenario/configuration/repetition,' which distinguishes runs from the sibling firedrill_batches/batch tools. It stops short of explicitly naming an alternative sibling, so it is clear but not fully differentiated.

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?

'Clear cursor when changing filters' and 'read the selected run's report/value for evidence' give implied usage and a soft routing hint toward other tools, but there is no explicit statement of when to use this tool versus firedrill_batches, firedrill_batch, or firedrill_batch_value.

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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond them: the scenario is 'immutable', stale bases conflict (optimistic concurrency), and 'history is never overwritten', which explains the append model and why operationKey must be retained.

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

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

Three dense sentences with the core purpose front-loaded and the concurrency/immutability constraints following. Almost every clause carries information, though the middle sentence packs three separate instructions together.

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

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

For a mutation tool with no output schema and a very deep nested scenario schema, the description covers the behavioral essentials (immutability, concurrency conflict, idempotency key) but says nothing about what the scenario object must contain or the meaning of projectId, leaving a meaningful gap for correct invocation.

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

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

Schema description coverage is only 20% (just operationKey), so the description must carry more. It usefully explains expectedRevision (null vs current revision), environmentId (must be authorized) and operationKey retention, but leaves the entire large nested 'scenario' object and projectId undocumented, so compensation is partial.

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

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

States a specific verb and resource ('Save one immutable project scenario') and scopes it negatively by excluding target binding, batch, Tool allocation and assessment. This lets an agent separate it from the batch/tool siblings, though it never names a direct alternative such as firedrill_create_batch or firedrill_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?

Gives actionable invocation guidance: pick an authorized environment, pass expectedRevision null for a new ID versus the current revision for an append, and retain operationKey before dispatch. The creation-vs-append branch is the key usage decision, but no alternative tool is ever named, so the 'when not to use this' dimension is absent.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so that ground is covered. The description adds genuinely new behavior: oversized definitions return authenticated resource/JSON Pointer references rather than a truncated recipe, and definitions remain project-owned even when environment-scoped. It stops short of describing auth requirements or the normal return shape.

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

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

Three tight sentences with purpose front-loaded and no filler. The phrasing is jargon-dense ('authority context', 'truncated executable recipe') which costs some immediate legibility but every sentence carries information.

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

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

For a read-only tool with no output schema and four parameters at 0% schema coverage, the description tells the agent about the oversized-definition edge case but not the ordinary return payload or the revision identifier format. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must carry the load. It partially compensates by explaining environmentId's role as authority context for environment-restricted identities and implying projectId is the definitions owner, but it never explains the 64-hex 'revision' format or the projectId/scenarioId relationship.

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

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

States a specific verb and resource: 'Resolve one exact saved scenario revision.' The words 'one exact ... revision' distinguish it from the sibling listing tools (firedrill_scenarios, firedrill_recommend_scenarios), though no sibling is named explicitly.

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 one conditional rule ('Environment-restricted identities must select environmentId as authority context'), which is real usage guidance for a subset of callers, but says nothing about when to use this tool versus firedrill_scenarios or firedrill_save_scenario, and no prerequisites are stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description adds non-obvious behavior: 'Pending reads never resend provider requests' and a disclaimer that recommendations are not target executions, coverage guarantees, or calibrated probabilities. That is genuine semantic context beyond structured fields, though error/not-found behavior is unstated.

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 dense sentences, front-loaded with the core read action and scoping, no filler. Some phrasing is jargon-heavy ('handle', 'caller-authored') and could be plainer, but every sentence carries information.

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

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

No output schema exists, but the description compensates by characterizing what recommendations are and are not, and by noting that pending reads do not re-issue provider requests. Combined with read-only annotations and explicit project/environment scoping, an agent has enough to call it correctly and interpret the result.

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

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

Schema coverage is only 25% (only operationKey is documented), so the description carries weight, and it does: it maps 'by ID' to recommendationId and the operation-key recovery path to operationKey, and adds the mutually-exclusive 'select exactly one handle' rule that the schema does not express (the schema permits both simultaneously). Pattern/min-length constraints remain schema-only.

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

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

States a specific verb and resource ('Read one exact durable scenario recommendation') and names two retrieval modes (by ID, or by recovering the original operation key). It implicitly separates itself from the plural sibling firedrill_recommend_scenarios by emphasizing 'one exact' read, but never names an alternative tool, leaving that differentiation to inference.

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?

'Select exactly one handle' gives an invocation constraint, and the operationKey param description advises reusing the key after an uncertain response, which is real usage guidance. However, there is no explicit statement of when to prefer this tool over firedrill_recommend_scenarios or firedrill_scenarios, so alternatives remain implied rather than stated.

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

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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, so the safe-read profile is covered. The description adds real behavioral context beyond that: unused definitions stay visible, lastExecution is nullable, and large definitions are returned as exact resource references to avoid filling context. That last point in particular tells the agent something about the return shape it would not otherwise 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?

Dense but largely front-loaded, with the primary verb+resource in the first clause and no redundant restatement of the name. Phrasing is occasionally compressed to the point of opacity ("with nullable lastExecution in selected environment"), but every sentence carries information.

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

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

For a 7-parameter list tool with no output schema and no parameter descriptions, the description should do more: pagination semantics, the limit default, and the meaning of the evaluation/sequence enums are all missing. It does cover the environment restriction and the resource-reference return behavior, so it is adequate but visibly incomplete.

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?

With 0% schema description coverage and 7 parameters, the description carries the full burden and only partially meets it. It loosely conveys q (literal name/ID prefix), evaluation, sequence, and environmentId, and pagination is implied by "Page", but limit, cursor, and projectId are never named and the enum values (quality/exact/observation, single/sequence) are left unexplained.

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

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

States a specific verb and resource ("Page project-owned immutable scenarios") and names the filtering axes, so an agent knows it is a paginated read/list operation over scenarios. It does not, however, explicitly distinguish itself from close siblings like firedrill_scenario or firedrill_recommend_scenarios, so an agent must infer the routing.

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?

"Select environmentId for restricted identities; no execution is required" gives conditional guidance and clarifies a when-not (running a scenario), which is useful. But there is no explicit statement of when to choose this over firedrill_scenario or the recommendation siblings, so usage is implied rather than prescribed.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuine beyond-annotation behavior: local $refs resolve against the same root document, large nodes return explicit child pointers rather than flooding context, and that schemas are not private runtime source.

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 dense sentences, front-loaded with the primary read action and following with constraining caveats. No wasted filler, though the density leans jargon-heavy.

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 and 0% schema coverage, the description does well on ref resolution and large-node behavior, but leaves the required 'id' parameter and the return shape unexplained. Adequate but with a clear gap for a tool whose selection hinges on that enum.

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 0%, so the description must compensate. It explains 'pointer' as an RFC 6901 node and 'sha256' as an optional root hash, but the required 27-value 'id' enum — the most important parameter — receives no explanation at all.

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 (Read) and resource (canonical structural input JSON Schema), plus the exact-node variant via RFC 6901 pointer. It is distinguishable from siblings like firedrill_validate_recipe and firedrill_preview, though it doesn't name them directly.

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 signals when this tool isn't enough: 'Cross-field rules require canonical preview/validation' and 'discovery does not grant authority or prove execution,' pointing to preview/validation and discovery alternatives. Clear context, though it stops short of naming exact sibling tools.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description goes further by disclosing return behavior beyond annotations: inputs/results are omitted and replaced with byte counts, hashes and JSON pointers, and no pagination exists. It stops short of covering error behavior or any auth requirements.

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?

Purpose is front-loaded in the first sentence, followed by the metadata scope, the pagination note and the exclusion list, with essentially no filler. The exclusion sentence is long but each clause rules out a distinct plausible misconception, so it 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?

With no output schema, the description correctly compensates by describing what the response contains and what it deliberately omits, and it clarifies pagination expectations and side-effect boundaries. The remaining gap is the complete silence on the three required parameters and lack of explicit sibling routing.

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 0%, so the description carries the full burden of explaining runId, projectId and environmentId, and it says nothing about any of them. The names are largely self-explanatory and the schema supplies type and length constraints, but no added meaning (relationships between project/environment/run, format expectations) is provided.

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 gives a specific verb ('Inspect') and a precise resource ('retained sequence execution and every retained step identity, phase and poll count'), which is far more than the ambiguous tool name 'firedrill_sequence' conveys. It indirectly differentiates itself from siblings by stating what it does not do, but never names the sibling an agent should use for those other actions (e.g. firedrill_advance_time, firedrill_runs).

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?

Usage is implied: an agent should call this to inspect a retained sequence. The trailing negations ('Does not advance steps, run targets, restore services, assess outcomes or expose runner authority') function as useful when-not guidance that prevents misuse. However, no alternative tool is named for those excluded operations and no prerequisites for the call are stated, leaving routing 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 idempotentHint=true, destructiveHint=false, readOnlyHint=false, so the safety profile is covered. The description adds non-obvious behavior: only project-owned IDs are published, no instance/grant/agent side effects occur, partial or uncertain receipts must be retained, and fidelity is limited to a declared semantic/MCP subset plus read-only record UI rather than vendor REST/UI emulation.

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

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

Front-loads the core action, then requirements, then explicit non-actions, then recovery, then the fidelity caveat. Dense but every clause carries information; the final sentence on tool fidelity is somewhat broad and could be trimmed.

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

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

For a six-parameter, no-output-schema mutation tool, the description covers prerequisites, idempotency/recovery behavior, and blast radius. Return-value expectations are not described, but the recovery-with-key instruction largely substitutes for that for an agent operating under uncertainty.

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 only 17%, so the description must compensate. It explains releaseDigest (comes from catalog discovery), operationKey (must be saved and reused), and the initialData choices ('explicitly empty or synthetic starter dataset'), but projectId, environmentId, and catalogId are never characterized beyond being required.

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

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

States a specific verb and resource with scope: 'Acquire one exact qualified built-in release into the selected project's private build and explicitly empty or synthetic starter dataset.' It further separates itself from siblings by declaring what it does NOT do (allocate an instance, issue a grant, execute an agent), which distinguishes it from service_invoke/service_create/service_control without opening their 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 concrete preconditions ('Requires the releaseDigest returned by catalog discovery and a saved operationKey') and an explicit recovery path ('recover with catalog_acquisition_by_key using the same scope/key, never silently select latest or create a replacement'). It stops short of naming the full set of alternatives an agent might weigh, but the when-to-use and never-do guidance is unambiguous.

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

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

Annotations declare idempotentHint=true and destructiveHint=false but do not explain the execution model. The description adds real value: isolated disposable instances, a retained receipt, no change to publication status, and the caveat that it does not claim universal service fidelity. The operationKey recovery instruction is consistent with the idempotency annotation rather than contradicting it.

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

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

Four short sentences, front-loaded with the core action and followed by scoping caveats and the recovery instruction. Every sentence carries content, though 'does not claim universal service fidelity' is slightly obscure phrasing that costs a bit of clarity.

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 nested-schema, non-read-only tool with no output schema, the description covers the important behavioral facts (isolation, receipt, publication untouched) but says nothing about what the receipt contains, what happens to instances on failure, or how expectations mismatches are reported. The cardinality limits sit in the schema, so their absence is acceptable, but the result contract is thin.

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 only 20% – only operationKey is documented in the schema, and the description repeats that same recovery guidance while adding nothing for projectId, environmentId, buildId, or the deeply nested suite object. The suite's cases/steps/expect/records structure carries the tool's entire semantics and is left for the agent to infer from the schema alone.

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 concrete verb+resource: run operation/expectation fixtures against an exact private service build in isolated disposable instances. The phrase 'does not change publication status' implicitly distinguishes it from firedrill_service_publish, and 'executes authored service code, not the customer agent' distinguishes it from agent-level assessment tools. It stops short of naming siblings explicitly.

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?

'This executes authored service code, not the customer agent' gives a useful boundary against the agent-facing tools, but there is no explicit guidance on when to use this versus firedrill_service_invoke, firedrill_service_acquire, or firedrill_service_control. Usage is implied by the phrase 'supplied operation/expectation fixtures' rather than stated as a decision rule.

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 rich behavioral traits: reset/rewind increment epoch, fence old grants, preserve history, and do not reset external agents, databases, or provider state. It also clarifies extend semantics, clock mutation risk, destroy semantics, operation-key recovery, and that no grant/credential creation is exposed.

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 purpose and action list, then layers in constraints. It is dense and information-rich, though the long compound sentences could be easier to scan; nearly every clause carries useful guidance.

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 control tool with rich annotations, a nested action-based schema, and no output schema, the description covers critical behavioral and usage details. It does not describe return values or response structure, which is a minor gap given the absence of an output schema.

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

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

The schema has low description coverage, so the description carries the burden and adds meaningful semantics for actions, snapshotId in reset/rewind, expectedExpiresAt/expiresAt in extend, and operationKey recovery. It does not cover every nested field (e.g., projectId, environmentId, instanceId, epoch) in detail, but the action-specific mapping is strong.

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 and resource: controlling an exact manual service instance/epoch. It enumerates the supported actions (snapshot, reset, rewind, clock, pause, resume, extend, destroy), making the tool's scope immediately clear and distinguishable from related service 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 clear usage context and important exclusions: reset/rewind restore modeled state only, extend does not resume compute, destroy is not record deletion, and the run-owned lifecycle rejects this path. It does not explicitly name alternative sibling tools, but the constraints are strong enough to guide selection.

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 declare a non-read-only, idempotent, non-destructive write; the description adds genuinely new context beyond that: it consumes 'bounded service capacity, not a payment' and that 'no sample data/actor is inferred.' These clarify cost/consumption semantics not present in annotations. It does not elaborate on the operationKey/idempotency relationship beyond what the schema already says.

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

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

Three dense sentences with no filler; the core allocation behavior is front-loaded, followed by capacity semantics and the recipe alternative. The phrasing is jargon-heavy but every sentence adds 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 6-required-param mutation with no output schema and low schema coverage, the description covers purpose, capacity, and the recipe alternative but omits the meaning of ttlSeconds and the identity params, and says nothing about the return (e.g., instance id/handle) an agent needs to proceed.

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

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

Schema coverage is only 13%, so the description carries most of the burden, and it compensates partially by clarifying that seed and actor operations must be explicit and that build/dataset are exact and immutable. However, ttlSeconds, projectId, and environmentId get no explanation in either schema or description, leaving real gaps.

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

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

States a specific verb and resource: 'Allocate one manual service instance from an exact immutable build and optional dataset.' This clearly distinguishes it from sibling tools like firedrill_service_acquire or firedrill_service_invoke, though it never names those alternatives explicitly.

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 an explicit when-not and alternative: 'For independent recipe cases bind services in the recipe instead; the runner allocates isolated run-owned instances.' That routes the agent away from this tool for recipe-driven cases, but no positive trigger conditions or prerequisites (permissions, project/environment context) are given.

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 destructive=true, idempotent=true, readOnly=false, so the safety profile is covered. The description adds real context beyond them: it discloses that the call 'may mutate canonical state/events,' explains that operationKey enables durable reply recovery, and distinguishes it from authoredIdempotencyKey's manifest contract. It still omits error/return behavior and rate/permission constraints.

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, front-loaded with the core action, then constraints and idempotency semantics. Dense with domain jargon but every sentence carries information; nothing is padded.

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

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

For an 8-parameter mutation tool with no output schema and only 25% schema coverage, the description covers mutation, idempotency, and the run-owned exclusion but says nothing about the arguments payload, return/reply format, or permission requirements. Adequate but with clear gaps for a tool of this complexity.

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

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

Schema coverage is only 25%, so the description must carry weight. It adds genuine meaning for the two key parameters (operationKey for durable reply recovery vs authoredIdempotencyKey for the manifest idempotency contract) and gestures at 'exact epoch.' But six parameters (projectId, environmentId, instanceId, operationId, arguments, epoch) remain unexplained in both schema and description, leaving a substantial gap.

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

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

The description states a specific verb and resource: 'Invoke one authored operation on a manual instance at its exact epoch.' It also scopes it against run-owned instances, distinguishing it from the run-oriented siblings. It doesn't explicitly name the sibling alternatives (e.g. service_control, service_read), so it stops short of a 5.

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 a clear when-not signal ('Run-owned instances reject this operator path') and clarifies that a manual probe is not execution/assessment evidence, which helps route the agent. However it never names a preferred alternative or states positively when this is the right tool, so usage is implied rather than directed.

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 the write/idempotent/non-destructive profile, so the bar is lower. The description still adds real behavioral context: datasetPolicy performs uniqueness/reference/count checks, validation 'is not vendor fidelity or independently verified import consent,' the tool never reads host paths, and it returns retained IDs/digests and validation metadata rather than source. Side-effect boundaries (no instance allocation, no agent execution) are also disclosed.

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

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

Purpose is front-loaded in the first sentence, followed by compact clauses on policy, metadata, validation caveats, path scope, and return shape. The jargon is dense but each sentence carries distinct information; only the string of negative caveats borders on redundant.

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

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

Given a complex polymorphic schema and no output schema, the description covers purpose, both action modes, policy validation semantics, metadata scope, validation limitations, path isolation, and return contents. An agent has enough to select and invoke it correctly; remaining gaps are minor per-field details already structurally encoded in the schema.

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

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

Schema description coverage is 0% and the single top-level parameter is a dense polymorphic request, so the description must carry semantics. It clarifies the two request shapes (service source vs seed dataset), the meaning of datasetPolicy constraints, and what dataset metadata records (provenance and version-pinned cross-dataset mappings). It is silent on several nested fields (entryPoint, files, buildId, environmentId), which the enum/const-driven schema documents structurally but without prose.

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 (Publish) and two distinct resources: 'private service source' and 'immutable seed dataset'. This maps cleanly to the schema's two request variants (build vs dataset). It does not, however, name or contrast any sibling such as firedrill_service_create or firedrill_service_invoke, so differentiation is left to inference.

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?

Usage is implied rather than stated: 'Never reads host/repository paths' and 'Does not allocate an instance or run an agent' implicitly bound what this tool is not for, which helps contrast it with allocate/run-style siblings. But there is no explicit 'use this when… instead of X' guidance and no prerequisites or preconditions named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real operational context on top: filters apply before pagination, cursors must be cleared when filters change, epoch must be retained while paging observation, catalog metadata is unpaginated while other pages are bounded, and responses contain no source/credential dumps. It does not disclose auth/permission requirements or how conformance/run_services behave.

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?

Roughly 110 words with no filler, and the core capability statement is front-loaded ahead of the operational caveats. It is dense to the point of terseness, however — semicolon-chained fragments like 'Read build includeManifest or one operationId' are grammatical shorthand rather than clean prose.

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 exposing ~19 distinct actions with no output schema and near-zero schema descriptions, the entry needs more disambiguation than it provides. Several actions (conformance, run_services, pending, observation, history, dataset) are only glancingly or not at all described, so an agent may not know what each returns, even though pagination and scope notes partially cover the shared mechanics.

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 effectively 0% across a large discriminated union, so the description must carry the load. It partially does: it explains the build action's includeManifest and operationId ('authoritative authored contracts') and touches filters, cursor, and epoch semantics. But the majority of variant-specific fields (rowQ, pendingQ, activityQ, namespace, activityKind, kind, order, source, bindingId, evidenceCursor) get no explanation, leaving clear gaps.

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 opening clause names specific verbs (discover/inspect/read) and enumerates the resource classes it covers: catalog metadata, acquisition receipts, builds/datasets, instances/history, and run-service evidence. That is enough to separate it from write-side siblings like firedrill_service_acquire or firedrill_service_publish, though it never names an alternative tool explicitly and leans on undefined jargon ('qualified', 'authored contracts').

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 concrete routing advice among the tool's own actions: 'Use instance_history for newest instances with search/status/lifecycle filters; instances retains legacy ascending numeric pages.' That is genuine when-to-use guidance, but it offers no exclusions or comparisons against the other firedrill_service_* siblings, so the agent must infer read-vs-write boundaries.

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 read-only, idempotent, non-destructive behavior, and the description adds substantial behavioral context beyond them: bounded paging, oversized-group handling that retains population facts and exact API pointers, metric handling rules (zero/negative valid, absent values not zero, units not pooled), rubric score interpretation, and the fact that task measurements change no gate.

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?

It front-loads a purpose sentence, but then packs many caveats into semicolon-heavy clauses and cryptic phrases such as 'Task measurements change no gate.' The density reduces readability even if much of the content is relevant for a complex summary tool.

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

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

No output schema exists, so the description must carry return-value context, and it does describe paging, oversized groups, metrics, and rubric scores. However, required identifier parameters and the input cursor/limit semantics are left unexplained, leaving gaps for correct invocation.

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

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

Schema description coverage is 0% across five parameters, so the description must compensate, but it only indirectly touches pagination ('bounded page', groupPage.nextCursor) and never explains projectId, environmentId, batchId, limit, or the input cursor. It also references taskMetrics, which is not an input parameter in the schema.

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

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

States a specific verb, 'Read', and specific resources: complete batch counts, repeated-trial groups, missing evidence, and exact-check denominators. It does not distinguish itself from many siblings such as firedrill_batch, firedrill_batches, or firedrill_report, and the phrasing is dense, but the summary purpose is inferable.

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 a pagination usage instruction ('Follow groupPage.nextCursor for more groups') but no explicit when-to-use or when-not-use guidance and no named alternatives among the many sibling tools. Usage remains implied rather than directed.

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?

Substantially exceeds the annotations (idempotentHint/destructiveHint/openWorldHint): it discloses that no target agent or connection credential is created, that validation happens before allocation, that partial success is retained rather than rolled back, and that no durable journal exists over remote MCP so the saved plan/operationKey plus service receipts are the recovery authority. That is real behavioral context an agent cannot get from the schema or 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?

Purpose is front-loaded in the first sentence and the remaining sentences each carry a distinct constraint (aliasing, validation/partial success, retry protocol, credential scope, journal behavior). Sentences like the 'service idempotency receipts are the recovery authority' line are jargon-dense, but none are pure filler.

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

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

For a complex, deeply nested plan schema with no output schema and only 5 parameters, the description supplies the safety, idempotency, and partial-success semantics an agent needs before invoking. The main remaining gap is the shape of a successful/partial response, though 'partial success is retained' gives a usable hint.

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 only 20% (essentially just operationKey), so the description must compensate. It adds meaning for alias ('Duplicate Tools use distinct aliases'), the plan/operationKey pair ('Persist exact plan and operationKey'), and dataset validation, but says nothing about source kinds, data kinds, seed, ttlSeconds, or waitTimeoutMs. Partial compensation only.

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

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

States a specific verb+resource: 'Start optional named manual Tool instances from pinned catalog releases or saved private builds', including the two source kinds. It distinguishes itself implicitly from creation tools (create_project, service_create) by being a start/instantiate operation, but never names a sibling explicitly, so an agent must infer the boundary.

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 operational when-guidance ('Persist exact plan and operationKey before calling; retry only that unchanged intent') and implicitly scopes usage to named manual Tools, but never states when to choose this over firedrill_service_create, firedrill_materialize, or create_project. Usage is implied rather than contrasted with alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description still adds real value by enumerating what the call does NOT do (execute targets, generate fictional runs, require Tools/checks), clarifying it is a pure static check.

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?

Two short, front-loaded sentences with zero filler; the core action leads and the scope exclusions follow immediately.

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?

There is no output schema, so the description should convey what validation returns (pass/fail, error list, codes), and it should point to how a recipe is constructed. Neither is present, leaving the agent unable to interpret results or build the input for this non-trivial nested-object tool.

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 single 'recipe' parameter is an opaque freeform object with 0% schema description coverage, and the description says nothing about its expected fields, shape, or where to find the recipe schema (e.g. firedrill_schema). With an open nested object and no compensating detail, the agent is left guessing what a valid recipe looks like.

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 (validate) and resource (repository-owned simulation recipe object) with the scoping qualifier 'before admission', so an agent can distinguish it from execution-oriented siblings like firedrill_materialize. It stops short of explicitly naming an alternative tool, but the purpose is 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?

'Before admission' implies the lifecycle stage at which this should be called, which is genuine usage context. However, no alternative is named and no explicit when-not condition is given beyond the general 'does not execute targets' scope note.

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