elliot-mcp

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

Annotations only declare readOnlyHint=false and openWorldHint=false; the description usefully adds what is created and where (three named files under elliot-report/<date>-<commit>/). It does not disclose whether existing files are overwritten, whether the audit is locked afterwards, or what happens with unrecorded candidates, so it stops short of a full behavioral picture.

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

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

A single front-loaded sentence with no filler; the action and its concrete outputs come first and nothing is redundant.

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

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

For a state-mutating finalization tool with no output schema, the description covers the produced artifacts but omits the preconditions for a successful call, the effect on audit state, and what is returned on success or failure.

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%, and the description says nothing about any of the three parameters. In particular the significant 'skipped' array (risk-sweep items with reasons that appear in the report) and the 'out_dir' override are left entirely to the schema, so the description does not compensate for the coverage gap.

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

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

States a specific verb ('Close the audit') and enumerates the exact artifacts produced (report.html, report.md, claims.json) plus their destination path. It is distinguishable from most siblings, but it does not clarify how it differs from the sibling elliot_report, which plausibly also emits a report.

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: 'Close the audit' suggests this is the terminal step of an audit workflow, but there is no explicit statement of prerequisites (an open audit_id from elliot_audit_start, claims already recorded) or of when to prefer this over elliot_report.

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

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

Annotations declare readOnlyHint=false and openWorldHint=false, and the description corroborates the mutating nature by disclosing that it 'pins the commit' and returns a protocol to follow. It does not say whether the pinned state is persistent, whether concurrent audits conflict, or what cleanup is required against elliot_audit_finish. Still, the key side effect is surfaced, which is real value beyond the annotations.

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

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

A single dense sentence whose first clause states the core purpose and whose remaining clauses front-load the concrete outputs. No filler, no repetition of the title, nothing that could be cut without losing 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 no-required-param session-start tool with full schema coverage, no output schema and meaningful annotations, the description covers purpose, side effects, and the returned artifact ('the protocol to follow'). What is missing is lifecycle context: how long an audit stays open and its relationship to elliot_audit_finish. That is a modest gap, not a blocking one.

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 richly documented in the schema, including the default working directory and the fact that 'sources' disables the repo-wide risk sweep. The description adds nothing about either parameter, so it sits at the baseline. The phrase 'lists the files that make claims' loosely gestures at the sources scoping but no more than the schema already says.

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

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

The description gives a specific verb and resource (audit whether the repo matches its README/docs/security/pricing claims) and enumerates the concrete effects: pinning the commit, listing claim-bearing files, returning a protocol. That is far more than a restatement of the name. It does not name elliot_audit_finish as the counterpart, so sibling differentiation is only implied by the word 'Start'.

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 verb 'Start' plus 'returns the protocol to follow' implies this is the entry point of a multi-step audit before elliot_record_claim / elliot_audit_finish, but that sequencing is never stated. There are no explicit when-not conditions or named alternatives. The agent must infer the workflow position rather than being told it.

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

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

Annotations only tell the agent this writes to a closed-world target; the description adds the substantive preconditions (no doc sentence may promise otherwise, must belong to a specific sentence) that govern a valid record. It stops short of saying what recording does downstream — dedup, ID returned, effect on the audit — so it is not fully transparent.

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

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

Front-loaded with the core purpose and only three sentences long; the examples and the sibling routing each earn their space. The closing instruction 'Never attach this to an unrelated sentence' is slightly oblique since no sentence parameter exists in the schema, costing a point.

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

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

For a 7-parameter write tool with no output schema, the description covers the conceptual bar for behavior/docs_searched but omits what a successful call produces and how audit_id or signal should be sourced. Adequate to call correctly in principle, but an agent must infer the plumbing from the schema alone.

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 71%, and the description adds real meaning for two of the trickiest fields: what counts as 'behavior' (with concrete examples) and the evidentiary standard behind docs_searched ('the docs never mention... no doc sentence promises otherwise'). It says nothing about audit_id, severity, or signal, leaving those entirely to the schema.

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

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

Specific verb+resource ('record something risky the code does that the docs never mention') with three concrete examples of qualifying behavior. It also names the sibling elliot_record_claim and the exact condition that separates the two, so an agent can route without opening a schema.

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

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

Explicitly states when to use this tool (undocumented behavior with no doc promise), when to use the alternative instead ('If a doc sentence does promise otherwise, use elliot_record_claim on that sentence'), and an exclusion ('Never attach this to an unrelated sentence').

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

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

Goes well beyond the annotations by disclosing the validation contract: source quotes are checked against the docs at those lines, evidence quotes against the code, and 'absent' searches are executed server-side. It does not say whether a rejected claim is persisted, whether resubmission replaces a prior claim, or what a successful submission returns, which are the remaining behavioral unknowns for a mutating call.

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

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

Three tight sentences, front-loaded with the action, then the validation mechanics, then the failure remedy. Nothing is repeated from the schema and no sentence is filler.

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

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

Adequate for a 9-parameter nested-schema tool whose fields are 89% documented: the description covers the one thing the schema cannot, namely that quotes and absence checks are independently verified. It stops short of describing the success response, which matters slightly since there is no output schema.

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

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

Schema coverage is 89%, so the baseline is 3; the description earns an extra point by clarifying that for 'absent' evidence the agent supplies only a pattern and Elliot performs the search, which is non-obvious from the schema alone.

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

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

States a specific verb and resource ("Submit one claim with its verdict and evidence") and names the payload triple, so an agent can distinguish it from elliot_record_behavior and elliot_record_review without opening any schema.

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

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

Gives clear retry guidance once validation fails ("fix the citation and submit again"), which is the main decision point for a per-claim submitter. It does not explicitly route against sibling recording tools, so the alternative-selection half of the guidance is left implicit.

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

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

Goes well beyond the annotations by disclosing the enforcement rule that all evidence is verified against the actual files, which implies submissions can fail validation on unverifiable quotes. It also states the per-outcome evidence obligations. It stops short of saying what happens on a failed check or whether a decision can be revised later.

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

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

Four short sentences, front-loaded with the purpose before the mode prerequisite and evidence rules. The 'For the reviewer process:' opening is slightly clipped but no sentence 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?

There is no output schema, so the description must carry the result story, and it does not say what the tool returns or what an agent sees after a successful or rejected review. For a state-mutating review tool with 7 parameters, the mechanics of failure and the returned decision record are a material gap.

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

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

Schema coverage is 57% and the description adds real meaning for outcome by spelling out what counts as valid evidence for confirm versus reject. However, it restates reviewer_token already documented in the schema, never mentions the severity parameter, and introduces an 'absent search' evidence kind that the schema's evidence.type const ('quote' only) cannot express.

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

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

States a specific verb (record/review) and resource (one finding) with the exact decision vocabulary (confirm, downgrade, reject), scoped to 'the reviewer process'. It is clearly distinct from sibling recorders like elliot_record_claim or elliot_record_behavior, though it never names those siblings to reinforce 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?

Gives a clear situational frame ('for the reviewer process') plus a mode-specific prerequisite: supply the audit-scoped reviewer_token from the evidence packet in isolated mode. It does not route the agent away from alternatives (e.g. elliot_review_packet) or say what to do when a finding is not yet reviewable, so the exclusion half is missing.

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 read-only and closed-world, so the safety profile is covered. The description adds that the report summarises recent receipts and includes counts of checked and upheld claims, which is useful context but not rich behavioral detail such as data range or return format.

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

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

Two tight sentences with no wasted words. The purpose is front-loaded, and the usage instruction follows naturally.

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

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

For a simple read-only summary tool with one fully documented parameter and no output schema, the description provides the essential purpose and usage context. It could clarify the scope or meaning of 'recent' beyond the limit parameter, but otherwise 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 100%, and the sole limit parameter is fully documented in the schema with its default and range. The description does not add meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: summarising recent receipts, including the metrics 'claims checked' and 'held up'. It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools such as elliot_review_packet or the verify_* tools.

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

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

It gives a clear usage trigger: show this when the user asks what the agent really did. It does not provide explicit exclusions or name alternative tools, so it is not a full 5.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries real weight and delivers: the payload is limited to findings and checked evidence, an ELLIOT_REVIEW_TOKEN is required for the configuration described, and the auditor endpoint cannot record review decisions. That is genuinely useful operational context an agent would not get from the 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 return contract before the security caveat. Every sentence carries information; no filler, though the security sentence is dense and could be split.

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 no output schema, the description says little about the shape of the packet beyond 'findings and checked evidence', which a fresh reviewer process must parse. The critical security/role guidance is present, but the caller lacks detail on packet structure and on audit_id semantics.

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

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

There is one required parameter (audit_id) and schema description coverage is 0%, and the description never mentions it. The schema's regex pattern at least signals the audit_<hex> format, but nothing in the prose explains where to obtain the id or what it identifies.

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: it returns findings and checked evidence, and the word 'only' scopes the payload away from decisions/summaries that sibling tools like elliot_report or elliot_record_review presumably handle. It is clear what the tool produces, though it never explicitly names which sibling it replaces.

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?

'Give it to a fresh reviewer process' states the intended consumer directly, and the closing sentence gives an actionable deployment constraint (use a separate ELLIOT_ROLE=reviewer server). There is no explicit 'do not use this when...' exclusions, but the intended use case is unambiguous.

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

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

Annotations declare readOnlyHint=false and openWorldHint=false, so the agent already knows this is a bounded, non-read-only operation. The description adds the scope (tracked + untracked files) but never explains what state the non-read-only behavior creates — where the snapshot persists, whether a prior snapshot is overwritten, or how expensive it is on a large repo.

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 with the action and the downstream purpose front-loaded, and no filler. Every clause carries information an agent needs.

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

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

With zero required parameters, no output schema and a trivial schema, the definition covers purpose, timing and downstream linkage adequately. The remaining gap is what the fingerprint operation actually stores and returns, which matters somewhat given readOnlyHint=false.

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

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

The single `path` parameter is fully documented in the schema, including that any path inside the repo works and that the server's working directory is the default. The description adds no syntax or edge-case detail beyond that, which is acceptable given 100% schema coverage.

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

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

It names a concrete action and resource — fingerprinting every tracked and untracked file in a git repository — and ties that output to a specific consumer, verify_changes. That is enough for an agent to distinguish it from the other verify_* and elliot_record_* siblings.

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

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

The phrase 'before starting a task' plus the reference to verify_changes later gives a clear trigger and pairing. It stops short of stating exclusions (e.g. don't run mid-task or on non-git directories), so it is clear context rather than a full when/when-not rule.

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

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

With no output schema, the description carries the return-value burden and does so well: it discloses that valid=true requires both signature pass and an explicitly supplied matching key, and that omitting the key yields crypto validity flagged as untrusted signer. That is substantive semantics beyond the readOnly/openWorld annotations and does not contradict them.

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

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

Two tight sentences, front-loaded with the core action and then the conditional valid/public-key rule. No wasted text and the key caveat arrives early.

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

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

No output schema exists, and the description adequately covers return semantics and the security caveat, making the tool safe to call correctly. The only shortfall is silence on the shape of the required nested receipt object, which an agent may need before invoking.

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?

At 50% schema coverage, the public_key behavior is reinforced by the description, but the required 'receipt' parameter — a nested free-form object — gets no explanation of its expected structure or fields. Marginal value added over the schema, no compensation for the gap.

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

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

States a specific verb and resource — 'Verify an Ed25519-signed Elliot receipt and its digest' — plus the exact cryptographic scheme. This clearly distinguishes it from siblings like verify_changes, verify_url, or verify_outcome, which handle other artifact types.

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 explains the decision condition for supplying public_key (trusted signer identity vs. math-only check), which is real usage guidance. However, it never states when to reach for this tool versus the many sibling verify_* tools, leaving tool-level routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's added value is the comparison semantics: it compares against a prior snapshot or, failing that, HEAD. That is real behavioral context an agent cannot get from the annotations or schema alone, though it says nothing about what a negative or ambiguous result 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?

Two sentences, zero filler: the action and its baseline come first, the usage trigger second. Nothing could be removed without losing 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 zero-required-parameter, read-only verification tool this covers what to compare, against what, and when to call it. The one remaining gap is the result shape — whether it returns a boolean, a per-file diff, or a mismatch report — which is not covered by an output schema.

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

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

Schema description coverage is 100%, so path, claim, paths and snapshot_id are all documented in the schema itself. The description only reinforces the snapshot_id-vs-HEAD fallback; it adds no meaning for the paths filter or the claim string beyond what the schema already says. 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: checks whether files actually changed, with the comparison baseline named (snapshot taken before the task, or HEAD by default). This clearly separates it from verify_url, verify_github, verify_npm, which verify external artifacts rather than local file diffs.

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 to use it "before claiming code was fixed, cleaned, refactored or written", which anchors the tool to a concrete moment in the workflow. It also states the default baseline (HEAD when no snapshot is given), but does not name any sibling tool as an alternative or exclusion.

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 and openWorldHint=true, so the safety and external-call profile is covered structurally. The description adds a genuinely useful auth prerequisite ('Set GITHUB_TOKEN for private repos'), but says nothing about behavior on missing refs, rate limits, or whether a failed check is an error or a negative verdict.

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 every clause earns its place by naming a distinct check mode or a prerequisite. The colon-separated enumeration is dense but scannable, with no filler.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it never says whether the result is a boolean, a verdict with evidence, or an error on a failed check. The check-to-parameter mapping is also left implicit, so a caller can still mis-invoke it despite otherwise adequate coverage.

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 schema already documents pr, ref, repo, and claim; the baseline of 3 applies. The description adds modest value by implying which check each input answers (PR-based vs. ref-based), but never states explicitly that `pr` is required for pr_merged/checks_passing while `ref` is required for commit_exists/checks_passing — a pairing the agent must infer.

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

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

The description names a specific verb and resource ('Check what GitHub actually says') and then enumerates the three exact checks it performs — PR merge status, CI check status, and commit/branch existence — which map directly onto the check enum. This clearly differentiates it from siblings like verify_npm and verify_url, which cover other verification surfaces.

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 enumerated checks give clear context for when each mode applies (verifying a merge claim vs. a CI claim vs. a pushed-commit claim), and the private-repo token note signals the prerequisite. There is no explicit when-not guidance or named alternative for overlapping checks, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe external read. The description adds the pre-claim verification intent, but says nothing about what a failed check looks like (error vs. negative result) or how the claim parameter influences the response — meaningful gaps for a verification gate with no output schema.

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

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

Two sentences, zero waste, with the action stated first and the usage rule second. Nothing to trim and nothing buried.

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

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

For a four-parameter verification tool with no output schema, the description never indicates the shape of the verdict the agent should expect or how to interpret a failure, which is exactly what an agent needs to act on the result. Adequate but with a clear gap.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the published_after proof-of-new-publish semantics. The description only echoes name and version, 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: check the npm registry for a package and version. The npm-registry scope implicitly separates it from verify_github and verify_url, but no sibling is named explicitly to confirm that 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?

"Use before claiming a package or release was published" gives a concrete trigger condition tied to the other elliot_record_claim-style tools. It lacks an explicit when-not or a named alternative, which keeps it below a 5.

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

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

Substantially exceeds the annotations: it discloses disposable-copy isolation, network blocking, that writes are confined to the copy, the exit-code-zero rule for VERIFIED, pipefail injection for bash, and the INCONCLUSIVE fallback when the sandbox cannot start. This also explains why readOnlyHint=true holds despite commands that write files, which is genuinely additive context.

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

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

Front-loaded with the core action and scope, then progressively narrower operational caveats in four tight sentences with no filler. Each sentence carries distinct information (isolation, shell recipe, file placement, failure mode).

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 5-parameter tool with no output schema, it covers the important unknowns: isolation, network policy, success criterion, and one failure terminal state. It does not enumerate the full result vocabulary beyond VERIFIED/INCONCLUSIVE, which is the only remaining gap an agent might hit when interpreting output.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: the bash + ["-c", "..."] pattern for pipelines (the schema only says 'No shell is used'), and the constraint that every needed file must live in the repository, which implicitly scopes path. It says nothing about claim or timeout_ms, leaving those to the schema.

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

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

The first sentence states a specific verb and execution context: run a command and arguments in a disposable repository copy under the host OS sandbox. It is far more precise than the title alone and makes clear this is a functional-check executor rather than a metadata/URL/npm verifier. It never names the sibling verifiers (verify_changes, verify_npm, verify_url) it is distinguished from, so it stops short of a 5.

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

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

Usage is implied by the constraints: it explains the shell-pipeline recipe (command bash, args ["-c", "..."]) and warns that files outside the repository do not exist in the sandbox. There is no explicit 'use this instead of verify_changes/verify_npm when...' routing, and no stated exclusions, so the agent must infer when to reach for this tool versus its siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-network profile is covered. The description adds that it checks status and optionally body text, but says nothing about timeouts, redirects, authentication, or what happens on failure. With annotations carrying the safety burden, this is adequate but not rich.

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

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

Two tight sentences, front-loaded with what the tool does and followed by the decision context. Every sentence earns its place with no redundancy.

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

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

The tool is simple and all parameters are well documented in the schema. However, there is no output schema, and the description does not explain what a verification result looks like (e.g., pass/fail, observed vs expected status, text-match outcome). For a verification tool, that return-value gap keeps it at minimum viable completeness.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description restates the purpose of the URL, status, and text checks but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The description states a specific verb ('check/verify') and resource ('a URL') and clarifies the scope: response status and optional expected body text. It does not explicitly differentiate itself from narrower siblings like verify_github or verify_npm, leaving the agent to infer that this is the generic URL checker.

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 usage context: 'Use before claiming something is deployed or live.' This tells the agent when the tool is appropriate. It does not name alternatives or state when not to use it, which keeps it below a 5.

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