SHIP

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

Annotations already declare write, idempotent, and non-destructive traits. The description adds a valuable behavioral nuance: the version is rebuilt only if its snapshot is gone, and the response indicates whether that happened. This goes beyond structured data, though it does not cover other aspects like permissions or error cases.

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 core action and followed by a key conditional detail. Every sentence earns its place with no redundancy or filler.

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

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

For a mutation tool with no output schema, the description covers the main action and an important conditional behavior (rebuild + response indicator). It is largely complete, though it doesn't address error handling or permission requirements.

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

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

Schema description coverage is 100%, so the schema already documents both parameters fully. The description adds no additional meaning about versionId or templateId beyond what the schema provides, making the baseline score of 3 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?

The description states a specific action ('Make a version the one missions use') and resource (sandbox template version), making the purpose clear and distinguishable from read-only siblings like list_sandbox_template_versions. However, it does not explicitly name or contrast with related write tools such as save_sandbox_template or build_sandbox_template.

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 context ('from their next dispatch') but provides no explicit when-to-use, when-not-to-use, or alternative recommendations. It lacks guidance on prerequisites or how this tool relates to version creation or listing 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?

Adds substantial context beyond the annotations: each decision's downstream effect ('accept' passes QA, 'reject' fails the mission, 'rerun' re-runs QA on the same commit), the human-in-the-loop precondition, a 409 failure mode, and the required missions:write scope. This is consistent with destructiveHint=true, since 'reject' terminates the mission.

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 eligibility condition, then the decision semantics, then the error and auth constraints. Four dense sentences with no duplication or filler.

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

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

For a state-mutating tool with only two required params and no output schema, the description covers precondition, detection method, per-value effects, error behavior, and authorization — everything an agent needs to decide and invoke correctly.

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

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

Schema coverage is 100% and the enum values are already documented there, so the baseline is 3. The description still earns credit by spelling out the semantic consequence of each decision and by adding a detail absent from the schema — that 'rerun' evaluates the same commit.

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 ('answer the QA checkpoint of a mission') and immediately delimits the situation it applies to (pauseSource 'qa-unverifiable'), which separates it from siblings like approve_mission_ceiling, decline_mission, and set_mission_disposition.

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 trigger condition (mission waits at the QA checkpoint, detectable via get_mission pauseSource) and an explicit when-not (409 when the mission is not at the checkpoint). It stops short of naming the sibling tools an agent should reach for instead in those other cases, which keeps it off 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?

Goes well beyond the annotations: it discloses that the limit increases by exactly one step, that the interrupted stage re-runs, that credits are spent, that human consent is expected, the returned value, and the 409 failure condition. Annotations only supply the generic write/non-idempotent profile.

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 front-loaded: context, then the action's side effects, then the warning, then the return/error/scope facts. Every sentence earns its place, though the second sentence packs behavior, cost, and a warning into one long clause.

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

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

With no output schema, the description still covers the return value, the error case, the authorization scope, and the irreversible credit spend. Nothing an agent needs to invoke this safely is missing.

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

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

Schema description coverage is 100%, so issueId and projectId are fully documented in the schema (including the GitHub key format and where projectId comes from). The description adds no parameter-level meaning beyond that, 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 with mechanism: raises the mission's credit ceiling by one step and re-runs the stopped stage. An agent can distinguish this from resume_mission or request_more_credits without opening any schema.

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

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

Gives a clear operating condition ('ask the person first' since it spends credits) and a negative condition (409 when the mission is not at its limit), plus the missions:run scope requirement. It stops short of naming sibling alternatives like request_more_credits for agents that need more than one step.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, yet the description adds real value on top: the exact blast radius ('Nothing else changes'), the reversibility path (unarchive_mission), and the auth requirements (scope plus owner/admin capability). That is precisely the mutation context annotations cannot express.

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

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

Three short sentences, front-loaded with the effect, then the constraint, then the permissions. Every sentence carries distinct information and nothing is repeated.

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, reversible mutation with no output schema, the description covers effect scope, reversibility, and authorization, which is everything an agent needs to invoke it correctly. Nothing material is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema (Linear key or GitHub Issues id, e.g. SHIP-412). The description adds no format or validation detail beyond it, 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 ('Hide a finished mission') and scopes the effect precisely to list_missions and the board, which distinguishes it from siblings such as delete_sandbox_template or destroy_environment. An agent can immediately tell this is a soft, listing-level hide rather than a deletion.

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 conditions for calling it (finished mission, missions:write scope, config:write capability, owner/admin) and names unarchive_mission as the reversal path. It does not explicitly contrast with a destructive delete-style alternative, so it stops just 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?

Adds real context beyond the annotations: credential is write-only and never seen by agents, reviewer/qa only ever receive read-only tools and cannot use sandbox-internal servers, and omitting fields preserves existing state while setting them re-points. It stops short of saying what happens to the previously stored credential on re-point or how failures (bad transport/credential combo) surface, which is why it isn't 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?

A single dense paragraph with no filler; the binding/update distinction is front-loaded and the transport and field-omission rules follow in a logical order. Every clause carries actionable 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 mutation tool with no output schema, the description covers purpose, prerequisites, transport selection, and update semantics — enough to call it correctly. Gaps are minor: it does not touch approvedTools or the refresh_mcp_server_tools prerequisite, though the schema covers 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: the role-scoping rule for reviewer/qa, the intent behind each transport mode, and the keep-vs-replace behavior of transport/remoteUrl on update. It says nothing about approvedTools (left entirely to the schema).

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

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

States a specific verb pairing ('Create or update') and a precise resource ('the binding for a server the repository declares'), which cleanly separates it from list_mcp_bindings and unbind_mcp_server. An agent can identify it as the write-side counterpart to the read siblings without opening the schema.

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

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

Gives explicit conditional guidance: omit transport/remoteUrl on an update to keep the pinned server and credential, set them only to bind or re-point. It also enumerates the three transport choices with the situation each serves (secret needed, no credential, proxied URL) and names the config:write capability prerequisite.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is covered. The description usefully discloses that a call returns an in-flight build rather than always starting a new one, which is real behavioral context. However that 'reuse existing build' behavior sits in mild tension with idempotentHint=false, and nothing about auth requirements or build lifecycle/status is 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?

A single tight sentence with zero filler, and the primary action (build the active version) is front-loaded ahead of the fallback clause. Nothing is wasted, though there is little structure to speak of.

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 mutation tool with no output schema, the description covers the action but not the outcome: it never says what a caller receives (build id, status, log reference) despite get_sandbox_build_log existing as a sibling. Adequate but leaves a visible gap around return semantics.

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 a single parameter at 100% schema coverage (templateId documented as 'Sandbox id (sbt_...)'), the schema fully carries parameter meaning. The description adds nothing about the identifier's format or source, 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 (Build) and resource (the sandbox's active version), and adds a second clause about returning an already-running build. It is clearly distinguishable in intent, though it never names the closely related siblings like activate_sandbox_template_version or save_sandbox_template that an agent might confuse it with.

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 when-to-use guidance, no prerequisite (e.g., does building require the version to be saved first?), and no condition pointing to alternatives such as activate_sandbox_template_version. The only temporal hint is that an existing running build is reused, which is inferred rather than framed 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: exactly what is destroyed (the per-issue agents/baseBranch override) and the post-condition state (mission resolves from ship.yml again).

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 destructive action leads and the consequence follows. Nothing to trim.

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?

Two required params, no output schema, and annotations that cover safety, so the description's remaining job is explaining the effect — which it does. It could be slightly stronger by noting the override must already exist or how to inspect it via get_agents_override first.

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 issueId and projectId are fully documented in the schema, including the Linear/GitHub id format. The description adds no parameter detail beyond the word 'per-issue', so the baseline 3 for schema-complete tools 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 ('Delete') and resource ('per-issue agents/baseBranch override') and adds the resulting effect ('the mission resolves from ship.yml again'). An agent can distinguish it from set_agents_override by the delete semantics, though the sibling tools are 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?

Usage is implied: the description says the override is removed and the mission falls back to ship.yml, which conveys the intent of reverting to config-driven behavior. There is no explicit when-to-use, when-not-to-use, or pointer to get_agents_override/set_agents_override as 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 it as a non-read-only, non-idempotent, open-world write, so the description's job is to add context beyond that — and it does, disclosing the required missions:run token scope and pointing to the SHIP API docs. It stops short of saying what is destroyed on failure or whether retries duplicate issues, which matters for a non-idempotent creation tool.

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

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

The compound action and the 'no issue yet' scope are front-loaded, and each sentence carries information. The middle sentence is long and packs two conditional hand-off modes into one breath, which slightly hurts scannability but wastes no words.

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 tool with nested agent overrides and no output schema, the description covers the non-obvious parts: the two entry modes, the title-omission rule, auth scope, and API docs. It omits nothing critical, though it doesn't mention the agents/labels/description fields (all adequately schema-documented).

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including the entryPlan/entryPrNumber coupling. The description restates those relationships (entryStartAt pairing, title omission with entryPrNumber) rather than adding new semantics, 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 specific compound action (create the tracker issue AND start the run in one call) and scopes it with 'for work that has no issue yet', which implicitly but clearly distinguishes it from sibling tools like start_mission or list_missions. An agent can tell what resource is produced 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?

It gives explicit branching guidance: use entryStartAt='builder' with an entryPlan to hand over a plan, or entryStartAt='reviewer'/'qa' with entryPrNumber to hand over an existing build. It does not name the alternative tool (e.g. start_mission) for work that already has an issue, so the when-not is only implied by 'for work that has no issue yet'.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description adds genuine value: the auth requirement (config:write), the SHIP API dependency with a docs link, and the key behavioral fact that firing files an ordinary tracker issue rather than spawning a separate execution mode. It does not address the non-idempotent hint (duplicate tasks on retry), which is a notable omission.

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 load-bearing, with the core purpose front-loaded before the mechanics and the API/capability footnotes. The middle sentence is dense but the parenthetical aside about execution mode is worth the words; minor tightening is possible.

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

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

For a 12-parameter mutation with no output schema, the description covers the conceptual model, auth requirement, and downstream side effect, which is what an agent needs to invoke it correctly. It omits retry/duplicate behavior and does not point at get_scheduled_task or list_scheduled_tasks for verification.

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

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

Schema description coverage is 100% with 12 well-documented parameters, including conditional requirements (weekday for weekly, dayOfMonth for monthly) and the label-must-already-exist caveat. The description adds no parameter-level detail 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?

Opens with a specific verb and resource ("Create a recurring agent mission") and immediately clarifies the conceptual model: a stored mission request, not a new execution mode. It also distinguishes itself from run_scheduled_task by explaining that firing is what produces the tracker issue and pipeline run.

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

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

It routes the agent between this tool and run_scheduled_task (immediate firing) and states the required config:write capability, which is real usage guidance. It stops short of explicitly naming when not to use this versus update_scheduled_task or create_mission, so it is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: the required 'missions:write' scope and the permanent nature of the decline ('no call here reopens it'), which 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?

A single dense sentence front-loads the action and effect, then adds the irreversibility constraint and auth requirement with zero wasted words.

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 mutation with no output schema, the description covers the action, the resulting state, permanence, and required scope. Only an explicit routing hint toward merge_mission is missing.

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

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

Schema description coverage is 100% and the single issueId parameter is fully documented in the schema with an example. The description adds no additional meaning about the parameter, 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 and resource ('Close the mission's open pull request on GitHub without merging it') and names the resulting state change ('the mission becomes declined'). It clearly distinguishes itself from the merge sibling by emphasizing the non-merging close.

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 'without merging it' implicitly contrasts with merge_mission, and the irreversibility note hints at when caution is needed, but it never explicitly states when to choose this tool over merge_mission. Usage is implied rather than spelled out.

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 destructiveHint=true and idempotentHint=true, and the description goes beyond them by naming the required connectors:write scope and config:write capability plus the consequence that installs from that host lose their credential. It stops short of stating whether the removal is reversible or recoverable via save_sandbox_registry.

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, no filler, with the mutation and its identifier source front-loaded before the downstream consequence. Every clause carries information an agent needs.

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

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

For a one-parameter destructive delete with no output schema, the description covers identity, parameter source, required auth scopes, and the effect on sandbox builds. Nothing material to correct invocation 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% and the single parameter's schema description already says 'Registry credential id, from list_sandbox_registries'. The description repeats that provenance without adding format or validation detail, so the baseline 3 applies.

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

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

States a specific verb (Delete) plus resource (stored credential of a private registry) and clarifies the identifier source with '(an id from list_sandbox_registries)'. This distinguishes it cleanly from save_sandbox_registry, list_sandbox_registries, and delete_sandbox_template.

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

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

Points the agent at list_sandbox_registries as the way to obtain the required id, and explains the context of use via the downstream effect on sandbox builds. There is no explicit when-not-use or named alternative for removing only part of a credential set, 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?

Annotations already declare destructive=true and idempotent=true, but the description adds substantial context the annotations cannot: the 409 conflict semantics, the exact prerequisite ordering to clear the conflict, the effect on in-flight missions (they finish), and the required scopes/capabilities (agents:write, config:write). This is exactly the beyond-annotation disclosure the dimension rewards.

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 destructive scope, then the conflict/remediation, then permissions. Every sentence carries operational information an agent needs; no filler or restatement of the title.

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

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

For a one-parameter destructive tool with no output schema, the description covers the full decision surface: what is destroyed, when the call will fail, how to unblock it, side effects on running missions, and authorization requirements. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single templateId parameter is documented in the schema as 'Sandbox id (sbt_...)'. The description adds no format or targeting semantics 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+resource (delete a sandbox template) and scopes it precisely: all versions and builds go with it. That distinguishes it from the near-named sibling delete_sandbox_registry and from archive-style tools without opening a schema.

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

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

Explicitly defines the blocking condition (409 while an agent or a project's default sandbox uses it) and the remediation path (repoint via update_project with defaultSandboxTemplateId). It also states when the operation is safe to proceed despite live missions. Nothing about when to use or avoid it 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 flag destructiveHint=true, but the description adds critical context: deletion also removes run history irreversibly, already-started missions continue, and the safer alternative preserves the task. It also discloses required scope and capability.

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 are front-loaded with purpose and irreversible impact, followed by side effects, alternative behavior, and permissions. Every sentence adds necessary decision-making information without waste.

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

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

Given the single-parameter schema, destructive annotations, and no output schema, the description provides everything needed: consequences, run history loss, in-progress mission behavior, the safer alternative, and required 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 100% for the single required parameter, so the schema already documents 'scheduledTaskId'. The description adds no additional parameter semantics, which is acceptable but not value-adding here.

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

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

States a specific verb and resource: delete a scheduled task, and clarifies the scope includes its run history. It also distinguishes itself from the non-destructive alternative of setting enabled to false.

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

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

Explicitly describes the intended use and names the alternative for stopping new runs without deleting history. It also states the permission requirements, giving the agent clear preconditions before invoking.

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 destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: teardown is enqueued to an orchestrator (asynchronous, not immediate) and it destroys both Workers and all provisioned datastores, plus the write-capability requirement.

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 packed sentences with zero filler; the destructive scope is front-loaded before the async/auth caveats.

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 mutation with no output schema, the description covers scope, asynchronous execution, and the capability requirement. It could note whether the teardown is reversible or what status the caller receives, but nothing critical is missing.

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

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

Only one parameter (environmentId), and its schema description ('Environment id to tear down') already carries the meaning at 100% coverage. The description adds no syntax or format 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 (teardown), resource (preview environment), and the exact scope of destruction (deployed Worker(s) plus every provisioned datastore). An agent can distinguish this from read siblings like get_environment/list_environments without inspecting schemas.

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

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

The description gives a prerequisite ('requires project write capability') but never states when to use this versus alternatives or when-not to use it (e.g., production vs preview environments). Usage is implied by the name and scope rather than spelled out.

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

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

Adds substantial behavior beyond the annotations: per-token subject scoping, the persistence rule tied to notice id lifetime, and the concrete case where a topped-up-then-depleted balance returns as a new id and reappears. The annotations only supply safety/idempotency hints; this description explains the actual dismissal 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?

Four tight sentences, front-loaded with the action and subject before the preconditions and id-lifecycle caveat. The low-balance example is the only elaboration and it earns its place by making the id-reuse rule concrete.

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 mutation with no output schema, the description covers the precondition, the scope, the idempotency-persistent behavior, and the critical-notice carve-out. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% with a format example ('credits_low:<grant>'), so the baseline is 3. The description goes further by explaining what the notice id means operationally — dismissal is bound to that id, and id churn is why a notice can reappear — which adds real meaning about the parameter's role.

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 (close/dismiss) and resource (a workspace notice) with an explicit analogy to the console's close button, and scopes it to the token's subject. This cleanly distinguishes it from the read-side sibling get_notices.

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 ('Only a notice with dismissible: true can be closed') and explicit exclusions ('Critical notices cannot be closed'), so an agent knows when not to call it. It does not, however, name the sibling (get_notices) that supplies notice ids in the description text itself; that reference lives only in the schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond them usefully by describing the shape of the returned data and by flagging a non-obvious trap: 'sessions' contains every session of the run's role on the mission, so the agent must use runSessionId for this run's own log and cost. That is genuine disambiguation an annotation cannot carry.

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 return payload front-loaded before the session-id caveat. The second sentence is somewhat dense ('sessions lists every session of the run's role on the mission; runSessionId names this run's own') and requires careful parsing, keeping it just short of ideal.

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 must carry the return-value burden, and it does: it names the run record, the metric series, and the session summary fields (role, outcome, cost, sessionId), plus the session-vs-runSessionId distinction. Error or missing-run behavior is not covered, but for a read-only getter that is a minor 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 single sandboxId parameter is already documented as the run's sandbox id sourced from list_agent_runs. The description adds no format or syntax detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Fetch) and resource (one agent run) and enumerates the payload it returns: run record, CPU/mem/disk metric series, and session summaries. It implicitly distinguishes itself from list_agent_runs, get_agent_run_logs, and watch_agent_run by describing detail retrieval rather than listing, logging, or streaming, but it never names a sibling 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: the id comes from list_agent_runs (noted in the schema, not the description), and the tool is obviously the detail-fetcher for a known run. The description does supply one practical routing hint (read the log and cost from runSessionId rather than any other session), but there is no explicit when-to-use/when-not guidance or named alternative such as get_agent_run_logs.

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, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: logs over 40,000 characters return the tail only, aligned to a whole line, with a note. That truncation contract is exactly the kind of operational detail an agent needs and cannot get from 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?

Four front-loaded sentences: purpose first, then stream semantics, then parameter provenance, then the truncation caveat. No filler sentences, though the parenthetical list of system-log stages is dense enough to slow reading slightly.

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 explaining the payload of each part plus the truncation rule. What is missing is error behavior (e.g., log not yet available for a running or stopped run) and guidance on pairing with watch_agent_run, but otherwise an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema's one-line 'Which log stream to read' by explaining what each enum value actually contains (reasoning+tool calls vs clone/dependency-install/validation/git stdout vs assembled prompt), which is real added meaning for the only parameter that requires judgment.

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

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

Specific verb+resource+scope: 'Fetch a session's log content from one agent run.' It then defines the three log streams (session=stream-json reasoning+tool calls, system=container/runner stdout, prompt=assembled input prompt), which cleanly separates it from get_agent_run (metadata), list_agent_runs, and get_sandbox_build_log. An agent can identify this tool 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?

It tells the agent that role and sessionId come from the agent run's own record, which implies a prerequisite call to get_agent_run, but it never names an alternative tool or states when to prefer this over list_agent_runs / get_agent_run / get_sandbox_build_log. Usage is implied rather than explicit, so it lands at the minimum-viable level.

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, and non-destructive behavior, so the bar is lower. The description adds a genuine behavioral detail beyond the annotations: the return is null when the override is unset, which tells the agent how to interpret an empty result.

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 with the operation and scope front-loaded and the null-case tucked in at the end. 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?

With no output schema, the description correctly carries the return-value burden by naming what is returned and the unset case. For a simple two-parameter getter this is nearly complete; only the permissions or failure modes are unaddressed.

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

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

Schema description coverage is 100%, with both issueId and projectId documented including format examples (SHIP-353). The description adds only the framing that the record is per-issue and per-mission, which the schema already conveys; 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?

Specific verb (Read) plus a precisely named resource (the per-issue agents/baseBranch override record for one mission), scoped to a single mission. It does not name the closely related sibling tools (set_agents_override, clear_agents_override), so an agent must infer the read-vs-write split 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?

The description implies the usage (fetch the override before acting on it) but never states when to call this versus set_agents_override, clear_agents_override, or get_mission. No prerequisites or exclusions are given; guidance is only inferable.

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 context beyond that: the return includes a long-lived signed serving URL and instructions for consuming it (open to view the screenshot/video), which tells the agent what it can do with the result.

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 primary action and its output, with a parenthetical that earns its place by explaining how to use the URL. No filler or restatement of the tool name.

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 full annotation coverage and an output schema, the description covers purpose, output content, and the practical use of the returned URL. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single id parameter is already documented as coming from list_artifacts, so the baseline is 3. The description adds no syntax, format, or sourcing detail beyond what the schema provides.

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

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

The description states a specific verb ("Fetch") and resource ("one artifact's metadata") plus the signed serving URL, and the singular "one artifact" implicitly contrasts with the list_artifacts sibling. It does not name the sibling explicitly, so the differentiation is inferable 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?

Usage is implied rather than stated: an agent understands this is the single-item lookup that pairs with list_artifacts, and the schema note "id (from list_artifacts)" reinforces that. There is no explicit when-to-use/when-not guidance or named alternative, so this is minimum-viable.

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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds genuine context beyond that: it is a composite read combining balance-by-source, start-eligibility, ceiling and allowance, and it discloses the decision it supports (dispatch). Auth needs and rate limits remain 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?

Two sentences, front-loaded with the core action and the returned facets, closing with the actionable trigger. No filler, no restatement of the title, and 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?

With no output schema and no parameters, the description carries the full burden of describing what comes back, and it does so thoroughly across five value categories. What is missing is minor: no indication of freshness/refresh behavior or any cost of invoking it, though for a zero-arg read-only call that is a small 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, which is the baseline-4 case; there is nothing schema-side to document. No parameter information is needed or missing, so the description is not penalized here.

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 ('the workspace's credit balance') and enumerates the distinct facets returned: balance by source and expiry, mission-start viability, per-mission ceiling, project allowance, recent usage. That enumeration implicitly separates it from siblings like list_billing_ledger (raw ledger entries) and list_credit_offers (purchasable offers), so an agent can tell them apart without opening a schema.

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

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

'Check it before dispatching work' gives a clear triggering context for calling the tool. It stops short of naming an alternative (e.g., list_billing_ledger or list_credit_offers) or stating when not to call it, so it is clear context without 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the return-shape hint (registry row with status, worker name, timestamps), but since an output schema exists this is largely redundant and no error/not-found behavior is 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?

A single tight sentence with the resource scope front-loaded and the returned fields parenthetically appended. No filler and nothing to trim.

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 an output schema, rich annotations, and a fully documented single parameter, the description only needs to establish purpose and scope, which it does. Minor omission of not-found/error behavior 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 coverage is 100% and the single environmentId parameter is fully documented in the schema, including its origin ('from list_environments'). The description adds nothing about the id format or source beyond what the schema already says, 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 ('Fetch') and resource ('one preview environment's registry row') and even enumerates the returned fields (status, worker name, timestamps). This cleanly separates it from the sibling list_environments, though it does not name that sibling 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?

The singular scope implies this is the detail-fetch counterpart to list_environments, and the schema points at list_environments as the id source. However, there is no explicit when-to-use statement or exclusion criteria beyond that implication.

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 readOnly/idempotent annotations: it discloses the required missions:read scope, the payload cost differential between views, the meaning of each pauseSource value, and where escalation details live (summary.escalation / escalationCause). It also chains behavior by telling the caller to pass proofRunSandboxId to list_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?

Front-loaded with the single-sentence purpose, then dense but purposeful detail. A few clauses (the enumeration of summary fields) are long but each carries information an agent would otherwise have to guess.

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 full burden of return-value explanation and does so thoroughly for both views, including nested field semantics and escalation reporting. An agent can call this correctly and interpret the response without further documentation.

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 real meaning: it enumerates what each view actually returns (summary fields vs full additions) and explains the downstream use of proofRunSandboxId. orgSlug and projectId narrowing are left to the schema.

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

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

States a specific verb and resource ("Fetch one mission") and immediately qualifies scope via the view modes. It does not, however, distinguish itself from the sibling inspect_mission, which plausibly reads the same resource, so an agent cannot fully disambiguate 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?

Explicitly frames the choice between view='summary' ("small enough to poll") and view='full' (adds stages, events, stats, outcomes), and routes two specific states to alternatives: resume_mission for checkpoint pauses and answer_qa_checkpoint for qa-unverifiable. It gives no guidance on when to prefer this over list_missions or inspect_mission.

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 safety (readOnly/idempotent/non-destructive), and the description still adds real substance: notices are returned critical-first, carry a stable id/kind/message/action URL, and dismissed notices are filtered out. It even explains the operational consequence of a disconnected tracker (missions cannot start or report back), which helps the agent prioritize escalation to a human.

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 purpose and severity ordering. The return-shape sentence and the dismissal-exclusion sentence each carry distinct information, and the closing line lands the call-to-action.

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 input schema, no output schema and annotations already covering the safety profile, the description supplies everything an agent needs: what the notices represent, ordering, returned fields, exclusion rule, and when to check. Nothing material is missing despite the lack of a documented response 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 tool takes zero parameters, so the baseline is 4. The description correctly implies no caller-side filtering, noting that dismissal state (not a parameter) governs exclusion from results.

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) + resource (workspace notices) with scope and ordering (critical first) made explicit. The two example notice kinds (rejected tracker connection, credits running out) make it unmistakable against siblings like get_billing, get_setup_progress or dismiss_notice.

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 proactive directive ('Check it before dispatching work'), which is exactly the trigger context an agent needs. It does not explicitly name alternatives (e.g. go to get_billing instead for billing detail), so 5 is not warranted.

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 behavior, and closed-world scope. The description adds useful behavioral context by noting the 404 response when the project is outside the caller's org, though it does not cover rate limits or permission details beyond org scoping.

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, front-loaded with the core action and followed by the key failure condition. No wasted language.

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-by-ID tool with rich annotations, complete input schema, and an output schema, the description covers the essential behavior including the notable 404 org-scoping condition. Nothing critical is missing.

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

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

Schema coverage is 100% and the single parameter is documented as 'Project UUID.' The description reinforces that the lookup is by UUID but adds no syntax or format details beyond what the schema already provides.

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

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

The description uses a specific verb and resource: 'Fetch a single project by its UUID.' This clearly distinguishes it from list_projects and update_project without needing to name 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?

The description gives clear context for when to use it: retrieving one project by UUID. It does not explicitly name alternatives such as list_projects or state when not to use it, but the single-resource intent 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 already establish readOnly, idempotent, non-destructive, so the safety profile is covered. The description goes further by disclosing pagination semantics and two response fields (nextAfter, done) despite there being no output schema, which is genuinely additive 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?

Two short sentences, front-loaded with the resource, then the continuation contract. No filler and nothing buried.

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 burden of explaining the return shape and does so for the key pagination fields. It stops short of describing log content or chunk format, but the pagination contract is the operationally critical part and it is present.

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

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

Schema description coverage is 100%, so templateId, buildId, and after are all documented in the schema itself; that establishes a baseline of 3. The description restates the role of `after` and links it to nextAfter, adding only marginal meaning beyond the schema.

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

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

The description identifies the resource precisely (a page of a build's log) and frames it as a paginated read. It does not, however, differentiate from the sibling get_agent_run_logs, leaving the agent to infer which log source applies.

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 an explicit driving loop: call again with after = nextAfter until done is true. That is real usage guidance for a paginated tool, but there is no when-to-use / when-not-to-use guidance relative to the alternative log-retrieval 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, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the value is null while the org is unclassified, and the data is sourced from a once-a-minute capacity check, which signals staleness/freshness to the caller. It does not discuss auth or permission 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?

Two sentences with no filler, and the returned fields are packed efficiently. The first sentence is a long triple-clause construction that is somewhat dense but every clause carries information, so it stays close to optimal.

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 burden of explaining the return value, and it does so by naming the three result components. Combined with annotations that cover the safety profile, the definition is nearly complete; only permission/authorization context is missing.

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

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

Schema description coverage is 100% for the single orgId parameter, and the schema already explains it is required only for a caller in several orgs. The description alludes to 'the org's missions' but adds no syntax or format 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?

The description names a specific resource (org's agent capacity against its limit) and enumerates the three things it returns: current usage vs limit, queued missions and why, and whether the platform is fully saturated. It is far more specific than a tautology, but it never contrasts itself with siblings like get_mission or get_agents_override, so it falls 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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The only contextual clue is the parenthetical about the once-a-minute capacity check, which implies freshness rather than routing. An agent must infer on its own when this tool is preferable to inspecting a mission 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 cover read-only/idempotent/non-destructive/non-open-world, so the bar is lower. The description still adds genuine context: 'An id outside the caller's accessible projects returns not found' discloses access-scoping behavior not present in the annotations or 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?

Two sentences, front-loaded with the verb and the field enumeration, followed by the one relevant caveat and the sibling pointer. No wasted text.

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-shape burden and does so by listing the returned fields (project, name, prompt, triggers, labels, template key, skip setting, enabled, run times). Access behavior and the alternative tool are also 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 description coverage is 100% and the single parameter is already documented (including its source 'from list_scheduled_tasks'). The description adds no additional syntax or format meaning 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 ('Fetch one scheduled task by id') plus the resource, then enumerates the returned fields, so the agent knows exactly what it retrieves. It distinguishes itself from siblings by pointing to list_scheduled_task_runs for run-level data.

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 list_scheduled_task_runs when the goal is run output, which is clear alternative guidance. It does not explicitly contrast against list_scheduled_tasks or state full when-not conditions, keeping it 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds real behavioral context the annotations don't: the ordered group model, the role-dependent gating of the per-milestone console page, and that `activeGroup`/`next` encode what to work on. Some of this restates the output schema's fields, which keeps it from being fully additive.

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 readable in one pass, with no filler sentences. It is dense in the middle with return-field detail that the output schema already carries, so a little of it could be trimmed without losing agent-relevant meaning.

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 annotations covering safety, an output schema defining the return shape, and no input parameters, the description supplies everything an agent needs: what the checklist contains, how groups and milestones are ordered, what `next` means, and which sibling to call when setup stalls.

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; the baseline for a no-parameter tool applies. The prose describes response semantics instead, which is a reasonable substitute but not parameter documentation.

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

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

Opens with a specific verb and resource: 'Read what the workspace has set up with SHIP so far, as the console's setup checklist shows it.' It further scopes the payload (13 ordered milestones across three named groups) so an agent can immediately distinguish this read-only progress query from mutating siblings like mark_setup_step or report_setup_blocker.

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 use case ('Use it to suggest the next step to a person') and routes the adjacent case to a named sibling: if the person won't finish setup, ask why and record it with report_setup_blocker. That is a concrete when-to-use plus alternative-selection rule, not 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 the tool as read-only, idempotent, non-destructive, and not open-world. The description adds value by specifying the returned content (status, environment, version), which is useful context beyond the structured safety hints. However, it does not disclose any further behavioral traits such as authentication requirements 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?

The description is a single, front-loaded sentence that efficiently communicates the tool's purpose without any wasted words. It is appropriately sized for such a simple probe.

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

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

Given the tool's simplicity (0 parameters, no output schema) and the annotations covering its safety profile, the description provides enough context by stating what it returns. It could be slightly more complete by mentioning that it takes no arguments or by noting typical usage, but it is largely 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?

The tool accepts zero parameters, and the schema description coverage is 100% (vacuously). Per the rubric, a zero-parameter tool receives a baseline of 4, as there are no parameter semantics to clarify.

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 ('Returns') and resource ('upstream API status, environment, and version'), making the tool's function immediately clear. No sibling tool performs a similar health/status check, so it is easily distinguishable from the rest of the toolset.

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 explicit guidance on when to use this tool versus alternatives, nor does it state any prerequisites or exclusions. While the name 'healthz' implies a health-check use case, the description itself provides no such direction.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds material context beyond them: the required 'inspect:read' scope, the fact that the report is 'typed' and partitioned per-section across KV/D1/R2 stores, and the specific fields returned. It stops short of noting rate limits or access-failure behavior, but the auth requirement is a real addition.

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 verb and resource, followed by the payload inventory and the auth requirement. The long section list is dense but every element earns its place by telling the agent what it can inspect.

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 carries the burden of describing the return payload, enumerating sections down to session-log heads, and it states the required scope. The remaining gap is that it never clarifies the relationship to get_mission, so an agent with both tools in context must guess which to call.

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

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

Schema description coverage is 100%, with the schema documenting issueId syntax (SHIP-199, WEB-42), orgSlug disambiguation, the sections filter, and projectId scoping. The description adds only the 'by its issue id' framing, which 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 ('Fetch the typed platform-inspection report for a mission, by its issue id') and enumerates the report's contents, so the agent knows this is a read of a diagnostic report keyed by issue id. It does not explicitly distinguish itself from the sibling get_mission, which fetches the mission itself, leaving the boundary 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?

No explicit when-to-use or when-not, and the obvious alternative (get_mission) is never named. Usage is only implied by the content list — task state, retry reason, dispatch error, provenance — which signals a diagnostic/troubleshooting purpose an agent could 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 this a read-only, idempotent, non-destructive operation, so safety is covered. The description adds genuinely useful context beyond that: the result is auth-scoped to the caller's accessible projects, ordering is newest-first, and pagination is driven by a nextCursor that must be replayed with the same filters.

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 no filler: scope and ordering first, then the unit of a run, then the return shape, then pagination. Every sentence carries information an agent needs.

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

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

With an output schema present, the return-value enumeration is mildly redundant, and the remaining gap is routing guidance versus sibling get/list tools. Otherwise the description covers scope, ordering, filtering intent, and the pagination contract 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 description coverage is 100%, so baseline is 3, and the description goes slightly beyond by explaining the cursor chaining contract (pass nextCursor back as cursor with the same filters) rather than just restating the field. It doesn't otherwise add syntax for role/status enums or the projectId/issueId identifiers, which are already well documented 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 and resource (list agent runs), plus scope (caller's accessible projects) and ordering (newest first), which distinguishes it from get_agent_run and list_scheduled_task_runs. The extra sentence defining a run as one agent in its own sandbox removes any ambiguity about the unit of listing.

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: the description covers what is listed and how pagination works, but never says when to prefer this over get_agent_run for a single run or how it relates to list_scheduled_task_runs. An agent can infer the listing role from the name alone, so this is adequate but not prescriptive.

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, idempotent read, so the description's value is in behavioral detail: results include superseded QA attempts, a note indicates when more results exist, and serving urls are long-lived and signed. Some of the row-field enumeration overlaps with the existing output schema, which lowers the marginal value slightly.

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 scope before the filtering workflow. No filler, though the row-field enumeration in sentence two is the least essential part given the output schema exists.

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 four-parameter, all-optional list tool with an output schema and full annotation coverage, the description covers what the agent needs: scope, filters, superseded coverage, pagination signal, and the mission proof-of-work recipe. Minor gap is not pointing to get_artifact for single-item retrieval.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: issueId returns every run's artifacts including superseded attempts up to limit, and sandboxId is tied to a specific agent run (the mission's proofRunSandboxId). That exceeds what the schema descriptions alone convey.

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 ('List proof-of-work artifacts') and scopes it to 'QA screenshots/video/traces' for the caller's accessible projects. An agent can distinguish it from get_artifact or list_agent_runs 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 concrete routing guidance: use issueId to get one ticket's evidence, and for a mission's proof of work read proofRunSandboxId from GET /v1/missions/{id} and pass it as sandboxId. It stops short of naming get_artifact as the alternative for fetching a single artifact, so it is clear context rather than full when/when-not coverage.

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 read-only, idempotent, non-destructive, non-open-world behavior, so the description is not responsible for the safety profile. It adds useful context beyond annotations: the reverse-chronological order, what each ledger entry represents, how to page, and the owner/admin restriction. It does not cover rate limits or return fields, but it meaningfully enriches the behavioral picture.

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

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

The description is three sentences with no wasted words, front-loading the core purpose before pagination and permission details. Every sentence earns its place by adding 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?

There is no output schema, so the description bears some burden for explaining return content, and it does so by naming entry types and ordering. It covers pagination and access requirements but does not describe the fields within each entry (amount, timestamp, etc.), leaving a small gap for a ledger tool. Overall it is complete enough 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 both parameters fully. The description reinforces cursor usage ('Pass nextCursor back as cursor for the next page') and implies newest-first ordering, but adds no syntax or meaning beyond what the schema provides. The baseline of 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'List where the workspace's credits went.' It further distinguishes itself from siblings like get_billing by specifying a paginated ledger with one entry per mission, grant, adjustment, and expiry. An agent can tell exactly what this tool returns and how it differs from a billing summary.

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 clear usage context: newest-first ordering, entry composition, pagination via nextCursor, and an explicit permissions restriction ('Owners and admins only'). It does not name alternative tools or state when not to use this one, but the operating context 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 already establish readOnly, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: that checkout applies location-based tax, that Enterprise contracts are not purchasable through checkout, and precisely what each catalog section contains — valuable given no output schema exists.

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 entire definition is a single sprawling sentence with deeply nested parentheticals that reads like a transcribed response schema. It is dense and poorly front-loaded, forcing the reader to parse clauses rather than grasp the tool's role at a glance.

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, no output schema, and annotations covering safety, the description's job is largely to convey what comes back — which it does exhaustively (packs, team.plans, enterprise, limits, trial). It is complete enough to call and interpret, short of explicitly stating its relationship to the checkout tools.

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 no parameter meaning to convey; the 4 baseline applies. The description does not need to compensate for any schema gap here.

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 (list) and resource (SHIP's catalog of credit packs, monthly plans, Enterprise tiers, limits, trial). The scope is unambiguous, though it does little to differentiate itself from sibling list_* tools and reads more like a response inventory than a purpose statement.

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?

No explicit when-to-use, when-not-to-use, or named alternatives. The mention that 'contracts are sold by SHIP, not through checkout' faintly gestures at start_credit_checkout, but the agent is left to infer that this is the read-only catalog-lookup counterpart to the checkout/request_more_credits 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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds one genuinely behavioral fact beyond annotations — results are scoped to the caller's accessible projects (authorization surface) — but no pagination, ordering, or empty-result 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 waste, with the scope constraint front-loaded ahead of the returned fields. Nothing here needs trimming or reordering.

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?

Output schema exists so return values need not be explained, and annotations carry the safety profile; the description supplies the scope qualifier. The one gap is that the returned-field sentence partially duplicates the output schema rather than using the space for filtering/ordering guidance.

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

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

Schema description coverage is 100%, so all four filters (limit, status, issueId, projectId) including the status enum are fully documented in the schema. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the work.

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 ('List') and resource ('per-mission preview environments') plus scope ('caller's accessible projects'). It is clearly distinguishable from the singular get_environment and the mutating destroy_environment siblings, though it never names them 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 only implied: listing is the obvious read operation, and the schema's limit description carries the real guidance ('Narrow with issueId, projectId or status before raising it'). The description itself offers no when-to-use vs alternatives statement or 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 declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description still adds real context beyond them: the security-relevant guarantee that credential fields are returned as NAMES and 'never values', plus the visibility scope limiting results to projects the caller can see. It stops short of covering pagination or result size.

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 scope, then the field inventory, then the disambiguation. The parenthetical '(never values)' is a compact way of carrying a critical guarantee. 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 work of describing the return surface (project, server, transport, status, roles, auth, credential field names) and the visibility boundary. Combined with the sibling disambiguation and the annotations' safety profile, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description instead spends its space on the shape of the returned records, which is the useful equivalent.

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 ... MCP server binding') plus its scope ('across the projects you can see in your org'), then enumerates exactly what each row contains: project, server, transport, status, enabled roles, auth method, and credential field NAMES. It explicitly separates itself from list_mcp_servers, so an agent can route without opening either schema.

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

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

Gives an affirmative use case ('Use it to find where a credential is used') and names the alternative with its distinguishing condition ('use list_mcp_servers for one project's full detail'). Nothing about when to pick this over its sibling 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 and closed-world, so safety is covered. The description still adds real behavioral context: per-role effective tool counts are null when the server runs inside the sandbox and the role gets every exposed tool, credential fields are returned as NAMES and never values, and configStatus reports whether the file could be read.

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 long but well-ordered sentence that front-loads the resource and then enumerates the returned binding fields; the null-case and never-values notes are embedded where they matter. Slightly dense, but nothing is wasted and no boilerplate is present.

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 must characterize the return value, and it does so field-by-field (enabled roles, transport, status, approved tools, per-role tool counts, credential field names, configStatus). Safety is covered by annotations and the single parameter by the schema, so nothing an agent needs to call it correctly is missing.

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

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

There is a single parameter at 100% schema description coverage ('Project id, e.g. from list_projects'), so the schema carries the semantics. The description adds nothing about projectId (no format, no source beyond the schema), which is the expected baseline when coverage is 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 ('The MCP servers a project's repository declares in its MCP file (.mcp.json by default)') and enumerates the binding detail returned, so the agent knows exactly what this retrieves. It does not differentiate itself from the sibling list_mcp_bindings, but the scope (config-file declared servers for one project) is otherwise 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?

No when-to-use, when-not, or alternative is named. With list_mcp_bindings, bind_mcp_server, unbind_mcp_server and refresh_mcp_server_tools in the sibling set, an agent gets no help deciding between reading declared config versus listing bindings. Usage is only faintly implied by the word 'declares'.

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, so the safety profile is covered. The description adds real value beyond that: sort order by newest activity, that a total is returned for paging, that archived missions are filtered out, and the required missions:read scope.

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 tightly packed sentences, front-loaded with the resource and scope before exclusions and auth. The enumeration of returned fields is somewhat long but earns its place since there is no output 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?

With no output schema, the description usefully enumerates key returned fields (issueId, title, activity, pipelineProgress, review/check/test state, PR, cost, paused), and it covers ordering, exclusions, paging total and required scope. Only the precise pagination mechanics are left vague.

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

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

Schema description coverage is 100%, and the schema already explains limit, offset, search, activity and projectId in detail. The description only alludes to paging ('total for paging') and filters, adding little 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 ('List missions'), the scope ('caller's accessible projects'), the ordering ('newest activity first'), and paging behavior ('with total for paging'). This clearly distinguishes it from get_mission and inspect_mission 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?

The description notes the exclusion of archived missions and the required missions:read scope, plus the schema tells the caller to narrow with projectId/activity/search before raising limit. However, it never states when to prefer this over get_mission or inspect_mission, so selection guidance is only implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive context beyond them: the required cross_org privilege level, the pagination mechanism, the default page size of 50, and the termination condition. This is unusually rich behavioral disclosure for a read-only 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?

Two sentences, zero filler, front-loaded with purpose and access requirement before the pagination mechanics. Every clause carries information an agent needs.

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

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

With no output schema, the description compensates by naming the fields returned and fully describing the cursor lifecycle. Nothing needed to page through results 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 cursor and limit parameters are already documented, setting a baseline of 3. The description adds value beyond the schema by explaining the round-trip contract - nextCursor from the response is fed back as the cursor input - and that a null nextCursor signals the last page.

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 (List) and resource (every organization on the platform), and immediately scopes it as cross-tenant with the returned fields (owner email, member count, pending invite status). No sibling tool lists orgs, so an agent can tell this is the only cross-tenant org enumeration available.

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 precondition for use - platform-admin (cross_org) access - which lets an agent decide whether it is eligible to call it. It does not name an alternative or state when NOT to use it, but no sibling tool overlaps with org listing, so the missing exclusions are low-impact.

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, closed-world, non-destructive behavior, so the description does not need to restate safety. It adds genuine behavioral context the annotations lack: the exact fields returned and, importantly, the semantics of an empty result as a not-yet-configured workspace with a hard consequence ('no mission can run').

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 return shape, then the remediation path for the empty case. Minor redundancy in listing return fields when an output schema already exists, but nothing is padding.

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

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

Output schema and annotations carry the return shape and safety profile, so the description correctly focuses on the non-obvious empty-state interpretation and the follow-up call. Pagination behavior for the cursor is left entirely to the schema, a small 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?

Schema coverage is 100% and both parameters (limit with default 20 and max 100, and the opaque cursor) are fully documented in the schema. The description adds nothing about pagination mechanics or how to iterate with the cursor, so the baseline of 3 is warranted.

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 the projects accessible to the calling principal'), names the scope of accessibility, and enumerates the returned fields. It is trivially distinguishable from the singular get_project sibling and from the other list_* tools, which target different resources.

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

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

Gives an explicit conditional branch: an empty result means the workspace is not set up, and the agent should call get_setup_progress and surface the console page of its next step. It does not explicitly say when to prefer get_project over this tool, but the list-vs-get distinction is self-evident.

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, so the safety bar is low, yet the description adds genuinely new behavioral information: the response includes auth scheme and username but 'Never the secret.' That credential-exposure disclosure is exactly the kind of thing annotations cannot 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?

A single clause with no filler, and the key constraint — 'Never the secret.' — is placed at the end for emphasis. The telegraphic, fragment-like phrasing ('registries sandboxes install from') costs a little readability but wastes no space.

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

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

With no parameters, no output schema, and full annotation coverage, the description is nearly sufficient: it names the resource and the returned fields. Explaining the return shape stands in for the missing output schema, though it doesn't say how many registries or how ordering works.

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 to disambiguate; the schema coverage is 100% by definition. Baseline 4 applies, and the description correctly spends no words on nonexistent 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?

States a specific resource — the org's private package registries that sandboxes install from — and enumerates the fields returned (host, auth scheme, username). This is far more than a restated title, though it never names the sibling write tools (save_sandbox_registry, delete_sandbox_registry) to sharpen 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?

Usage is implied by the read-only listing nature and the readOnlyHint annotation rather than stated. There is no explicit when-to-use or when-not, and no pointer to save_sandbox_registry/delete_sandbox_registry for the mutating counterparts. Adequate but leaves 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and side-effect profile is fully covered. The description adds only that the definitions are 'ready-made' and enumerated by language, but says nothing about return shape, pagination, or whether starters can be customized - modest added value given the annotations carry the bulk.

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 compact sentence with no filler and the resource front-loaded; the language enumeration is informative rather than padding. It is a touch terse - an explicit verb ('List') would make it self-contained instead of relying on the tool name.

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 list tool with no output schema, the description conveys the basic content but not the return structure - the agent cannot tell whether it gets names, versions, or full build definitions. Given the absence of an output schema, one clause about what a starter record contains would close the 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 per the rubric the baseline is 4. There is nothing for the description to clarify beyond confirming there is no filtering or input, which it implicitly does by describing a fixed set of starters.

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 resource - ready-made sandbox definitions - and even enumerates the available languages (Python, Java, Go, Rust, Ruby), which tells an agent concretely what it will get. The verb 'list' comes from the name rather than the description, and it does not explicitly distinguish itself from the crowded family of sibling list_* tools (e.g. list_sandbox_templates).

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 trailing phrase 'to create a sandbox from' implies the tool is a precursor to sandbox creation, which is useful implied usage context. However, there is no explicit when-to-use guidance and no mention of how it relates to sibling tools such as list_sandbox_templates or build_sandbox_template, leaving the agent to infer the 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine value by disclosing what each entry includes (active version, size, latest build status), but says nothing about ordering, pagination, or whether inactive/archived templates appear.

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 well-formed sentence that front-loads the core action and packs the return contents into a compact clause. 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 zero-parameter read tool with no output schema, the description is nearly sufficient: it names the resource and previews the returned fields, and annotations carry the safety profile. The only real omission is any hint of ordering or result-size behavior, which is 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies an unfiltered org-wide listing, which is consistent with there being no filter 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?

States a specific verb and resource ('List the org's sandboxes') and clarifies the concept with a parenthetical ('definitions agents start in') that disambiguates it from a runtime sandbox instance. However, it never differentiates itself from close siblings like list_sandbox_starters, list_sandbox_registries, or list_sandbox_template_versions, which an agent must pick between.

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 when-to-use guidance and no mention of alternatives, despite the sibling list containing at least four other sandbox-related list tools. The agent is left to infer the selection criteria from names alone.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description correctly focuses on output behavior: ordering (newest first), the active-version marker, and inclusion of each version's latest build. That extra content detail is genuinely useful beyond what the annotations state.

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 ordering and marking details are packed efficiently. Nothing wasteful, though it is terse enough to leave some gaps.

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 read tool with no output schema, the description conveys what comes back (versions, order, active flag, builds). Nothing critical is missing, though it could note that no filtering/pagination applies.

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 sole templateId parameter is documented as a sandbox id (sbt_...). The description adds no further parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific verb (list) and resource (a sandbox's saved versions), which cleanly separates it from sibling list_sandbox_templates. It does not explicitly name that sibling, but the resource boundary is unambiguous from the wording.

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 when-to-use or when-not-to-use guidance, and no mention of the alternative activate_sandbox_template_version or list_sandbox_templates. Usage is only implied by the resource being listed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them with the highest-value disclosure here: the status enum interpretation and the explicit warning that 'dispatched' means the mission started, never that work succeeded. That prevents a serious misread of the data.

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

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

Three tight sentences, each front-loading its key fact (what rows contain, the status caveat, ordering/pagination). No filler, and the critical caveat is placed where an agent will read it.

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

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

With no output schema, the description carries the return-value burden and does so: row contents, status semantics, joined mission data, ordering, and pagination are all covered. An agent can call and correctly interpret this without further context.

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 scheduledTaskId, limit, and cursor are already documented; the description largely restates the cursor round-trip that the schema describes. Baseline 3 is appropriate since the schema does the parameter work.

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 ('Run history for one scheduled task') and immediately enumerates the row contents (status, joined mission progress/cost). This clearly separates it from sibling get_scheduled_task (task config) and list_scheduled_tasks (the task list itself).

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?

Explains ordering ('newest first') and the exact pagination workflow ('pass nextCursor back as cursor for the next page'), which is the operative how-to-use guidance. It does not explicitly contrast with get_scheduled_task or list_scheduled_tasks, so it falls short of 5.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive, closed-world profile, so the description only needs to add context. It does: it discloses the per-item return fields (schedule, enabled state, next/last fire time) and the authorization scope (only accessible projects). Pagination or result-count behavior is not mentioned.

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, no filler, with the scope and returned fields front-loaded before the parameter usage note. Every clause carries information an agent needs.

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

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

With no output schema, the description compensates by enumerating the notable returned fields, and it defines global vs project-scoped behavior for a tool with one optional parameter. It stops short of mentioning pagination, ordering, or volume limits, which is the only 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 single parameter is fully documented in the schema, so the baseline is 3. The description earns above baseline by spelling out the behavioral difference between supplying projectId and omitting it (all accessible projects vs one project), which the schema's parameter text does not state.

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 (list) and resource (recurring agent missions / scheduled tasks) plus the scope (caller's accessible projects), and pre-empts the mission-vs-scheduled-task terminology overlap that exists among siblings like list_missions and list_scheduled_task_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?

The closing sentence gives a clear conditional: omit projectId to span all accessible projects, pass it to narrow to one. That covers the practical when-to-use decision, but it names no alternative tools and states no exclusions, 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real conceptual context the annotations cannot: templates are pure content, not code paths, and their keys serve an attribution role. It does not describe return shape or pagination, but for a no-param read against fully-covered annotations this is solid added value.

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 filler. The core identity ('read-only gallery of curated scheduled task templates') is front-loaded, and the second sentence immediately resolves the natural confusion about how templates relate to actual task execution.

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 zero-parameter, read-only listing with no output schema, the description supplies enough: it says what templates contain, that keys are meaningful, and how they are consumed. The main residual gap is that it does not hint at the shape of the returned list beyond prompt/cadence/key, which matters slightly more given there is no output schema to lean on.

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

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

The tool takes zero parameters, so there is no input semantics to clarify and the baseline is 4. The only field-like mention (templateKey) belongs to a sibling create tool, not to this one, so it neither helps nor distorts parameter understanding here.

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 (listing curated scheduled task templates) and defines what a template actually is — a prepared prompt plus a suggested cadence. It also differentiates the concept from related siblings by explaining that a template is content rather than an executable path, so an agent can place it relative to create_scheduled_task 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?

It clearly explains the downstream context: pass a template's key as templateKey on create_scheduled_task, or copy its prompt/schedule into a hand-written task. This frames when the listing is useful (discovery/attribution before creating a task), but it never explicitly states an exclusion or says 'call this before creating a scheduled task' as a directive, so it stops just short of full routing guidance.

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

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

Annotations cover the safety profile (idempotent, non-destructive, not read-only), and the description adds genuinely useful behavior: the return value (the checklist as it now stands), the refusal case for a token that acts for no person, and the semantic that 'reached' stays false until SHIP sees the step done.

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 front-loaded: the core action and the step/group distinction come first, and side details (return value, refusal) come later. The semicolon-heavy run-on sentences are slightly harder to parse than ideal 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?

With no output schema, the description compensates by stating the return value, the refusal condition, and the relationship to setup progress. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% and all three parameters are enum-documented, so the schema carries the load. The description clarifies the intent of step vs group (one milestone vs every open step of a group), which adds modest value beyond the schema but no new format or constraint detail.

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

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

States a specific verb (mark) and resource (a step of the setup checklist) with the exact state transitions available (completed/skipped/open). It is clearly distinguishable from the sibling get_setup_progress, which is pointed to as the source of step ids.

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?

Explains the two modes clearly: give 'step' for one milestone, or 'group' to mark every open step of a group (the console's Skip all). It also notes open removes the mark. It stops short of explicit when-not-to-use guidance, but the routing between step and group is well covered.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true, openWorldHint=true), the description adds the irreversible nature of the merge, the missions:write scope requirement, the auto-branch-update and auto-conflict-fix behavior, and the meaning of the 202/409 responses. That is rich behavioral context an agent cannot get 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?

The core action and its irreversibility lead, followed by outcome handling; every sentence carries operational information. It is dense but slightly long, and the response-handling clauses could be tightened without losing meaning.

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

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

With no output schema, the description covers the failure/async paths (202, 409, conflict auto-fix), permissions, and irreversibility, which is most of what an agent needs. It does not describe the shape of a successful merge response, which is a minor 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?

There is a single required parameter with 100% schema coverage, so the schema already documents issueId fully (Linear key or GitHub Issues id). The description adds no parameter-level detail beyond the schema, which is the expected baseline of 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?

The description names a specific verb and resource ('Merge the mission's open pull request on GitHub') and states the repository's own merge method is used, so the action is unmistakable. It does not differentiate itself from adjacent siblings such as set_mission_auto_merge or set_mission_disposition, which is the one gap preventing 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 clear conditional guidance on how to proceed in each outcome: 202 updating_branch means stop calling, 409 means a blocker exists and the reason is returned, and a merge conflict is handled automatically with no further call. What is missing is an explicit when-not-to-use or a named alternative to choose 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?

With annotations already covering readOnlyHint=false, destructiveHint=false, and idempotentHint=true, the description adds valuable behavioral context: the current stage finishes, no agent is stopped, and the operation is reversible via resume_mission. It also discloses required permissions. It stops short of full transparency about edge cases like already-paused missions or effects on scheduled tasks.

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 four short, front-loaded sentences with zero waste. The core behavior is stated first, followed by the key operational nuance and the alternative, then the prerequisite.

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 pause tool with one fully described parameter, no output schema, and clear annotations, the description covers purpose, usage, behavioral nuance, and authorization requirements. No additional return-value or parameter detail is needed.

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 sole parameter issueId is fully documented in the schema, including format examples. The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb (hold/pause), resource (mission), and scope (before its next stage). It distinguishes itself from the sibling resume_mission by naming it as the continuation alternative, and 'no agent is stopped' implicitly contrasts with stop_mission.

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 states when to use it ('before its next stage') and which alternative to use to resume ('Use resume_mission to continue'). It also gives the prerequisite scope and role, leaving no ambiguity about eligibility.

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 flag destructiveHint=true and idempotentHint=true, and the description adds real context beyond them: approvals for tools that no longer exist are dropped (explains the destructive side effect), the binding must be ready (prerequisite), and 'Requires config:write' (auth scope). No contradiction with the mutation/destructive profile.

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

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

Three sentences, front-loaded with the action and its effect, followed by prerequisite and auth requirement. Dense but every clause carries distinct information with little waste.

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, so return semantics are not required, and the description covers effect, prerequisite, exclusion, and auth scope. Missing only the approval workflow/return detail, which is minor for a well-annotated mutation 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 100% and both projectId and serverName are documented in the schema with examples and a pattern. The description adds no parameter-level syntax or format beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource: snapshotting the bound server's current tool list, including the readOnlyHint/destructiveHint annotations, for approval. It is clearly about tool-list refresh rather than generic config, though it doesn't name a sibling (e.g. list_mcp_servers or bind_mcp_server) to explicitly contrast with.

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 context and an exclusion: the binding must be ready and 'a server inside the sandbox has no gateway tool list', which implies when this cannot be used. It stops short of naming an alternative tool for those cases, but the when/when-not conditions 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?

Adds behavior beyond annotations: 'Each call is a new report' explains the non-idempotentHint=false semantics, and 'A token that acts for no person is refused' discloses an auth failure mode. It does not say what happens to reports afterwards or what the call returns, which with no output schema is a minor gap.

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

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

Front-loaded with the core purpose, then preconditions, then the negative constraint and auth caveat. Every sentence carries information; only 'Each call is a new report' is close to restating the non-idempotent annotation.

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

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

For a two-parameter write tool with no output schema and full annotation coverage, the description supplies the trigger, the sibling that gates it, the privacy constraint, the anti-guessing rule and the refusal condition. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is already 100%, so baseline is 3; the description adds value by mapping example situations ('no repository yet', 'no wish to set up model keys or credits', 'no time now') onto the reason enum values, and by framing the detail parameter as the person's own words. It does not add format guidance beyond the schema.

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

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

States a specific verb ('Record why...will not finish setting up') on a specific resource (setup blocker reason, in the person's own words), with concrete examples of what qualifies. It is clearly distinguishable from read-oriented siblings like get_setup_progress and mark_setup_step.

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

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

Explicit preconditions: 'Call it only after the person said why', 'Ask them when get_setup_progress shows setup is not done', plus a negative rule 'Do not guess a reason'. It names the sibling that triggers it and the condition that selects 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 declare readOnlyHint=false and idempotentHint=false but say nothing about routing or effect. The description adds real behavioral context beyond them: who may submit, that approval routes to SHIP for sponsored/Enterprise workspaces versus owners and admins otherwise, and that a new message joins an existing open request (explaining the non-idempotency). It stops short of describing the response payload or any limits on concurrent requests.

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

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

Three short sentences, front-loaded with the action and scope, then eligibility, then routing and open-request behavior. Nothing is padding, though the routing sentence is telegraphic enough to require a second read.

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 tool with no output schema, the description covers eligibility, routing of the answer, and deduplication behavior, which is most of what an agent needs. It does not explain what a successful call returns or what happens to a request that is declined, but the core is present.

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

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

There is a single required parameter with 100% schema description coverage ('What the credits are for.'). The description restates the same intent ('saying what they are for') without adding format, length, or content expectations, so it neither helps nor hurts beyond the schema baseline.

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

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

The description states a specific verb and resource tied to a named scope: 'Ask for more credits for the workspace.' An agent can tell this is a request/escalation action, not a purchase, but the description never names the closely related siblings (start_credit_checkout, list_credit_offers), so the differentiation must be inferred.

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?

'Any member may ask' establishes who is eligible, and 'A message sent while a request is open joins it' tells the agent not to open duplicates. However, there is no explicit when-to-use statement and no comparison to start_credit_checkout or list_credit_offers, so selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds genuine value beyond that: the checkpoint-approval side effect of advancing to the next stage, and the required missions:write scope. It doesn't spell out reversibility of the approval or error cases, but the added context is substantial.

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

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

Three tight sentences, front-loaded with the core action, then the checkpoint condition, then the routing alternative, ending with the scope requirement. 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 single-param action tool with no output schema, the description supplies the operational context an agent needs: what it does, the exact state that triggers it, the sibling alternative, and the required auth scope. Combined with annotations, nothing essential is missing.

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

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

Schema description coverage is 100% and the single issueId param is fully documented in the schema with examples. The description adds no syntax beyond that, so the baseline of 3 applies – the schema carries the parameter burden.

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

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

States a specific verb (continue/resume) and resource (mission), and adds a precise behavioral detail distinguishing it: at a checkpoint it approves the stage's result and advances. An agent can tell this apart from pause_mission, stop_mission, and send_mission_instruction without opening a schema.

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

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

Gives an explicit triggering condition – get_mission showing pauseSource 'checkpoint:<role>' – and names the alternative (send_mission_instruction) with the exact reason to pick it (wanting changes instead of approval). 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?

Goes well beyond annotations by disclosing the skip-if-previous-open bypass, the guaranteed new-issue side effect even when a prior mission is open, and the exact authorization requirements (pipeline:control capability, missions:run scope for token callers). This is precisely the operationally important context annotations alone (readOnly/idempotent/destructive) cannot 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 action and its key override, and every clause carries meaning. The second sentence is dense with em-dash asides about authorization, slightly reducing readability, but 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 mutation-triggering tool with no output schema, the description supplies the side-effect semantics and the full auth prerequisite set an agent needs before invoking. Nothing essential is missing.

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

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

Schema description coverage is 100% for the single parameter, so the schema already documents scheduledTaskId. The description adds no format or sourcing detail for the id beyond what the schema states, so the baseline 3 is appropriate.

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

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

States a specific verb (fire/run) and resource (scheduled task) with the key modifier 'immediately', and the 'bypassing its schedule' clause cleanly separates it from the passive scheduled execution that create/update_scheduled_task imply. An agent can distinguish this trigger action from its CRUD siblings at a glance.

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 strong context on when this behavior applies (manual override of schedule and the skip-if-previous-open guard), which implicitly frames the manual-trigger use case. It stops short of naming a sibling alternative or an explicit when-not-to-use condition, so it lands just below 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation context: the credential is attached only to requests for that host, never enters a sandbox, and is never returned, which explains blast radius and why no read-back occurs. It stops short of stating permission requirements or explicitly tying 'replace' to the destructive hint.

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 with zero filler, and the upsert behavior is front-loaded before the scoping facts. Every clause carries information the agent cannot get from the schema or 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?

For a credential-store tool with a fully documented schema, no output schema and annotations covering mutation/idempotency, the description is nearly complete: it covers scope of attachment, secret non-exposure, and replace semantics. Missing only prerequisites (who may write credentials) and any note on rotation/verification behavior.

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

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

Schema description coverage is 100% and the schema already documents host, scheme (including the bearer/basic enum semantics), secret and the conditional username. The description adds no parameter-level detail (e.g. that username is ignored under bearer), 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 (store/replace) and resource (credential for a registry host), and the parenthetical clarifies upsert semantics so the agent knows this is not a pure create. It does not explicitly name the sibling it differs from (list_sandbox_registries, delete_sandbox_registry), 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?

Usage is implied by 'for a registry host' — the agent infers this is the way to supply credentials for host-scoped sandbox requests. However, there is no explicit when-to-use statement, no note that list_sandbox_registries should be consulted first, and no stated prerequisites for the host/scheme combination.

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 establish a non-read-only, non-idempotent, non-destructive write, and the description adds substantial context beyond them: that a changed definition or size becomes a new version built immediately, that the response carries that build, and that refusals identify the offending line or size bound. It does not disclose permission/auth requirements or what happens to prior versions on update.

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, all front-loaded: the create/update distinction comes first, followed by definition constraints, versioning behavior, and error semantics. No filler and every sentence carries information an agent needs.

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

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

For a parameterless-required, five-param mutation tool with no output schema, the description covers create vs update, definition constraints, version/build behavior, and error reporting, and even notes the response carries the build. It omits the shape of the returned build object and whether non-dockerfile fields (name, size) are partial updates, leaving minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (name, size, starterId, dockerfile, templateId). The description reinforces the create-vs-update role of templateId and the Dockerfile rules, but adds little syntax or format detail the schema lacks; 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?

The description states a specific verb and resource ('Create a sandbox ... or change one') and immediately disambiguates the two modes via the templateId condition. It is clearly distinguishable from siblings like build_sandbox_template, delete_sandbox_template, and save_sandbox_registry 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 explicitly states the discriminator between create and update ('omit templateId'), which is real when-to-use guidance. It does not name alternative tools (e.g., build_sandbox_template or list_sandbox_starters) for related workflows, so it stops short of full routing guidance.

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