Codemind

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

With no annotations, the description carries the behavioral burden and does well: it discloses Pro-plan gating, an upper bound (up to 50), unavailability on Free/base pay-as-you-go, and the exact refusal signal (BATCH_SIZE_LIMIT_EXCEEDED with the limit). It does not describe partial-failure semantics within a batch or per-item error behavior, which is the remaining gap.

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

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

Three dense sentences that are front-loaded with the batching purpose before dropping into plan limits and the follow-up call. Everything earns its place, though the plan/limit clause is information-heavy for a single sentence.

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

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

No output schema exists, so the description appropriately explains the return value (one batchId) and how to consume it (get_batch for aggregate progress); webhook pairing constraints are handled in the schema. What is missing is what happens when some items in a batch fail while others succeed.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning beyond the schema by stating each item mirrors a build_feature call (storyTitle, acceptanceCriteria, stackType, existingFiles?, skipTestsFor?) plus repoUrl, and that repoUrl is 'informational only' — the schema leaves repoUrl completely undescribed.

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

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

Specific verb+resource with explicit scope: 'Submit several pre-decomposed stories in one call and get back one batchId to track.' It directly contrasts itself with the sibling build_feature ('instead of dispatching build_feature N times yourself'), so an agent can distinguish the two 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?

Names the alternative (build_feature called N times) and the condition that selects this tool (multiple pre-decomposed stories in one dispatch). It also states the plan prerequisite, the failure mode when exceeded, and the follow-up tool (get_batch with the returned batchId).

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful traits: the operation is asynchronous (returns a buildId immediately), verification runs against the acceptance criteria before returning, and there is an explicit error-handling contract. It omits the repo side effects (that it writes implementation/test files into the project) and any auth or rate-limit expectations, leaving a gap for a mutating build tool.

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

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

Front-loads the core purpose and workflow in the first sentence, then follow-up routing, then the critical failure-mode warning. Every sentence earns its place with no filler.

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

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

For a 9-parameter, no-output-schema tool, the description covers the workflow, the immediate return value (buildId), and error behavior, and the schema handles parameter detail. It leaves the eventual build outputs and repo-write side effects to be inferred, which is the only notable gap.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters in depth. The description only restates that it takes a story title plus acceptance criteria, adding no format or constraint detail beyond the schema; baseline 3 is appropriate.

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

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

Names a specific verb+resource (generate a feature) and enumerates the pipeline: generate implementation and tests, run checks against acceptance criteria, return a buildId. It clearly distinguishes itself from read siblings like get_build/get_test, but never contrasts itself with the closest build siblings (build_batch, build_from_spec), so it falls short of 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?

Gives explicit follow-up routing (call stream_build with the returned buildId; call get_usage_guide for details) and a clear failure-mode instruction (surface the error, do NOT implement the code yourself). It never states when to prefer this tool over build_batch or build_from_spec, so no exclusions are offered.

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

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

With no annotations, the description carries the full burden and delivers real behavioral detail: LLM decomposition, the repo-assignment invariant, dispatch parity with build_batch, and the dry-run non-persistence semantics. It stops short of disclosing auth requirements or the delivery flow (deliver is covered in the schema), so it is strong but not exhaustive.

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 every sentence carries operational content, but the final sentence about re-decomposition is dense and slightly convoluted. No wasted filler, though it could be tightened.

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 tool with no annotations and no output schema, the description covers the core call flow well and the schema fills in deliver, maxStories, and existingFiles. Remaining gaps are the webhook parameters and any auth prerequisites, which keeps it short of a 5.

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

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

Schema description coverage is only 29%, so the description must compensate more than it does. It meaningfully explains dryRun and the repos/repo-assignment semantics, but webhookUrl, webhookSecret, and hint receive no explanation anywhere, leaving several parameters underspecified.

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 – submit raw spec text, decompose it into stories, and dispatch them – and explicitly ties the dispatch to the same path build_batch uses. It also states a distinguishing scope rule (each story assigned to a declared repo, never invented), so an agent can separate it from build_batch 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?

It prescribes exactly when to use dryRun, names the alternative (build_batch) for committing an edited story list, and warns that a second build_from_spec call re-decomposes from scratch. This is explicit when/when-not/alternative guidance rather than implied usage.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuine behavioral trait: the tool is a no-op on terminal builds. It omits other material traits for a mutation — permission/auth requirements, whether cancellation is reversible, whether it is synchronous or streaming, and what happens to partial build artifacts.

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, with the core action front-loaded and the edge-case constraint immediately following. 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 single-parameter build control tool with no output schema, the description covers the action and the key edge case, which is close to sufficient. It would be complete with a note on return/confirmation behavior and any auth requirement, given there are no annotations to cover those.

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?

There is a single required parameter with 100% schema description coverage ('ID of the build to cancel'), so the schema already does the work. The description adds no format, source, or lookup guidance for buildId, which is the baseline 3 case.

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

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

The description gives a specific verb+resource ('Cancel a running build'), which is unambiguous and clearly distinct from the build/retry/continue siblings by verb. It stops short of naming an alternative like retry_build or continue_build, so an agent must infer sibling routing from the verb alone.

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 supplies an explicit applicability condition ('running build') and an explicit negative case ('no effect on builds that already reached a terminal state'), which tells the agent when the call is a no-op. It does not name alternative tools for the terminal-state case (e.g., retry_build), so routing guidance is incomplete.

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

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

With no annotations, the description carries the full burden and does so richly: billing semantics (verified stories not rebuilt or billed again, resumed stories billed once on first verification), a hard limit of 2 resumes then RESUME_LIMIT_EXCEEDED, inherited throttle/plan cap/allowance rules, and failure context passed to each resumed story. This is exactly the behavioral context an agent needs before invoking.

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

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

Purpose and origin are front-loaded in the first clause, followed by behavior, constraints, and error condition in tight sentences. Every sentence carries distinct, decision-relevant information with no filler.

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

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

No output schema or annotations exist, so the description must cover behavior end to end, which it does: preconditions, billing, limits, error code, and a progress-tracking sibling. An agent has everything needed to call this 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 0% and the single required batchId has no description, so the schema contributes nothing. The description implies batchId identifies the finished run ('resume a finished Ship run ... in the same run') but adds no format or sourcing detail. It partially compensates but not fully.

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 (resume/re-dispatch) and resource (a finished Ship run started with build_from_spec) and scopes it to stories that did not verify. An agent can distinguish this from retry_build or continue_build based on the description alone.

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 triggering condition — the run ended incomplete or nothing_delivered — and notes the no-op case when nothing is left to do, plus 'Track progress with get_batch.' It does not explicitly contrast with the similarly named continue_build or retry_build siblings, leaving a routing gap.

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

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

With no annotations, the description carries the full burden, and it discloses a genuinely non-obvious partial-application rule: already-started components are unaffected and criteria replacement only applies to not-yet-started work. It omits auth needs, idempotency/multiple-call behavior, and what happens if the build already finished.

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 tight sentences with zero waste; the action is front-loaded and the scoping caveat follows 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?

For a 2-param mutation tool with no annotations and no output schema, the description covers the trickiest behavior (who is and isn't affected). It still lacks auth/permission context and failure modes, which matters more here because no annotations 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 100%, so both parameters are already documented. The description adds only the replacement semantics ('replaces the original for all not-yet-started components'), which is marginal beyond the schema's own wording. Baseline 3 applies.

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

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

States a specific verb+resource: 'Send corrected acceptance criteria to a running build.' This is clearly distinct from cancel_build, retry_build, or get_build. It does not name a sibling tool to contrast against, but the action 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?

Provides a clear applicability condition: only components that have not started generating are affected, and the in-flight component finishes as originally scoped. This is an explicit when-not constraint, though no alternative tool is named for the excluded case.

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

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

With no annotations to lean on, the description carries the full burden and does: it discloses the return values (tenantId, apiKey bearer token), the anonymous-until-claimed lifecycle, and a real destructive consequence — replacing an already-claimed account's credential 'loses its identity and history'. That is the kind of side-effect warning an agent cannot infer from the schema.

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

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

Front-loads purpose, then the trigger, then the side-effect warning. Five sentences is on the long side, but nearly every clause carries operational weight (auth precondition, sibling routing, claim-link lifecycle, credential-replacement warning), so little is wasted.

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 compensates by describing the response (tenantId, bearer token, claim link in response text). Auth preconditions, optional-parameter policy, and lifecycle consequences are all covered — nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine usage constraint the schema does not: 'All arguments are optional; pass utm_source, utm_medium and utm_campaign, and invite, only if your human gave you them.' That governs when to supply them rather than just their format.

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

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

Opens with a specific verb+resource+scope: 'Instantly provision a new anonymous Codemind account on the free plan — no credential, no human step required.' An agent can distinguish this account-provisioning tool from the surrounding build/review/test siblings immediately.

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

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

States exactly when to call it ('build_feature ... fails with an auth error and no CODEMIND_API_KEY is configured') and names the alternative plus its trigger ('if you ALREADY have a configured apiKey, call get_usage_guide with topic "auth" before calling this tool again'). When-to-use, when-not-to-use, and the sibling alternative are all explicit.

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?

No annotations are provided, so the description carries the full behavioral burden. It doesn't state whether this is read-only, what 'aggregate status' values exist, whether it polls or blocks, or whether unauthenticated access is allowed. The phrase 'aggregate status' adds some semantics but leaves core behavior 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?

A single, front-loaded sentence with no wasted words. It's appropriately sized for a simple getter and easy to scan.

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 and no annotations, so the description is the only source of behavioral and return-value information. It says what it gets but not what the aggregate status contains or how to interpret the result, leaving an agent able to call it but not to use its output confidently.

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 for the undocumented batchId parameter. It only implies batchId refers to a batch from build_batch, but gives no format, source, or validation details, leaving the required parameter underspecified.

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 (Get) and resource (aggregate status of a batch), and links it to a sibling tool (build_batch) so the agent can see the submission-tracking relation. It doesn't differentiate from get_build or list_builds, but the 'aggregate status' and 'batch' phrasing is reasonably distinct.

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 implies usage by tying the tool to a batch created via build_batch, so an agent knows it applies after submission. However, it gives no explicit when-to-use vs. get_build/list_builds, nor any condition or exclusion guidance.

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

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

With no annotations, the description carries the full burden and explicitly self-declares 'Read-only,' which is the key safety trait, plus it discloses the monetary unit (cents) and that the draw only appears if topped up. It omits auth/account prerequisites and data freshness, but for a status read this is solid 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?

Two sentences, front-loaded with the 'Read-only' safety signal and the returned fields, then the usage trigger. Every clause carries information and nothing is redundant.

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

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

There are no parameters and no output schema, so the description must describe the return payload itself — which it does by listing the reported fields. Minor ambiguity remains around the 'allowance window' (reset cadence/definition), but an agent has enough to call and interpret the result 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-related gaps exist.

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-implied resource (billing/plan status) and enumerates exactly what is reported: plan, verified builds used, included/remaining allowance, and paid-balance draw in cents. No sibling tool covers billing, so an agent can confidently distinguish it from get_usage_guide or list_builds.

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 two concrete invocation contexts: checking headroom before a large batch and diagnosing an allowance-based rejection. That is clear when-to-use guidance. It stops short of naming alternatives or stating when not to call it, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden. It does disclose the returned content (status and error details), which is genuinely useful, but it never confirms this is a side-effect-free read, nor mentions auth requirements, polling behavior, or rate limits.

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

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

One sentence, front-loaded with the action and resource, with the return-content qualifier attached compactly. No filler or redundancy.

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

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

For a single-parameter read tool with no output schema, the parenthetical return summary substitutes adequately for a documented response shape, and the one required param is fully described. Missing only the operational context (read-only nature, polling) that would make it fully self-contained.

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?

There is a single parameter with 100% schema description coverage ('The build ID.'), so the schema does the heavy lifting. The description's 'by ID' adds no syntax, format, or source-of-ID detail beyond what the schema already provides, matching the baseline 3 for high-coverage schemas.

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

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

States a specific verb (get) and resource (build) scoped by ID, and the parenthetical '(status and error details)' signals it returns state rather than files or spec. It implicitly distinguishes itself from get_build_files/get_build_spec but never names those siblings or stream_build explicitly, so differentiation is inferential 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?

The description offers no when-to-use guidance, no exclusions, and no mention of alternatives such as stream_build (for live updates) or list_builds (for finding an ID). The intended use can be inferred, but nothing is 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?

With no annotations, the description carries the full behavioral burden. It does disclose the return payload shape ('each file path and full content'), which is useful given there is no output schema, but it omits whether the operation is read-only (implied), how it behaves on an incomplete build, and whether large file sets are paginated or truncated.

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 sentences with zero filler; the resource and the precondition are front-loaded and the return shape is stated second. Nothing in the text is redundant.

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

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

For a one-parameter read tool with no output schema and no annotations, the description covers the essential call path and pre-emptively describes the return value. It is only mildly incomplete in not addressing failure or partial-build conditions.

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?

There is a single parameter and schema description coverage is 100%, so the schema already documents buildId. The description adds no meaning beyond the schema (e.g., where buildId comes from, format expectations), which matches the baseline 3 for high schema coverage.

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

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

States a specific verb (Retrieve) and resource (generated files from a completed build), which is more precise than the bare name suggests. It does not, however, differentiate itself from close siblings such as get_build or get_build_spec, so an agent must infer which one returns file contents versus metadata or spec.

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 phrase 'from a completed build' implies a precondition (the build must have finished), which is real usage guidance. There is no explicit when-to-use-vs-alternative statement, no mention of what to do for in-progress builds, and no pointer to get_build or list_builds for obtaining the buildId.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose one important trait: this read does not retry the build and returns the *original submitted* spec rather than current state. However, it says nothing about permission requirements, error behavior for missing/invalid build IDs, or whether the spec is a snapshot versus a live view, so disclosure is partial.

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?

One sentence, front-loaded with the verb and resource, with the field enumeration and the key "without retrying" qualifier packed in without filler. Every clause contributes to identifying the tool or its constraints.

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 compensates by listing the spec fields the caller can expect, which is the main missing structured information. It is nearly complete for a one-parameter read tool; only the distinction between the original and any current spec version is left slightly under-specified.

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

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

Schema description coverage is 100% and there is a single trivial buildId parameter, so the baseline of 3 applies. The description adds no naming, format, or sourcing detail for buildId beyond what the schema already states.

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?

"Get a build's original submitted spec" names a specific verb and resource, and the parenthetical enumerates exactly what the spec contains (storyTitle, acceptanceCriteria, stackType, existingFiles, skipTestsFor). It implicitly separates itself from retry_build via "without retrying it," but it never explicitly contrasts with get_build or build_from_spec, so sibling differentiation is only partial.

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?

"Useful for inspecting or reusing a prior build's spec as a template" gives a concrete when-to-use condition (inspection/reuse as template) and implicitly steers toward build_from_spec for the reuse path. There is no explicit exclusion or named alternative, so it falls short of full when/when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the non-streaming, snapshot nature of the call and that it is intended for polling, which is real context beyond the schema. However, it says nothing about whether the operation is read-only, permission requirements, or behavior for an unknown/expired reviewId.

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 tightly written sentences with no filler. The core purpose is front-loaded and the disambiguation against stream_review follows immediately, so nothing needs to be skimmed for.

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 compensates by naming the returned fields (status, verdict, findings), which is exactly what an agent needs. The only gap is undefined error behavior for invalid or unknown reviewIds, a minor omission for such a simple lookup.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'the reviewId returned by review_code'. The description does not add syntax, format, or provenance details beyond what the schema already supplies, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the current state of a review by ID') and enumerates what the state contains (status, verdict, findings). It also explicitly differentiates itself from the sibling stream_review, so an agent can select between them without opening either schema.

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

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

Gives the positive case ('useful for polling or inspecting a review after the fact') and names the alternative with the condition that selects it ('Use stream_review to follow a review in real time instead'). This is explicit when/when-not/alternative guidance.

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

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

No annotations are provided, so the description carries the full burden, and it does meaningful work: it declares the non-streaming, one-shot snapshot behavior ('without streaming'), which is the key trait distinguishing it from stream_test, and names the returned fields. It stops short of disclosing error/not-found behavior, retention of results, or polling cost, so it is strong but not exhaustive.

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, front-loaded with the purpose and return contents before the routing advice. 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 no output schema and no annotations, the description compensates by enumerating the returned fields (status, verdict, generated test content), so an agent knows what to expect. It omits failure modes (invalid/stale testId) and whether the read is cheap to poll repeatedly, which are the remaining 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?

Only one parameter (testId) and schema description coverage is 100%, with the schema itself explaining that it comes from test_component. The description adds only 'by ID', so the baseline 3 for a schema-complete single parameter is appropriate.

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

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

States a specific verb (get), resource (test), keying mechanism (by ID), and enumerates what it returns: status, pass/fail verdict, generated verification test content. It also explicitly distinguishes itself from the sibling stream_test, so an agent can pick between them 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 both a positive condition ('useful for polling or inspecting a test after the fact') and an explicit alternative with the condition that selects it ('Use stream_test to follow a test in real time instead'). This is the when/when-not/alternative pattern done fully.

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

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

With no annotations, the description carries the full burden and does well: it discloses that outputs are tail-truncated and why (failure summaries sit at the end, install noise at the start), that diffs are path+line counts rather than content, and that the LLM trace is conditional ('when available'). It does not describe failure behavior for an unknown/mismatched run id, leaving one behavioral gap.

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

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

Three dense sentences with the primary return value front-loaded and parenthetical caveats kept tight; every clause carries information (truncation rationale, alternatives, trace fields). Slightly overloaded with nested asides, but no filler sentences.

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

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

With no output schema, the description does the heavy lifting by enumerating the return payload (fix diff, before/after test output, per-LLM-call trace with stage/model/status/latency) and the files alternative. Only error/edge conditions and any size or pagination behavior remain unstated.

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

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

Schema coverage is 100% and the schema description already spells out 'the triage run id, as returned by get_triage_runs ... not the build id or issue number'. The description restates the same disambiguation in the parameter's context, adding emphasis rather than new meaning. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Returns the generated fix diff ... and before/after test-run output for one triage run') and immediately differentiates itself from siblings by naming get_triage_runs (id source) and get_build_files (full contents). An agent can distinguish it from get_test, get_build, or get_build_files without opening any schema.

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

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

Gives explicit preconditions and anti-patterns: the id must come from get_triage_runs and is 'NOT a build id and NOT an issue number', and it routes to get_build_files for full file content. It stops short of stating when this tool is unnecessary (e.g. when the run is still in progress or when only a build-level view is wanted), so it is strong but not fully exhaustive.

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

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

With no annotations, the description carries the full burden and does well: it decodes the terminal status values (pr_opened, needs_human, failed) and their meanings, and clarifies the repoAttachmentId format. It omits pagination/ordering behavior, keeping it out of the top tier.

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 parenthetical status definitions and the follow-up pointer. It is a bit dense but each clause adds usable information, so little is wasted.

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 no annotations, the description usefully explains the return shape (one row per issue with terminal statuses) and the diagnostics follow-up path. It is nearly complete, lacking only ordering/pagination details an agent might want.

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

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

Schema coverage is 100% with a single parameter whose schema description already states it is not an owner/repo string. The description's identical clarification adds no meaning beyond the schema, so the baseline 3 for a fully documented single param applies.

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

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

States a specific verb (Lists) and resource (issue-triage run history) with clear scope (one attached repo, one row per auto-triaged issue). An agent can distinguish it from siblings like get_triage_diagnostics without opening a schema.

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

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

Explicitly routes the agent to get_triage_diagnostics for follow-up diagnostics, which implies when this listing tool is the entry point. It does not, however, state when-not to use it or contrast with sibling listing tools such as list_repos, so it falls short of full when/when-not guidance.

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

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

No annotations are provided, so the description carries the disclosure burden. It conveys intent and call timing well, and the tool is implicitly a safe read of documentation, but it never states side effects, whether the call is read-only, or what the response contains. For a pure knowledge-retrieval tool this is adequate but not rich.

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 opening clause, and each subsequent clause maps to a topic or a routing rule rather than padding. It is dense — essentially two long sentences with embedded lists — but nothing appears redundant with the schema.

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

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

For a one-parameter, zero-required, annotation-free retrieval tool with no output schema, the description covers purpose, call timing, and topic routing well. The only real gap is the unmentioned "cloud-swarm" topic and any indication of the response shape, both minor here.

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

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

Schema coverage is 100% with an enum and a per-field description, so the baseline is 3. The description lifts this above baseline by mapping topic values to concrete content (acceptanceCriteria guidance, patch mode, webhooks, error handling, auth recovery) and by prescribing "auth" for a specific recovery scenario.

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 ('Get detailed usage guidance for Codemind's tools') and then enumerates the concrete subject matter covered (acceptanceCriteria authoring, patch mode, webhooks, build declines, auth recovery). No sibling tool provides guidance, so it is trivially distinguishable from build_feature, review_code, etc.

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

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

Gives explicit triggers: call before build_feature/test_component/review_code when unfamiliar with the surface, or when the same story fails repeatedly across retries. It also routes a specific case — topic "auth" before create_free_account to recover from an auth error — naming both the alternative and the condition that selects 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?

No annotations are provided, so the description carries the full disclosure burden. It conveys tenant scoping, but omits ordering guarantees, what a build record contains, and whether the result set is capped or paginated beyond what the schema hints at. For a list tool with zero annotation coverage this is thin.

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

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

A single front-loaded sentence with zero filler; the scope (tenant) is stated immediately. It is efficient, though arguably terse to the point of under-specification rather than maximally useful.

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 simple read-only list tool with no annotations and no output schema, the definition is minimally viable. It covers scope and the schema covers pagination, but the agent gets no sense of result content, ordering, or how this differs from get_build.

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

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

Schema description coverage is 100%, and both limit and offset are fully documented there with defaults and maximums. The description adds only the vague notion of recency and no parameter-level detail, so the baseline 3 applies.

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

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

The description states a clear verb+resource: list builds, scoped to the tenant. It reads as distinct from the singular get_build sibling by verb alone, but it never names or differentiates itself from that sibling, so an agent must infer the list-vs-get split.

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 guidance and no mention of alternatives such as get_build or stream_build. The word "recent" implies a browsing use case but gives no threshold or condition for choosing this tool over other build 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?

With no annotations and no output schema, the description carries the full burden. It does disclose one important behavioral fact — that the returned `id` field is a repo attachment id intended for get_triage_runs — but says nothing about pagination, ordering, auth requirements, or the other fields returned.

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

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

A single sentence, front-loaded with what is listed. It is efficient, though the trailing 'and that the returned `id` field...' clause is grammatically tangled and slightly slows comprehension.

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 parameterless read-only list tool with no output schema or annotations, the description covers purpose, scope, and the key return field's downstream use. It stops short of describing the shape of the returned repo records, which is the main remaining 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?

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. No parameter confusion is possible.

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 ('Lists GitHub repos attached to the caller's tenant') and scopes it to Codemind Resolve. It does not explicitly contrast with list_builds or other list_* siblings, but the resource is distinct enough that an agent can tell them apart.

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 implies the workflow by naming get_triage_runs as the downstream consumer of the returned `id`, which is useful routing context. However, it gives no explicit when-to-use vs when-not guidance and no prerequisites.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the automatic-indexing behavior of completed builds, but says nothing about failure semantics, whether re-indexing overwrites prior content, latency/synchronicity, or any permission requirements for a state-mutating operation.

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

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

Two sentences, zero filler, and the concrete purpose is front-loaded before the usage caveat. The second sentence exists to prevent a redundant call and therefore 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?

No annotations and no output schema, so the description should carry more: it never describes what the caller gets back, whether the operation is synchronous, or what happens when the file-count/size limits are exceeded. It is adequate for choosing the tool but incomplete for invoking it confidently.

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

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

Schema description coverage is 100% — path, content, projectId, and the ≤10 files / ≤700KB limits are all documented in the schema. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ("Index files into the CIL codebase context for a project") and immediately scopes it to a particular class of files, which no sibling name conveys. It is clearly distinguishable from build_feature and the other build/stream siblings from the description alone.

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

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

Gives an explicit when-to-use ("for files Codemind itself did not generate — a manual edit, another tool's output") and an explicit when-not-to-use ("Not needed after a normal build_feature call"). It names the competing tool and the condition (projectId supplied at build time) that makes this tool unnecessary.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the retry uses the same spec including existing files, but says nothing about whether a new build is created, side effects on the failed build, permissions required, or any rate limits. For a mutation tool with zero annotation coverage, this is a significant gap.

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

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

A single front-loaded sentence with no filler. The verb and object lead, and the parenthetical detail about spec reuse is compact and informative. Nothing is wasted.

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 simple one-parameter tool, the description conveys the core action and spec reuse. However, with no annotations and no output schema, it leaves open important context such as return values, whether the failed build is replaced, and any asynchronous behavior. 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 100%, and the single parameter buildId is fully documented in the schema as 'ID of the failed build to retry.' The description adds no additional syntax, format, or constraint information beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Retry') and resource ('a failed build') with the key qualifier that it reuses the same spec (story, acceptance criteria, stack, existing files). This distinguishes it from build_from_spec, which would require a fresh spec, but it does not explicitly name or contrast with sibling tools like continue_build or build_from_spec.

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 phrase 'Retry a failed build' implies the context of use, but there is no explicit guidance on when to use this versus alternatives such as continue_build, build_from_spec, or build_feature. No exclusions or 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?

With no annotations the description carries the full burden, and it does: it discloses the two-pass LLM-judge architecture, that findings are merged into one verdict, the rejection behavior when neither files nor diff is supplied, and the async contract (returns a reviewId immediately; call stream_review to follow progress). This is rich behavioral context beyond what any structured field provides.

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

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

Front-loaded with purpose and the hard constraint, and every section maps to a real decision an agent must make. It is somewhat verbose in the conventions/relatedFiles rationale, but the length is justified by a five-parameter tool with an async contract and no annotations.

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

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

No output schema exists, yet the description explains the return (reviewId) and how to retrieve findings (stream_review), plus the input rejection rule and the guidance needed to get a strong review. An agent has everything required to call it correctly and follow up.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: the mutual-requirement constraint that at least one of files or diff must be present (not visible since required is empty), the authoritative/blocking weight of conventions, and the intent behind relatedFiles as cross-reference-only grounding. It largely echoes the schema wording, which caps it below 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 specific verb (submit) and resource (code for review) and enumerates the review scope: bugs, security issues, silent failures, style. It explicitly distinguishes itself from siblings by naming test_component for test verification, so an agent can route correctly without opening the schema.

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

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

Gives explicit when-to-use conditions (supply files and/or a diff, at least one required), when-not (no code generation or execution; use test_component for test verification), and detailed guidance on when to add conventions and relatedFiles versus the weaker review that results from omitting them. Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does a good job: it explains the polling model ('polls the batch's aggregate status periodically'), the per-tick notification behavior, and the exact termination condition, naming both terminal statuses (completed, completed_with_failures). It stops short of stating the poll interval, error/timeout behavior, or whether the call blocks until completion, which leaves some uncertainty about calling semantics.

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 clauses, each earning its place: the core action, the observable lifecycle, and the routing alternative. Front-loaded with the streaming behavior and no redundant restatement of the name or title.

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

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

For a single-parameter streaming tool with no annotations and no output schema, the description covers the essential contract: what triggers it, what it emits per tick, and when it closes. It omits the shape of the progress notification payload and the polling cadence, so an agent knows the lifecycle but not the payload it will receive.

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% and batchId has no type or format guidance, but the description supplies the key semantic link: the ID refers to a batch produced by build_batch, which tells the agent where the value comes from. No format, validation, or lookup hint is added, so it is adequate but not generous.

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 ('Stream live progress for a batch') and immediately ties the resource to its origin ('submitted via build_batch'), which identifies the correct input domain. It also distinguishes itself from the sibling get_batch by contrasting live streaming with a point-in-time snapshot.

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

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

Gives an explicit alternative and the condition that selects it: 'Call get_batch instead for a single point-in-time snapshot.' The streaming use case (watching progress until a terminal state) is stated directly, so an agent can choose between the two without guessing.

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

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

With no annotations, the description carries the full behavioral burden and does reasonably well: it discloses streaming semantics ('emits a progress notification on every phase change') and both termination paths ('resolves with the final result when the build completes or fails'). It omits whether the call blocks, whether it can be cancelled, and any auth or timeout 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?

Three short sentences with no filler: identity of the resource first, then runtime behavior, then the call-timing rule. Every sentence earns its place and the most decision-relevant information is front-loaded.

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

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

For a single-parameter streaming tool with no annotations and no output schema, the description covers what an agent needs to invoke it and what to expect back in kind (progress notifications, final result). The shape of the emitted notifications and final result is left unspecified, which is the only real gap.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'The buildId returned by build_feature.' The description restates the same provenance without adding format or validity details, so the schema does the heavy lifting and the baseline 3 applies.

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

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

States a specific verb and resource ('Follow a build ... in real time') and anchors it to the sibling that produces the input ('a build submitted by build_feature'), which implicitly separates it from polling siblings like get_build and list_builds.

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?

'Use immediately after build_feature returns a buildId' gives an explicit triggering condition and ordering relative to another tool. It does not, however, state when NOT to use it (e.g., when a build has already finished, use get_build instead), so it falls short of full alternative 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?

No annotations are provided, so the description carries the full burden. It usefully discloses what the tool resolves with (findings plus approve/request-changes verdict), but says nothing about failure modes, timeouts, cancellation, or whether the call blocks until completion.

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 sentences with zero waste, and the core behavior (real-time follow, then resolve with findings and verdict) is front-loaded.

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

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

With no output schema, the description correctly explains what the tool resolves with, which is the key missing piece. It is nearly complete but omits stream/error behavior that matters for a long-running real-time call.

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

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

Schema coverage is 100% and there is a single parameter, so the schema already documents reviewId. The description adds only that the id is 'returned by review_code', which the schema also states, so baseline 3 applies.

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

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

States a specific verb+resource ('Follow a review ... in real time') and names the origin tool (review_code). It implicitly contrasts with the polling sibling get_review via 'in real time', but never names that sibling, so an agent must infer the streaming-vs-polling distinction.

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: the description ties it to a review submitted by review_code, suggesting it is called after that. However, it does not state when to prefer this over get_review, nor any preconditions such as the review needing to be in progress.

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

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

With no annotations, the description carries the full behavioral burden and does disclose the key traits: the call streams/follows in real time and 'resolves with the pass/fail verdict and the generated verification test content.' It omits auth needs, timeouts, and failure modes, but the core behavioral profile of a long-lived streaming call is communicated.

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 action and its real-time nature lead, and the resolution behavior follows immediately — 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 single-parameter streaming tool with no output schema, the description supplies the essential missing piece: what the call resolves with (verdict plus generated test content). It is nearly complete, lacking only edge-case behavior such as failure/timeout handling.

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?

Only one parameter exists and schema description coverage is 100%, so the schema already documents testId fully (including its origin from test_component). The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource — follow/stream a test submitted by test_component — and the 'in real time' framing implicitly distinguishes it from the non-streaming get_test sibling. It does not name the sibling explicitly, so an agent must infer the routing rather than being told.

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 phrase 'Follow a test submitted by test_component in real time' implies the usage context (after test_component has produced a testId, when you want live updates), but there is no explicit when-to-use versus get_test or when-not guidance.

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

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

With no annotations, the description carries the burden and does well: it discloses the verification pipeline, that execution happens in the cloud (isolate or container per stack), that validation runs against a mechanical stub first, and that the tool is asynchronous (returns a testId immediately). It doesn't cover permissions, cost/rate limits, or failure handling, so it stops short of a 5.

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

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

Four compact sentences, front-loaded with the core action and the pipeline, then alternatives and follow-ups. Every sentence is load-bearing, though the parenthetical detail on isolate/container and the multi-clause first sentence make it slightly denser than strictly necessary.

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, async, nested-schema tool with no output schema, the description covers the workflow end to end: what it takes in, what happens internally, that it returns a testId synchronously, and which follow-up tool yields the verdict. It also routes to build_feature and get_usage_guide, leaving no obvious gap for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters in detail (including the exact-match constraint on component and the stub-hidden code field). The description only restates the component shape (filePath/exportName/signature) and acceptance criteria, adding no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Run standalone cloud verification on code you already have,' and describes the pipeline (generate black-box test, validate against a stub, execute real code). It explicitly distinguishes itself from siblings by ruling out code generation and naming build_feature as the alternative. An agent can tell it apart from build_* tools without reading 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 explicit when-to-use ('code you already have'), when-not-to ('No code generation happens here — use build_feature for that'), and the required follow-up ('call stream_test to follow progress and get the pass/fail verdict'), plus a pointer to get_usage_guide. Nothing is left to inference.

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