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

Annotations only declare the mutation profile (readOnly=false, idempotent=false, destructive=false); the description adds non-obvious domain behavior: a step with an evidence gate cannot be marked done until a non-note row exists, and a step-less row satisfies no step gate by design. That gate interaction is exactly the context annotations 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?

Front-loaded with the gate rule, then parameter-level guidance in short paragraphs. Slightly more prose than strictly needed (the REST-route justification is rationale rather than instruction), but every sentence carries actionable 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?

An output schema exists so return values need no explanation, and the description covers the mutation's downstream effect and the step_id optionality rule. It does not sketch what a valid ref/data pairing looks like per kind, but that is a minor gap for a 5-param create 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 coverage is 80%, but the description still adds meaning to step_id (omit for project-level evidence, contrast with the REST route accepting null) and to kind (note vs. gate-satisfying kinds). Remaining kinds like pixel_diff and file_hash are only enumerated 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 ('Record structured evidence for a step') and immediately ties it to the evidence gate. An agent can tell this is the write-side counterpart to list_evidence 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?

Explicitly says when to use kind='note' (supplementary remark, does not satisfy the gate) and when to omit step_id (project-level evidence such as measurement, console transcript, negative result). Both branches are covered with their consequences.

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

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

Annotations already declare destructive, idempotent, non-readonly behavior, so the bar is lower; the description still adds real context beyond them by explaining the host-lease release and the conditional process termination when this server owns the host. It does not say what happens to partial artifacts or whether cancellation is refused in terminal states.

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

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

One sentence, front-loaded with the action, with the mechanism in a tight parenthetical. Nothing is wasted and nothing is 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?

An output schema exists, so return values need not be explained, and the mutation semantics are covered. Still missing for a destructive sibling-rich tool: how to identify the run, and how this differs from job_cancel.

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

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

Schema description coverage is 0% for the single required run_id, so the description must compensate, and it does not — no format, no hint to obtain it from build_list or build_status. The parameter is entirely opaque from the text.

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 ('Cancel a run') and adds the concrete effect of marking it cancelled and releasing its host lease. It is distinguishable from build_start/build_status/build_wait, though it does not explicitly separate itself from the similarly named sibling job_cancel.

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 name and effect but never stated: no guidance on when to cancel versus letting a build run, and no mention of the job_cancel alternative for job-level runs. An agent must infer the calling conditions.

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

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

Annotations already declare readOnly/idempotent/closed-world, so safety is covered. The description usefully adds result ordering (newest first), which annotations cannot express, but omits pagination, result limits, and retention window for a list operation.

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

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

A single front-loaded fragment with no waste; the resource and ordering come first, filters second. The compressed 'and/or' phrasing is slightly terse but still parseable.

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?

An output schema exists and annotations cover the safety profile, so the description need not explain return values. For a low-complexity two-optional-param list tool it is nearly sufficient, with only result count/pagination left unstated.

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

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

Schema description coverage is 100% and both parameters are already documented ('Only queued/running runs', 'Restrict to one host'). The description only restates those filters in shorthand, adding no syntax or default-behavior detail, so baseline 3 applies.

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

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

States a specific verb+resource (list recent build runs) plus ordering (newest first) and optional filters, so the agent knows exactly what comes back. It does not distinguish itself from siblings like build_status or diff_builds, which is the only gap.

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 filter conditions ('optionally one host and/or active only') imply the browse-recent-runs use case, but there is no explicit when-to-use vs. build_status, build_log, or diff_builds guidance and no 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 this as a read-only, idempotent, closed-world operation. The description adds useful behavioral context beyond annotations: it decodes UTF-16 logs, reports detected encoding, indicates truncation, and surfaces MATERIAL GUARD warnings from the full log. It does not contradict any annotations.

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

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

The description is two sentences and front-loads the core action. Every sentence adds useful information: the first states the purpose, and the second explains decoding, truncation, and warnings. There is no wasted wording.

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 low-risk annotated read operation and the presence of an output schema, the description covers the key special behaviors an agent needs: UTF-16 decoding, truncation, and MATERIAL GUARD warnings. Minor gaps remain around run_id semantics and explicit selection versus sibling tools, but overall it is sufficiently complete.

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

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

Schema description coverage is 50%: the lines parameter is documented in the schema, but run_id has no description. The description implies that run_id identifies the build run whose log is tailed, but it does not document format or acquisition. This is adequate but leaves a clear gap.

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

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

The description states a specific verb and resource: "Tail a build run's log." It clearly identifies the operation and the special UTF-16 decoding behavior. However, it does not explicitly differentiate itself from the closely related sibling build_status, 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?

The description does not say when to use build_log versus alternatives such as build_status or build_wait. The parenthetical "see build_status" points to another tool but does not establish selection criteria. Usage is only implicit from the tool name and purpose.

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; the description adds the useful operational detail that overwrite=true will replace an existing .vmdl and that the tool returns the written path. It also discloses the important constraint that the document is only compiler-acceptable and must be built on a host with resourcecompiler, which an agent could not infer from annotations alone.

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 core action, then the path convention, then the follow-up build step. Slight redundancy with the multi-line indentation, but no wasted content.

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?

Covers what the tool produces, the path semantics, the overwrite behavior, and the downstream build step, and an output schema exists so return values need not be spelled out. The remaining gap is the unexplained `name` and `translate` parameters for a six-parameter write 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 only 33%, and the description compensates partially: it defines `mesh` as addon-relative with an example and explains `overwrite`. However, `name` and especially `translate` (an array of numbers, presumably an offset) are left entirely undefined in both schema and description.

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 artifact: writes a Source 2 model document (.vmdl) for a mesh already in the addon. It also distinguishes itself from the sibling build_start by clarifying that this tool only emits the document and that compilation happens elsewhere.

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

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

Gives the sequencing rule (compile afterwards via build_start) and the condition for the overwrite flag (replace an existing .vmdl). It does not name an explicit alternative for building without writing a document, but the routing to build_start is clear enough.

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 openWorldHint=true; the description adds genuinely non-obvious behavior: the call is asynchronous (returns a run id immediately), the host lease is server-owned and auto-released at terminal status, and lease phase equals the run `kind`. It omits any note on failure modes of the SSH command itself or permission requirements, keeping it short of a 5.

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

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

What the tool does is front-loaded in the first clause, followed by operational guidance and then lease semantics. The STUCK/list_hosts passage is dense and slightly tangential to invoking this tool, though it does explain how to interpret the resulting run's state.

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 needn't be explained, and the description still states that a run id comes back immediately. Async behavior, lease lifecycle, and the correct follow-up call are all covered, which is everything an agent needs to invoke this 5-parameter, 2-required tool correctly.

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

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

Schema coverage is 80%, so the baseline is 3, but the description adds real meaning to `kind`: its value becomes the lease phase shown on list_hosts, which is not stated in the schema. `notes` and `log_path` are left entirely to the schema, so this is additive but incomplete.

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 ("Start a server-owned build run on a host") plus the mechanism (acquires lease, runs command over SSH, returns run id immediately). This clearly distinguishes it from build_status, build_wait, build_cancel, and build_list in the sibling set.

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 away from sleep-polling toward build_wait(run_id) or build_status, which is the key decision an agent faces after calling this. It does not, however, contrast build_start with adjacent launchers like test_start or deploy_push, so the sibling-exclusion guidance is partial rather than complete.

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 (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds critical domain behavior beyond them: a run can appear 'succeeded' while material guard warnings indicate the map will error-render as a checkerboard. This is a high-value gotcha that directly affects interpretation.

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 first sentence front-loads the record contents, and the second explains the warnings guard. It is somewhat detailed but the material-guard explanation earns its place because it prevents a critical misinterpretation.

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

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

Given an output schema, annotations, and complete schema coverage for the single parameter, the description is nearly complete. It explains the warning field's behavioral meaning but could briefly clarify its relationship to build_wait and build_log.

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 run_id parameter is already documented in the schema as coming from build_start. The description adds no additional parameter meaning, so the schema carries the full 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?

The description clearly identifies the resource as 'One build run's record' and enumerates what it contains: status, exit code, summary counts, material guard warnings, and artifacts. It lacks an explicit action verb like 'retrieve' and does not distinguish itself from close siblings such as build_log, build_wait, or build_list.

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 does not state when to use this tool versus build_log, build_wait, or build_list. The only implied usage is inspecting a single run's record, with no explicit alternatives 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 and idempotentHint, so the safety profile is covered; the description adds genuinely new behavior — server-side blocking, a raise on timeout, and the subtle rule that strict_materials turns material-guard warnings into an error even when status is 'succeeded'. That last point is exactly the kind of non-obvious semantics an agent cannot infer.

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 doing distinct work: what it does, what failure looks like, and the strict-mode edge case. Blocking behavior is front-loaded, and there is 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?

An output schema exists, so return-value detail is unnecessary, and the description still notes that the run record is returned. For a long-blocking tool with error-on-timeout behavior, the essentials are covered; only an explicit pointer to build_status as the non-blocking alternative 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 67%, with timeout_sec and strict_materials already documented in the schema. The description adds meaning for strict_materials beyond the schema's phrasing by explaining the failure condition relative to the run's success status, and the timeout raise condition is reinforced. run_id is self-evident.

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 — block until the run finishes, then return its record — and the parenthetical '(server-side, no client sleep loop)' distinguishes it from the polling pattern an agent would otherwise use. It never names the sibling it replaces (build_status), so it falls short of 5.

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

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

Clear context for when to call: you want to wait for completion rather than poll. Timeout behavior and the strict_materials escalation are spelled out. However, it does not explicitly route an agent to build_status for non-blocking checks or to build_cancel when waiting is undesirable.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, so the safety profile is covered; the description adds substantial unstated behavior—stale-lock takeover, STUCK detection driven by phase freshness, and the expectation to keep phase current. It doesn't explain force or the TTL interaction explicitly, which is the only real 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?

Four sentences, front-loaded with the core operation, then failure semantics, then the phase/heartbeat obligation and release step. Dense and useful throughout, though the phase guidance is slightly repetitive.

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 lock-mutation tool with an output schema, the description covers acquisition, failure, takeover, stuck detection, and release—everything an agent needs 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%, so baseline is 3; the description adds meaning by tying phase to server-side stuck detection and to heartbeat_host updates, which the schema only hints at. It does not discuss force or ttl_sec semantics, so it exceeds baseline without being exhaustive.

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 ('Claim exclusive use of a host') and positions the tool within a lifecycle by naming heartbeat_host and release_host. An agent can tell it apart from those siblings without opening any schema.

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

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

Explicitly explains the core condition: fails when another owner holds a fresh lock, but a stale lock is taken over automatically. It goes on to prescribe the follow-up flow (heartbeat while working, release_host when done), leaving little 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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds useful behavioral context by stating results are newest first, but it does not define how many 'recent' deployments are returned or whether pagination applies.

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

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

The description is a single compact sentence that front-loads the resource and ordering with no wasted wording. Every phrase contributes useful information.

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

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

For a one-parameter, read-only list tool with a full schema, rich annotations, and an output schema, the description is largely sufficient for correct invocation. The main remaining ambiguity is the scope of 'recent' and any result limit, but that is not required to call the tool successfully.

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 host_id parameter is already documented as 'Restrict to one host.' The description's 'optionally one host' duplicates that schema information without adding format or edge-case semantics.

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

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

The description identifies the resource (deployments), the ordering (newest first), and the optional host filter. It is clear what the tool returns, but it does not explicitly name a verb such as 'list' or distinguish itself from sibling actions like deploy_push and deploy_verify.

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

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

The description provides no guidance on when to use this tool versus alternatives such as deploy_verify, deploy_push, or the other *_list tools. The only conditional detail, 'optionally one host,' describes filtering rather than tool selection.

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

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

Goes well beyond the annotations (destructive, non-idempotent, open-world): it discloses the host-lease lifecycle (claimed as 'deploy:<id>', released when the copy finishes), the conflict semantics, and the project-lease convention 'project:<project_id>'. This is exactly the mutating-side-effect context an agent needs before invoking a destructive tool.

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

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

Front-loads the action and the post-check in the first sentence, then details the lease model. Dense but mostly earning its place; the parenthetical asides ('the `cs2_live_test` deploy step does', 'hashed/sized on push') add a bit of clutter.

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?

An output schema exists, so describing return values is optional — the description covers them lightly (deploy id entries with md5 + verified flags). Lease and conflict semantics are complete; the only shortfall is unexplained secondary parameters (dry_run, parallel, addon).

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 63% schema coverage, the description compensates by explaining `owner` in depth (pass another's owner if it's you, pass 'project:<project_id>' inside a project) and implying verify behavior and the file manifest. However, `dry_run`, `parallel`, and `addon` are not explained anywhere, leaving gaps.

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

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

States a specific verb+resource: copy files to a host, verify hashes over SSH, return a deploy id with md5/verified flags. It explicitly distinguishes itself from the sibling deploy_verify ('Call deploy_verify later to re-check'), so an agent can route between them 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?

Gives clear operational context: call deploy_verify afterward for re-checks, and pass `owner` when another party holds the lease or when inside an orchestration project. It explains the conflict case (host held by another owner) but doesn't broadly state when NOT to use this versus deploy_list or build flows — still strong guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description usefully adds that the check runs on the host and that status is mutated, but it omits what happens on checksum mismatch (does the deploy fail, does the tool error, does status change to failed?) – the single most important behavioral fact for a verify 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?

One sentence, front-loaded with the action resource, zero filler. Every clause carries information.

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

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

Output schema exists, so return values need not be explained, and the parameters are fully documented. What's missing is the failure semantics and any prerequisite state (deployment must exist and be in a verifiable state), which matters for a status-mutating operation.

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 deploy_id already documents its provenance ('Deploy id from deploy_push'). The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb and resource: re-check a recorded deployment's MD5s on the host, then update its status. That is clearly distinct from deploy_push and deploy_list in the sibling set, though it doesn't explicitly name those siblings.

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

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

No guidance on when to call this versus deploy_push or deploy_list. The phrase 'recorded deployment' implies a prior deploy_push, and 're-check' implies verification, but neither prerequisite nor timing is stated explicitly.

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 past the annotations (readOnly/idempotent/openWorld) by disclosing output semantics that matter for correctness: `group` clusters members under their parent, `before`/`after` hold only the member's own value, and crucially `counts` is computed BEFORE the per-section `limit` cap so it remains accurate when output is truncated. That truncation caveat is exactly the kind of trait an agent could otherwise misread.

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 granularity before descending into output-field mechanics. The tail (counts/totals/limit explanation) is dense and partly redundant with the existing output schema, costing some economy without being 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?

An output schema exists and annotations cover the safety profile, so the description is free to skip return values — yet it still spends most of its words describing result shape. What is missing is the reference to the `sections`/`limit` inputs it alludes to, leaving a small gap about how truncation is actually controlled.

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 defaults for to_build/from_build are already documented there, so the schema carries parameter meaning. The description arguably muddies things by referencing `sections` and `limit` as if they were inputs, yet neither appears in the input schema — an agent has no way to set them.

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 ('Show what changed between two ingested builds') and immediately qualifies granularity ('one row per added/removed/changed ...'). The enumeration of member kinds (schema field, entity member, game-event field, script symbol, convar, Pulse binding, Hammer class) makes it unmistakably distinct from build_list or search_docs.

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 concrete triggering context: 'Use it after a game patch to find code or configs that might break.' That is a clear when-to-use signal, but no explicit when-not or named alternative (e.g. compare against build_list for raw build metadata) is offered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds valuable context that subclasses inherit the input/output and that candidates should be checked with get_entity, which is behavior beyond the annotations. It does not mention rate limits or auth, but those are less critical here.

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 purpose and followed by a crucial inheritance note and follow-up action. Every sentence earns its place with zero 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?

An output schema exists, so return values need not be explained, and annotations cover safety. The description gives the essential behavior and a follow-up step, but the lack of any mention of 'side' or 'limit' leaves a minor gap for optional parameters.

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

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

Schema coverage is 50%: 'game' and 'name' are described in the schema, while 'side' and 'limit' have no description anywhere. The description only references 'name' indirectly ('input or output with this name') and gives no meaning for 'side' or 'limit', failing to compensate for the coverage gap.

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

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

States a specific verb ('Find') and resource ('entity classes') with scope ('including base classes') and the search target ('input or output with this name'). It distinguishes itself from get_entity by directing follow-up checks, but does not explicitly differentiate from siblings like list_schema_classes or get_schema_class.

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?

Implies a workflow by saying 'check candidates with get_entity', giving some context on how to use results. However, it does not state when to use this tool versus alternatives (e.g., list_schema_classes) or any exclusions, leaving usage largely inferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds no behavior beyond that: it doesn't say whether the file list is recursive, whether paths are absolute, or what happens when the named addon does not exist locally.

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 or redundancy. It is efficient, though its brevity is also the source of the gaps in usage and behavior.

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

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

For a simple read-only tool with full schema coverage and an output schema, the essentials are present. The one thing an agent would still need is the relationship to list_addons and read_addon_file, which is absent from the description.

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 parameters are well documented in the schema (game id values, the lowercase name pattern with an example). The description adds nothing beyond that, 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 action on a specific resource: it returns an addon's local root path and its file list, which is more than a restatement of the name. It does not differentiate itself from the nearby siblings list_addons and read_addon_file, so an agent still has to infer the split.

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

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

There is no statement of when to call this instead of list_addons (which also deals with addons) or read_addon_file (which reads contents). No prerequisites, no exclusions, no alternatives are named.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is fully covered. The description adds only a listing of returned fields, which the existing output schema already supplies, so marginal behavioral value beyond structured data is modest.

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 zero waste, front-loaded with the verb and resource, and the return payload summarized in a compact parenthetical.

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?

A simple two-parameter lookup with an output schema and full annotations, so little prose is required; the description is sufficient to call it correctly. The only missing piece is explicit routing against list_convars.

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 ('game' with an inline id list, 'name' as exact convar/command name) are fully documented in the schema. The description's mention of 'variable or command' and 'exact' name reinforces the schema but adds no new parameter meaning.

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

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

Specific verb+resource ('Get a console variable or command') with an enumeration of what's returned (default, min/max, flags, help text). It is implicitly distinguishable from the plural sibling list_convars, but it never names that sibling to make the boundary explicit.

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

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

Usage is implied by the singular 'get' framing and the exact-name requirement, but there is no explicit statement of when to use this over list_convars or search_docs, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful return context (Markdown body, URL, license for citation) that the annotations can't express, but says nothing about failure behavior for an unknown or malformed key.

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 tightly packed sentence with zero filler, leading with the action and resource and closing with the citation-relevant returns. Nothing is redundant with the title or 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 an output schema present, the description does not need to explain return values, and it still notes the Markdown format and license. For a one-parameter read tool this is nearly complete; only the error path for an invalid key is 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?

Only one parameter at 100% schema coverage, so the schema already explains 'key' and even gives an example format ('s2wiki:/Basics'). The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('Get a community documentation page (source2.wiki)') plus the output medium (Markdown) and what accompanies it (URL and license). This implicitly separates it from search_docs and list_docs, though it never names those siblings to make the distinction explicit.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. Usage is only implied by the schema note that 'key' comes from search_docs, which suggests this is a follow-up fetch step rather than a discovery tool.

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

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

Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is fully covered. The description adds useful context that inherited members are merged in and that a `defined_in` field marks the declaring base, but nothing about how large a result can get or how missing entities behave.

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

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

Two sentences, zero waste, with the resource and payload contents front-loaded and the `defined_in` clarification as a short follow-up.

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?

An output schema exists, so return values needn't be spelled out, and required params are clear from the schema. The one real gap is the undescribed `side` parameter, which also interacts with the `side:classname` input form mentioned in the schema.

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

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

Schema description coverage is only 50%: `game` and `classname` are documented, but `side` and `include_inherited` have no schema descriptions. The description partially compensates by explaining that inherited members are included, which maps to `include_inherited`, but `side` (server/client) is never explained at all.

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

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

States a specific verb and resource ('Get a Hammer entity') and enumerates exactly what comes back: keyvalues with choices, inputs, outputs, and inherited members. That is far more specific than the sibling search_docs or find_entities_with_io, though it never names those siblings to contrast itself against.

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

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

Usage is only implied: the required classname plus 'or `side:classname` from a search key' signals this is the follow-up lookup after a search. It never states when to prefer this over find_entities_with_io or get_schema_class, nor any preconditions.

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 openWorldHint=false, so the safety profile is covered. The description adds only that the return is the full source of a Valve-written example; it says nothing about errors for unknown names or how the game parameter affects resolution.

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

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

Two short sentences with the core action front-loaded and no filler. The second sentence is advisory rather than descriptive, which slightly dilutes structure but still earns its place as guidance.

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

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

With a complete output schema, full annotation coverage, and a two-parameter schema, the description covers what an agent needs to invoke it. Only the relationship to list_examples and failure behavior are left implicit.

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

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

Schema description coverage is 100%, with both 'game' (enum-like list of ids) and 'name' (with a format example) documented in the schema. The description adds no parameter-level meaning beyond that, so it meets the 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?

Names a specific verb and resource ('Get the full source of an example script'), which is unambiguous. It does not explicitly distinguish itself from the sibling list_examples, but 'full source' versus a listing is implicitly clear.

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?

'Prefer adapting these Valve-written patterns' hints at the intended use (using examples as reference material), but there is no explicit when/when-not guidance or named alternative such as list_examples for discovery.

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 closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: the returned definition is the *effective* one after core/game/mod override resolution, which tells the agent the result may differ from raw source files.

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 verb, resource, return content, and the override caveat in a tight parenthetical. Nothing wasted and the key scope qualifier is front-loaded.

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

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

An output schema exists, so return shape needs no prose, and both required parameters are schema-documented. For a two-param read tool this is nearly complete; only the relationship to list_game_events is left unstated.

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

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

Schema coverage is 100% — both 'game' (cs2, deadlock) and 'name' (e.g. player_death) are documented inline. The description adds only indirect meaning via the override mention and does not restate formats, 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 (Get) and resource (game event) and adds what is returned: fields and types. It reads clearly against neighbors like get_entity and get_schema_class by naming the 'game event' domain, though it never names list_game_events as the contrasting sibling.

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: an agent can infer this is the detail lookup complementing list_game_events, but the description never states when to call it versus that lister or versus get_schema_class. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds the notion that the entry includes a 'lock' and 'probed facts', which hints at freshness/state, but it does not say what happens for an unknown host_id or how stale the probed facts may be.

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 field list is front-loaded. It is slightly terse to the point of being a fragment, 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?

With a dedicated output schema and read-only annotations already present, the description only needs to frame what the entry contains, which it does. Missing only edge-case behavior (nonexistent host, lock semantics), which is minor at this complexity.

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

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

Schema coverage is 100% and the single host_id parameter is documented with an example ('build-pc'), so the schema carries the load. The description adds no syntax, format, or lookup-behavior detail beyond that, which is the baseline-3 case.

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

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

Names the resource (one host's registry entry) and enumerates its contents (ssh target, shell flavor, probed facts, lock), so an agent knows exactly what comes back. It is a noun phrase without an explicit verb and only implicitly separates itself from list_hosts (via 'one host's'), but the intent is unmistakable.

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

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

There is no statement of when to call this versus alternatives such as list_hosts, probe_host, or claim_host. The only routing hint ('Host id from list_hosts') lives in the schema, not the description, so an agent gets no usage guidance from the text itself.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is fully covered. The description adds real value by disclosing the depth of the payload (per-step status, notes, artifacts, recent events), which tells the agent this is a heavy full-state read rather than a summary. It stops short of noting cost/verbosity or pagination 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?

A single compact clause with no filler, and the most useful information (breadth of state returned) is front-loaded. It loses a point only because the fragment lacks an action verb, which would have cost nothing to include.

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

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

For a one-parameter read tool with an output schema and full annotation coverage, the description supplies what the structured fields do not: the scope of returned state. Missing only an explicit signal about payload size or how it relates to list_projects.

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 project_id parameter already documents its format and origin ('from start_project, e.g. p-1a2b3c4d'). The description adds nothing about the parameter, 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?

Names the specific resource ('project state') and enumerates what it contains (step status, notes, artifacts, recent events), which implicitly distinguishes it from list_projects and start_project. However it is a noun fragment with no verb, and it never explicitly states 'retrieves one project by id' or names the sibling it differs from.

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

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

No statement of when to call this versus list_projects, next_step, or update_step, and no preconditions. The agent must infer that this is the deep-read counterpoint to the shallow list tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine context — it explains this exists as a fallback for prompt-incapable clients — but says nothing about how arguments are applied or what the rendered text looks like.

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, zero waste, with the purpose front-loaded and the audience qualifier trailing as a subordinate clause. 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?

An output schema exists, so return values need not be explained, and annotations cover safety. The one thing left implicit is how the optional 'arguments' object is threaded into the rendered prompt, a mild gap for a 2-parameter 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 the 'name' parameter even enumerates the valid prompt names in its description. The description adds no parameter-level 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?

Specific verb ('render') plus specific resource ('one of this server's prompts') and output form ('as text'). It is unambiguous and no sibling tool in the list deals with prompts, so no explicit differentiation is needed, though none is offered.

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

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

States the selecting condition clearly: clients that can't fetch MCP prompts mid-task. That is an explicit when-to-use rule, but there are no named alternatives or when-not-to-use exclusions (e.g. what a prompt-capable client should do instead).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so safety and determinism are covered. The description adds that results include the inheritance chain and direct subclasses, but says nothing about behavior when a class/enum is missing, name ambiguity across modules, or whether include_inherited changes output shape.

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

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

Two sentences, front-loaded with the verb+resource and then usage contexts; no filler, no restating 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?

With an output schema and annotations present, the description only needs to add selection and input nuance, and it partly does. However, for a two-required-param lookup against multiple games and modules, it omits how to disambiguate same-named classes and what include_inherited does, leaving real gaps for correct invocation.

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

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

Schema coverage is 75%: game, name (including the 'module:Name' form) and module are documented in-schema, while include_inherited has no description at all. The description's mention of the 'inheritance chain' hints at inherited-member behavior but never explains the include_inherited flag or the relationship between the name and module parameters.

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

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

States a specific verb and resource ('Get an engine schema class or enum') and enumerates the payload: fields, types, defaults, metadata, inheritance chain and subclasses. An agent can tell it is a single-item lookup rather than a listing, though it never names the nearest sibling list_schema_classes 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 second sentence gives concrete use cases (networked fields, VData keys for Deadlock abilities, plugin offsets), which is real selection guidance rather than a generic 'use this to get a class'. It stops short of stating exclusions or pointing to list_schema_classes/search for discovery.

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, closed-world), so the description focuses on lookup semantics: type lookups include inherited members, member lookups include signatures and docs. It also discloses the non-obvious `Instance` = `Domain` alias, which is not derivable elsewhere; only minor details like not-found behavior are absent.

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

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

Four short sentences, front-loaded with what it looks up and followed immediately by the return-shape distinction. No filler; only the final alias sentence is slightly tacked on rather than integrated.

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 and the `game` parameter fully documented in-schema, the description only needs to nail lookup semantics and it does. Faint gaps remain around error/empty-result behavior for unknown symbols.

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 3 baseline applies, and the description earns a bump by explaining the consequence of each input form (type → full member set with inheritance; anything else → matched members with signature and docs) and by revealing the `Instance` alias that the schema does not mention.

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 ('Look up the CS2 cs_script (point_script) JavaScript API') and clarifies the two lookup modes. It is distinguishable from siblings like list_script_types and search_docs, but it never names those alternatives to reinforce the distinction.

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

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

It explains what to pass (a type name vs. anything else) and what each form yields, which is implicit guidance on how to use it. It gives no guidance on when to prefer this over search_docs, get_doc, or get_schema_class, so the agent must infer routing.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so safety/idempotency is covered structurally. The description adds real value by disclosing that re-heartbeating the same phase intentionally does not clear stuck-ness and that a new phase resets the clock, but says nothing about lock expiry windows or failure behavior.

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

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

Two short sentences with the purpose front-loaded and the phase caveat immediately after. Some residual indentation/backtick formatting is slightly noisy 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?

With annotations covering idempotency and an output schema handling return values, the description covers the operational essentials an agent needs. Only lock-expiry timing and error conditions are left 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 coverage is 100%, so owner, host_id and note are fully documented. The description's discussion of the phase parameter largely restates the schema's own note ('pass the same value to keep it, a new one to reset the clock'), adding only the stuck-ness framing, so baseline 3 applies.

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

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

States a specific verb and resource ('Refresh your lock's heartbeat') and its goal ('so it doesn't go stale mid-task'), which distinguishes it from claim_host/release_host siblings. It doesn't explicitly name those siblings, which prevents 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?

Gives clear context for when to call (mid-task, to avoid a stale lock) and a concrete caveat about re-heartbeating the same phase versus reporting a new one. It stops short of explicitly naming alternatives like claim_host or release_host for lock lifecycle changes.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description contributes the useful behavioral nuance that an existing assignment can be *moved*, but says nothing about what happens if the job is already running or what the prior host assignment becomes.

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 twelve-word sentence with the operation front-loaded and no filler. It is efficient bordering on terse; nothing is wasted, though the brevity pushes remaining burden onto the caller.

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, full annotation coverage and complete parameter docs, the description is serviceable but thin. It omits preconditions (job must be queued, host must be claimed) and does not mention that setting position reorders surrounding jobs, which matters for a scheduling 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 coverage is 100% and each parameter carries an example-bearing description, so the baseline is already met. The description adds a bit more by tying 'queue order' to the otherwise thin position parameter and framing assignment as movable.

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

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

States a concrete verb-and-resource pair: 'Set (or move) a queued job's host and queue order.' The 'queued' scoping separates it from job_start/job_cancel and the 'move' wording signals reassignment rather than creation. It stops short of naming a sibling to contrast with, so a 4 rather than 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?

The description gives no when-to-use, when-not, or alternative routing at all; the only hint is the adjective 'queued.' Nothing tells the agent to prefer job_enqueue for new work or claim_host for host-side reservation, leaving differentiation to inference from the name 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 declare the mutation/non-idempotent profile, but the description adds real value beyond them: append-only with no overwrite, and the side effect that images auto-record a screenshot event. That explains the non-idempotency and a hidden write the agent would otherwise not anticipate.

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, zero waste, with the core action front-loaded and the append-only constraint and side effect immediately after.

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 and annotations covering the safety profile, the description supplies the key behavioral facts (append-only, image side effect). It is only slightly short on edge cases such as name collisions, file size limits, or failure behavior for a missing local path.

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 path and job_id are already documented in the schema with the same Mac-local framing. The description adds no detail on the optional `name` parameter (overriding the basename) and no format guidance 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?

Specific verb+resource: copies a local file into a job's artifacts, with the scope (MCP runs on the Mac) made explicit. It clearly distinguishes itself from add_evidence or write_addon_file by naming the destination as job artifacts, though it does not call out those siblings by name.

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: attach a file to an existing job. There is no explicit when-to-use versus alternatives (add_evidence, job_link), nor any stated prerequisite that the job must already exist via job_enqueue.

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 non-read-only, non-destructive, non-idempotent mutation, and the description adds real information beyond them: the allowed source states and the side effect that the reason lands on the job timeline. It does not say whether an already-running job is interrupted gracefully or what state the job ends in on rejection, so it is not 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?

One compact clause with the state transition front-loaded and the side effect second; nothing is wasted. It is arguably compressed to the point of omitting a needed precondition-failure clause, but every word present 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 an output schema, full parameter coverage, and safety annotations present, the definition is close to self-sufficient. The remaining gap is behavioral on the failure path: what happens when the job is not queued/running, and whether cancellation is immediate for a running job, is left unstated.

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

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

Schema coverage is 100%, so both job_id ('from job_enqueue/job_list') and reason are already documented; baseline 3 applies. The description only echoes the schema's note that the reason is recorded on the timeline rather than adding format, length, or default behavior.

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 encodes a precise state transition ('queued/running -> cancelled'), which tells an agent the operation and its precondition far better than the tool name alone, and the 'job' framing distances it from build_cancel. It stops short of any explicit sibling differentiation (job_finish, job_restatus), which keeps it from 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?

The precondition 'queued/running' implicitly defines when the tool applies, so usage is inferable rather than stated. There is no explicit statement of when-not-to-use it, no guidance on a job already finished or failed, and no named alternative for stopping work in other states.

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

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

Beyond the annotations it discloses two real behaviors: validation is aggregate (all missing required fields surface in a single error with a field list) and 'ask' leaves the job queued and unassigned until picked up. It does not spell out that repeated calls create duplicate jobs despite idempotentHint=false, which would have earned 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?

Two short sentences, front-loaded with the action and the state transition, then the two most operationally important facts. Nothing 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?

Given an output schema and 100% schema description coverage, the description needn't restate returns or parameter syntax, and it correctly focuses on the intake-gate behavior. For an 18-parameter tool it is a little thin on which fields the gate actually enforces, but it is sufficient to call 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's mention of host_choice='ask' and the 5-minute cap only restates what the schema already documents for those parameters; it adds no new semantics for the other 15 fields.

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

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

A specific verb+resource ('enqueue a job') plus the state transition it performs ('validated intake -> queued'). An agent can distinguish it from the job_* siblings that consume/assign/finish jobs, though no sibling is named explicitly.

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

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

It hints at the creation context ('the intake is the gate') and gives one operational hint ('host_choice=ask to queue unassigned'), but there is no explicit when-to-use / when-not, no naming of alternatives like job_assign or job_next, and no prerequisite guidance.

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

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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive write. The description adds meaningful behavior: appending a timeline event, mutating the job's current phase when phase is provided, and supporting failure expansion via data.log_tail.

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 compact and front-loaded, with no wasted text. It communicates the core operation and key conditional behavior efficiently.

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?

An output schema exists, and annotations cover the safety profile. The description supplies enough context for correct invocation, though it does not fully explain all event levels or the relationship to sibling job 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?

Schema description coverage is 80%, so the schema already documents most parameters. The description reinforces phase and log_tail semantics, but adds limited meaning beyond the existing schema descriptions.

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

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

The description uses a specific verb and resource: 'Append one timeline event' to a job. It clearly identifies the operation, but it does not explicitly differentiate this tool from related job tools such as job_restatus, job_verdict, or job_finish.

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 useful conditions for specific fields: phase updates the job's current phase, and error/crash events require a message and should carry data.log_tail. However, it does not state when to use this tool instead of the many sibling job tools or when not to use it.

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

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

The annotations only say readOnly=false and destructive=false. The description adds the validation rule: the call is rejected unless all four summary fields are non-empty and at most 600 characters, and the error names the offending fields. That is real behavioral detail beyond the annotations, but the description does not say what state the job ends in, whether the call can be retried, or that an idempotentHint of false means a second close-out fails.

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

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

It is three short sentences and front-loads the core action before the validation gate. Each sentence carries information, though the parenthetical example of a stopped demo is slightly verbose for the space it takes.

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?

An output schema exists, so return values need no prose, and the description covers the rules of the one mutation this tool performs. It explains the required summary shape, what happens on rejection, and the difference between inconclusive and passed, so nothing essential is missing for a correct call.

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

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

Schema coverage is 100%, so the field descriptions already define job_id, status and the summary object. The description tells the caller more than the schema alone: the four summary keys are each subject to a non-empty and length check, and violation rejects the call; and it explains what status='inconclusive' actually means, which the schema only lists as an enum value.

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

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

The description opens with a specific verb and resource: 'Close out a running/queued job.' That distinguishes it from job_cancel, job_verdict and job_restatus by implication, but the description never names those siblings, so the agent must infer the boundary. Purpose itself is unambiguous.

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

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

It gives a clear condition for the 'inconclusive' status: a run that ended without a pass/fail verdict, such as a step-gated demo the user stopped answering, and explicitly says this is not a pass. How this tool relates to siblings such as job_verdict or job_cancel is not stated, so the caller must infer when to use this tool rather than one of those.

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 openWorldHint=false, so safety is covered. The description adds useful content beyond that by saying the payload is a 'full timeline' plus cross-entity links and artifacts, i.e. it is a heavyweight detail fetch rather than a summary. It says nothing about size, pagination, or behavior when the job id doesn't exist.

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 front-loaded sentence with no filler — the important part (full detail incl. events/links/artifacts) comes first. It reads as a sentence fragment, which is efficient but slightly telegraphic.

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 description needn't explain return values, and annotations cover safety; what remains is adequate for a one-parameter read tool. The main shortfall is absent guidance on when to prefer it over job_list or job_event.

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 job_id parameter is already documented with a format example ('j-1a2b3c4d') and provenance. The description adds no additional meaning to the parameter, 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 the resource ('One job') and enumerates what the response carries — timeline events, links to test runs/builds/deploys/evidence, and artifacts — which is specific enough to separate it from job_list's collection view. The verb is only implied ('One job with...'), so it stops short of a clean verb+resource phrasing.

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 sentence tells the agent when to reach for this versus job_list, job_event, or job_screenshots. The only routing hint ('Job id from job_enqueue/job_list') lives in the schema, not the description, so the description itself gives no usage guidance.

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