BTCDecoded Intelligence

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

Beyond the annotations, the description discloses concrete behaviors: live network fetch, capped comment thread, failure on private repos, precedent retrieval from the index, and no comment posting. These details reinforce the readOnly, idempotent, and non-destructive traits without contradicting 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?

Five short declarative sentences, front-loaded with purpose and key behavior. Every sentence contributes value, though phrases like 'scaffold' and 'Precedent from the index' are slightly cryptic and could be clearer.

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

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

For a two-parameter, read-only tool with rich annotations, the description covers access constraints, failure modes, side-effect absence, and live-fetch behavior. It does not describe the exact return shape, but no output schema exists and the behavioral detail is adequate for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with both ref and url already documented in the schema. The description adds behavioral context around public issues but does not add extra parameter-level guidance such as ref/url precedence, matching the baseline for high schema coverage.

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

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

Description names the resource (public GitHub issue), the behavior (live-fetches title, body, and capped comment thread), and explicit boundaries (private repos fail, does not post comments). This clearly differentiates it from sibling tools like analyze_pr or assess_argument.

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 useful context about when the tool applies (public issues) and exclusions (private repos), but it never explicitly states when to prefer this tool over alternatives such as analyze_pr or assess_argument. Usage is implied rather than directly routed.

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 indicate read-only, idempotent, non-destructive behavior, and the description adds meaningful behavioral detail beyond that: it fetches filenames and a capped patch pack, caps the live thread, fails on private repos, pulls precedent from the index, and does not post comments. This substantially helps an agent understand side effects and limits.

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

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

The description is short, front-loaded with the core purpose, and every sentence adds a distinct fact: public scope, fetched content, private-repo failure, precedent, and no comment posting. No filler or redundant restatement of the title.

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

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

The description covers the main inputs, key limits, failure behavior, and non-mutating nature, which is sufficient for an agent to select and invoke the tool. It does not explain what 'Precedent from the index' means in detail, but the overall fetch behavior is well specified.

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

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

Schema description coverage is 100%, and both parameters already have clear descriptions in the schema. The tool description does not add parameter-level details, but it does not need to because the schema fully documents url and ref.

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 states this tool fetches data for a public GitHub PR: filenames, a 4000-char patch pack, a capped live thread, and precedent. It is the only PR-specific tool among the siblings, and the phrase 'Does not post comments' further distinguishes it from mutating PR actions.

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 clear context: use it for a public GitHub PR, and private repos will fail. It does not explicitly name alternative tools or when-not-to-use conditions relative to siblings, but the public-PR scope and failure mode give an agent enough context to route correctly.

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

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

Annotations already cover read-only, idempotent, open-world, non-destructive traits, so the description is not obligated to restate them. It adds meaningful context beyond them: private repos fail, github_pr is not an arbitrary URL fetch, it is not a merge/payout/money check, and it does not post comments.

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

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

Front-loaded with the core purpose, then behavior, then limits, in short telegraphic sentences with no filler. The clipped fragment style is dense but every sentence carries information; it is not padded.

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

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

No output schema exists, so the description must convey return shape, and it does name the closed label set and structuredContent.rationale contents (met/unmet/unaddressed). That is nearly sufficient for a complex 7-parameter tool, though the exact structuredContent fields for requirement scores are only partially specified.

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

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

With 100% schema coverage the baseline is 3, but the description adds semantics the schema does not: github_pr is packed into the submission and private repos fail, the 'when' pin filters by passage-date prefix, and requirements scoring is conditional. Only 'caller_ref' echo behavior is left to the schema.

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

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

States a specific verb and resource ('Advisory spec-versus-submission check') plus the output contract: a closed judge label of met/not_met/ambiguous. This distinguishes it from siblings like verify_claim and analyze_pr. Jargon such as 'cite packs' is undefined, which slightly blunts first-read clarity.

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 real usage conditions: empty/off-topic cite packs yield ambiguous, requirements are scored only when packed cites bear on them, and github_pr must be public. However, it never explicitly says when to pick this over verify_claim or analyze_pr, so tool selection is left to inference.

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

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

Annotations already mark the tool read-only and non-destructive; the description adds the meaningful behavioral constraint that it performs no new synthesis and returns only a matching pattern plus citations. It also discloses provenance (internal product policy), which helps the agent calibrate how much weight to give the result. No contradiction with the readOnly/idempotent/openWorld hints.

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, and every clause earns its place: action, sources, output, and key constraints. The essential limitations are front-loaded before any elaboration.

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

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

For a single-parameter read-only tool, the description covers input, output shape, source scope, and a major limitation (internal policy, not evidence). It leaves details like exact `kind` values, citation formatting, and non-match behavior unspecified, but the absence of an output schema makes those gaps acceptable.

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

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

The schema already fully documents the single `text` parameter as a claim or thread excerpt, so the description adds little beyond restating 'the claim.' With 100% schema coverage, the baseline of 3 is appropriate; no format, length, or example guidance is added.

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 action ('Match the claim'), the target categories ('discourse game, numbered claim, or monopoly fallacy'), and the exact source documents to consult. It also specifies the output ('kind + heading pattern + cites') and draws a boundary against evidence tools by noting the files are internal product policy, not contemporaneous evidence.

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

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

It provides clear usage context by restricting the source documents to three internal files and explicitly says these are not contemporaneous evidence, which tells an agent not to use this tool for evidence-gathering. It also says 'No new synthesis,' framing it as classification rather than generation. It does not name sibling tools like verify_claim or find_discourse as alternatives, so it stops short of full when-to-use 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 cover the safety profile with readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the description's burden is lower. It adds one useful behavioral trait—mail/IRC cites often lack paths—but does not describe the return format, pagination, or operational constraints. No contradiction with 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?

Two sentences with zero waste: the main action and scope are front-loaded, and the mail/IRC caveat earns its place by shaping how the agent interprets results. No structured data is repeated.

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

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

For a read-only, idempotent tool with a rich annotation set, the description is serviceable, and no output schema exists to document return values. However, with 12 siblings sharing find/search verbs, the lack of explicit sibling routing or any note on result structure leaves meaningful gaps for an agent.

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 (path, repo, query, symbol, snapshot) already carries a meaningful description. The only added nuance, that mail/IRC rarely include paths, is a result-behavior observation rather than a parameter clarification. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb (Retrieve) and a concrete resource set (GitHub, mail, IRC, and Delving cites) scoped by a path or symbol, so an agent understands what the tool produces. It does not explicitly name a sibling to exclude, but the source-type list and the 'cites' scope separate it from the incident/precedent/spec finders among the 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?

There is no explicit guidance about when to use find_discourse versus the 12 sibling tools, and no alternatives are named. The only hint—'Mail/IRC rarely include paths'—concerns expected result quality, not tool selection. An agent must infer the tool's role without direct 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 establish that the tool is read-only, idempotent, and non-destructive. The description adds useful non-obvious context: it returns empty when the index has no passage, and it behaves like the search page. No contradiction with 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?

Two sentences with no filler; the core action and scope appear first, followed by useful behavior and empty-result semantics. Every sentence earns its place.

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

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

For a simple read-only retrieval tool with rich annotations and full schema coverage, the description covers the key edge case (empty result) and identifies the relation to search. It does not detail the cite output format, but given the simplicity this is a minor gap.

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

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

Schema description coverage is 100%, so the description does not need to compensate. It still adds value by giving a concrete CVE example and clarifying that query accepts incident names or CVE IDs, but the snapshot parameter is left entirely to the schema.

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

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

The description uses a specific verb ('retrieve') and resource ('index cites') and clearly scopes the tool to named incidents or CVEs with a concrete example. It references the search sibling but does not explicitly state the differentiating behavior, so it falls just short of full differentiation.

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

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

The entity scoping ('named incident or CVE') implies when to use the tool, and 'same search page as search' hints at shared behavior. However, there is no explicit guidance on when to prefer it over search or other siblings, and no when-not-to-use 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds a valuable behavioral limitation: 'Disposition is only what a cite heading or URL already says. Does not invent merged/rejected/stalled labels.' This goes beyond annotations and helps the agent trust results. It does not contradict 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 with zero filler. The main action is front-loaded, and the limitation is stated succinctly. Every word earns its place, and it is easy to scan.

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

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

For a simple retrieval tool with 2 parameters and no output schema, the description covers the core function and a key behavioral nuance. It does not describe the return format, but that is not required given the lack of an output schema. It is sufficiently complete for the agent to call it correctly.

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

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

Schema description coverage is 100%, and both parameters (query and snapshot) are described in the schema. The description does not add additional parameter-level detail beyond what the schema provides, but it does not need to. The baseline of 3 is appropriate given the schema's completeness.

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 (Retrieve), a specific resource (BIP, GitHub, and mail cites), and the scope (for a proposal). It distinguishes itself from sibling find_* tools by naming the unique source types, making it clear what this tool covers versus find_discourse, find_incident, etc.

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

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

The description implies usage for proposal precedent citations, but it does not explicitly state when to prefer this over alternatives or when not to use it. No exclusions or comparisons to siblings are given, so the agent must infer from the purpose. This is adequate but not explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds meaningful behavioral context beyond annotations: it specifies the output scope ('Cites only') and explicitly states what the tool does not do (emitting verdicts). This helps the agent set expectations without relying solely on structured data.

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

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

The entire description is two sentences with zero filler. It front-loads the core action and scope in the first sentence and adds the critical limitation in the second. Every word contributes to an agent's understanding.

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 two-parameter read-only tool with full schema coverage and no output schema, the description is sufficiently complete. It states what is retrieved, the input type, and the key boundary (no verdicts). The snapshot parameter is fully explained in the schema, so no additional description is required.

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

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

Schema description coverage is 100%, so both 'query' and 'snapshot' are already well-documented. The description loosely restates the query's purpose ('spec section or behavior') but does not add new parameter-level detail. Baseline 3 applies because the schema carries the 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?

The description begins with a specific verb and resource ('Retrieve spec, Core source, and GitHub cites') and immediately distinguishes this tool from siblings by adding 'Cites only. Does not emit aligned/gap/divergence verdicts.' This makes it clear what the tool produces and what it deliberately does not, separating it from analysis/verdict tools like assess_argument or verify_claim.

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 clear context for when to use the tool: to retrieve cites for a spec section or behavior. It also states a key exclusion ('Does not emit aligned/gap/divergence verdicts'), guiding the agent away from using it for verdicts. It does not name specific sibling alternatives, but the exclusion is strong enough for an agent to make the right choice.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral guidance beyond annotations: negative results are common (found=false) and the agent must not invent employment or affiliation. No contradiction with 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 compact and each sentence earns its place: scope, dataset size, negative-result frequency, and anti-fabrication rule. However, the first sentence is structurally confusing and could be clearer without adding length.

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 lookup, the description covers input semantics and a common failure mode, but with no output schema it only vaguely promises 'facts' and does not enumerate likely fields. An agent cannot fully predict the response shape, and the wording leaves ambiguity about whether output is facts or a name.

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

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

The schema has 100% coverage, including case-insensitivity and the found=false behavior. The description's mention of 'unique public GitHub name' partially overlaps with the schema's parameter description, adding little new meaning. 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 identifies a specific resource (GitHub login or unique public GitHub name) and what is returned (public-record facts from a curated research set). It is not vague, but the first sentence is grammatically awkward ('or that login's unique public GitHub name') and does not explicitly distinguish this tool from its analysis/search 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 description gives useful context: the known set is small (canonical maintainers) and most logins return found=false, implying this is a narrow lookup rather than a general-purpose search. However, it does not state when to prefer an alternative tool or what to do after a not-found result.

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 non-destructive behavior. The description adds useful behavioral context beyond that: this reads a stored index passage rather than doing a live fetch, and ok false signals the index has no passage. This meaningfully augments the annotation-only 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?

Two concise sentences carry the core purpose, parameter guidance, a limitation, and a return-condition caveat. Every sentence adds information and the main purpose is front-loaded.

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

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

For a simple read-only retrieval tool with no required parameters and no output schema, the description covers the essential input alternatives and a key response condition. It does not spell out the full return shape or define ok, but the missing detail is minor and partially compensable by annotations.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds input-combination guidance ('id from the cite, or source plus doc'), which is helpful, but it omits the uri parameter that the schema marks as preferred. Overall the description slightly augments the schema without carrying the parameter burden.

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

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

The description uses a specific verb and resource: 'Return the stored index passage for a search cite.' It also clarifies what the tool is not ('Not a live web fetch'), which helps distinguish it from broader search or web-fetching tools.

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

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

The description gives concrete calling guidance: 'Pass id from the cite, or source plus doc.' It also explains the meaning of ok false, giving the agent context for interpreting results. It does not explicitly name sibling alternatives, but the usage context is clear enough for a storage-retrieval 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover safety and non-mutating behavior. The description adds a small note about cost ('Free') and behavior about as_of. However, it doesn't explain the return format or how the snapshot is retrieved, and with output schema absent, the description carries more burden. Given the high annotation coverage, a 2 is slightly harsh; but the description adds limited behavioral context beyond what annotations suggest.

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

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

The description is three short sentences with no fluff. It front-loads the core purpose and includes the free and as_of behavior. Each sentence adds value and the structure is clean.

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

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

Given the tool is a simple replay with one parameter and rich annotations, the description covers the essential usage. It doesn't describe return format but that's allowed since output schema is absent and it's a minor gap. The description is sufficient for an agent to call it correctly.

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

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

Schema coverage is 100%, so the parameter 'id' is well documented as a snapshot_id from a prior tool result. The description reiterates the purpose ('Replay a stored dated report') which adds slight context but doesn't provide additional parameter details beyond the schema. Thus, baseline 3 is appropriate.

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

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

The description clearly states the action ('Replay a stored dated report') and the resource ('stored dated report'), and it distinguishes from related tools like search by noting it does not re-search or re-judge. While it doesn't explicitly name a sibling, the differentiation from search is 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?

The description indicates when to use it: to replay a stored dated report without re-searching, and clarifies that a new as_of means calling the original tool. It doesn't explicitly state what tools to use instead, but the context implies a distinction from search and analysis tools. It provides clear context for use.

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, open-world, non-destructive), and the description adds genuinely non-obvious behavior: the two-layer model that both layers are searched unless a source pins one, and the failure contract ('If ok is false, the index has no passage'). It stops short of return format or pagination details, but the failure and layering semantics are substantive additions 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?

The decision-relevant facts (what it is not, layer pinning, ok=false semantics) are front-loaded, but they are followed by an exhaustive run-on catalog of sources that reads as prose documentation rather than a callable definition. The source= labeling gives some structure, yet the size is driven by enumeration rather than by what an agent needs to invoke the tool.

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

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

With no output schema, the description carries the full burden of explaining returns, and while 'Cited... index' plus 'Footnotes label domain' hints at citation structure, there is no description of result shape, ordering, or result limits. Coverage of the corpus scope and failure behavior is solid, but the output contract remains underspecified for a complex search 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%, so the baseline is 3. However, the description goes further by mapping raw enum values to real meaning (source=price → CoinMetrics PriceUSD every close since 2010-07-18; source=textbooks → named titles), which an agent cannot derive from the bare enum. This is real added value over the schema.

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

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

The description opens with a noun phrase ('Cited Bitcoin coordination index') and clearly scopes what the index is not (live quote, ETF, derivatives, chain analytics), but never states the action with a verb. A reader can infer this is a retrieval/search tool over cited passages, yet nothing distinguishes it from siblings like get_passage or find_discourse without opening their schemas.

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

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

It says 'Pin a layer with source' and 'Every plan searches both layers,' which hints at the source-pinning behavior, and the 'not a live quote/ETF/derivatives' line is a useful exclusion. But there is no guidance on when to choose this tool over the many sibling retrieval tools (get_passage, find_discourse, find_precedent), leaving alternatives entirely unaddressed.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description adds valuably by disclosing edge-case behavior: possible return states like 'skipped' and 'no_passage,' and the warning that 'The judge is not a source.' This goes well beyond the annotation hints.

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 concise and front-loaded: it states the core action, then invocation pattern, then return behavior. The typo 'noul' (apparently 'null') is a minor blemish that prevents a perfect score, but every sentence 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?

Even without an output schema, the description enumerates the key return conditions, input alternatives, and a critical caveat about the judge not being a source. For a 4-parameter tool with strong annotations, this is sufficient for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful grouping and provenance: id comes 'from a search cite,' and source is used 'with doc,' clarifying the two valid invocation forms beyond the schema's individual property 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 opens with a specific action and resource: 'Score whether a stored index passage supports a claim.' It also distinguishes itself from sibling search/retrieval tools by emphasizing it uses a stored passage and is 'not a live web fetch.'

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

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

It gives clear invocation context: 'Pass id from a search cite, or source plus doc,' which tells an agent when and how to call it. It also warns this is 'not a live web fetch,' but it does not explicitly name sibling tools as alternatives, so it stops short of full when/when-not routing.

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