The Stochastic Parrot

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

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly reveals this is a read operation ('Fetch') and describes the returned payload in detail, including 'verified contradictions with verbatim spans' and 'naming/framing splits.' It does not discuss edge cases like missing slugs, but for a straightforward getter this is reasonably 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?

A single, efficient sentence that front-loads the operation ('Fetch... by slug') and then lists the payload contents, with the slug-source pointer at the end. Every clause earns its place; 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?

For a one-parameter getter with no output schema, the description is complete: it identifies the input, where to get it, and what the return value contains. No critical calling information is missing.

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

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

Schema coverage is 100%: the slug property already has a description and an example. The description adds meaningful provenance guidance ('Slugs come from search_corpus or list_audits'), which tells the agent how to obtain a valid parameter value beyond the schema's literal definition.

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 the verb 'Fetch' with a specific resource ('one piece's full detail JSON by slug') and enumerates the contents returned, which clearly distinguishes it from sibling list/search tools like list_audits and search_corpus. An agent can tell exactly what this tool does without opening the schema.

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

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

It explicitly tells the agent where valid slugs come from ('Slugs come from search_corpus or list_audits'), which is actionable guidance for invoking the tool. It does not explicitly name alternatives to avoid, but the fetch-by-slug semantics and sibling names make the usage context clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. The phrase 'frozen per-day stat snapshot' usefully implies a stable, read-only historical view, which adds meaning beyond the tool name. However, it does not mention what happens for missing or future days, whether the result can be absent, or any other behavioral edge cases.

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

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

The description is two compact sentences with no filler. The core identity is front-loaded, and every sentence contributes either to defining the resource or to supporting correct invocation.

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 retrieval tool, the description is largely complete: it defines what is returned, what parameter is needed, and where to find valid values. The absence of an output schema is partially mitigated by the phrase 'stat snapshot', though more detail about the response shape or error behavior would improve 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%, and the day parameter is already documented with its format. The description adds extra value by stating that valid day values are discoverable at /boxscore/ on the site, which helps the agent obtain a correct parameter value rather than only knowing its format.

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

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

The description clearly identifies the resource as a per-day box score and describes it as a frozen stat snapshot, which is specific and distinguishable from the sibling get_* tools. It states a clear verb-resource pairing and explains the core scope (one day). It does not explicitly contrast with siblings, but the unique resource name and 'frozen per-day snapshot' make the purpose 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?

The description gives explicit context for when to use the tool: for a single day's boxscore, and it clarifies that the day parameter is required. It also tells the agent where to discover valid day values ('days are listed at /boxscore/ on the site'). It provides clear usage context, though it does not discuss when not to use this tool versus alternatives.

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

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

With no annotations provided, the description carries the full burden, and it does well: it discloses both invocation modes and the contents of the full result ('pieces in order, claim ledger, and reopen conditions'). It does not discuss errors or explicit read-only guarantees, but 'get/list' strongly implies retrieval.

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 no wasted words. It front-loads the definition and then provides clear, structured usage guidance for both valid call patterns.

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 optional-parameter tool with no output schema, the description is nearly complete: it tells the agent exactly what to expect in both modes and what the full chain contains. It does not cover invalid-chain_id behavior, but that is minor given the low 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 description coverage is 100%, so the baseline is 3. The schema already explains that chain_id comes from the no-argument listing and that omitting it lists all chains. The description adds only minor context about returning 'one chain in full'.

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 ('story chains: multi-piece storylines the desk has covered more than once') and the actions ('list' and 'pass chain_id for one chain in full'). This distinguishes it from sibling tools like get_claim_ledger or get_coverage_record by resource and purpose.

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 explicit usage instructions: call without arguments to list available chain ids, or pass chain_id to retrieve one chain. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide how to invoke 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?

With no annotations provided, the description carries the behavioral disclosure burden. It goes beyond a generic 'get' by explaining the state model, the existence of receipts for transitions, and the meaning of an empty claims list. It does not explicitly state read-only behavior or error cases, but the tool name and ledger framing make side effects unlikely.

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, front-loaded with the resource identity, and each clause earns its place. The state enumeration and empty-list note provide real guidance without redundancy or fluff.

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, no-output-schema tool, the description explains the nature of the returned data, the lifecycle states, and how to interpret an empty result. It stops short of detailing the receipt or claim object shapes, but the definition is functionally complete for selecting and invoking the 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?

The input schema already documents the only parameter, 'chain', with an example slug format and 100% coverage. The description adds no new parameter-level detail beyond reinforcing that the chain is a story chain, so it meets the baseline for schema-covered 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?

The description clearly identifies the tool as exposing a story chain's claim ledger, which is a distinct resource among the sibling get_* tools. It specifies the content (specific verbatim claims outlets made), the tracked states, and the receipt-per-transition structure, so an agent can immediately tell this from get_audit or get_coverage_record.

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

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

The description implies the tool is used to inspect a story chain's logged claims and provides an important interpretation rule for an empty result. However, it does not explicitly state when to prefer this tool over alternatives or define conditions where it should not be used, so the usage guidance is mostly 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?

No annotations are provided, so the description carries the behavioral burden. It usefully discloses that the record includes gaps and that silence should not be interpreted without consulting it. However, it does not explicitly state read-only semantics, return format, or other operational behavior, though the get_ name implies a safe retrieval operation.

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

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

Two short, information-dense sentences with no filler. The first defines the record's content, and the second provides the critical usage rule. The most important guidance 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 zero-parameter read-only tool with no output schema, this description is complete. It states what the record contains, that it includes gaps, and when to use it. Nothing essential is missing for an agent to call this 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?

The tool has zero parameters, so the schema already fully covers this dimension. The description adds useful context about what the record represents, but no parameter-level semantics are needed. Baseline 4 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 names a specific resource — the capture-coverage record — and defines its content as 'what the desk's observatory actually monitored and when, including gaps.' This is clearly distinct from the sibling tools like get_audit or get_boxscore. It lacks an explicit action verb like 'retrieves' or 'lists,' but the get_ prefix and 'Read this' make the purpose 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?

The description gives a concrete when-to-use instruction: read this before treating any silence in the corpus as meaningful. This is an explicit, actionable usage rule. It does not name alternatives or state when not to use the tool, but the conditional guidance is strong enough for an agent 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains what metric is computed and what output facets are included, which implies a read-only reporting operation, but it does not explicitly state return format, caching, side-effect absence, or any access requirements.

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

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

The description is a single dense sentence that front-loads the metric name and uses a dash-separated list to enumerate outputs. Every clause adds useful information, with no repetition or filler.

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

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

For a no-parameter report tool, the description covers scope, definition of the metric, totals, rate, monthly trend, per-outlet appearances, and its role as a core longitudinal measurement. It does not specify the exact return shape or data structure, but since there is no output schema, 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?

The tool has zero parameters and the input schema is empty, so schema coverage is effectively 100%. The description correctly does not need to explain parameter semantics, and the baseline for a no-parameter tool 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 clearly identifies the Framing Index as a specific longitudinal measurement across the cross-outlet corpus, with enumerated outputs such as totals, rate, monthly trend, and per-outlet appearances. It is distinct from sibling tools like get_claim_ledger or get_coverage_record, though it does not explicitly name any alternative.

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 'The desk's core longitudinal measurement' implies a use case, but the description gives no explicit when-to-use or when-not-to-use guidance, and does not contrast this tool with any sibling. An agent would have to infer when to select this over other get_* tools.

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

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

With no annotations present, the description carries the disclosure burden. It is transparent about the detailed returned content and flags optional data ('where one exists'), while the 'get' verb signals a read operation; however, it does not address edge cases like missing storyboards or any access constraints.

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

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

The description is one dense sentence with no filler; each clause adds a distinct facet of the returned data. It front-loads the core resource ('chain's per-newsroom storyboards') before listing subcomponents.

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

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

There is no output schema, so the description compensates by enumerating the main contents of the result: per-outlet entries, objective label, motive/read/confidence, label arc, and optional synthesis. Together with the schema's chain-slug definition, this is largely sufficient, though it omits any note on empty results or failure behavior.

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

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

The single parameter 'chain' is fully documented in the schema with an example, and schema coverage is 100%. The description adds no new parameter-level detail, so it neither harms nor improves the schema's contribution.

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 retrieval operation ('get') on a clearly bounded resource: a chain's per-newsroom storyboards, with an enumerated breakdown of what those boards contain. This is readily distinguishable from siblings like get_framing_index or get_claim_ledger because the output object is specified.

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 makes clear the tool is for fetching a chain's per-newsroom storyboards and takes a chain slug, which implies the trigger condition. It does not explicitly compare with alternative tools or state when not to use it, so the agent must infer selection from the resource name.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by specifying that only published pieces are listed, results are summaries rather than full content, ordering is newest first, and all filters can be combined. It does not disclose potential pagination behavior or error conditions, but the core behavior is 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?

The entire description is one compact, front-loaded sentence that communicates the core action, return summary fields, ordering, and filter behavior. There is no redundant or filler 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?

Even without an output schema, the description explains what the tool returns (summaries with specific fields), how they are ordered, and that all filters are optional and combinable. With five parameters fully documented in the schema and no required parameters, the description is sufficiently complete for an agent to call the 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 description coverage is 100%, so the schema already documents all five parameters thoroughly. The description adds a useful behavioral note that filters are optional and combinable, but it does not provide additional parameter-level semantics beyond the schema.

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

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

The description starts with 'List published pieces' and enumerates the exact summary fields returned (slug, title, kind, date, counts of hard contradictions and naming/framing splits), making the resource and scope specific. The ordering ('newest first') and filter behavior further distinguish this from sibling tools like get_audit or search_corpus.

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 clearly states that filters are optional and combinable, which gives useful invocation guidance. However, it does not explicitly tell the agent when to use this tool versus alternatives like get_audit, list_corrections, or search_corpus, or what kinds of tasks are better suited to those tools.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It usefully discloses that the data is public, scoped to corrections on published pieces, and returned in original ledger order. However, it does not mention pagination, response format, or explicitly confirm there are no side effects, though 'ledger' and 'list' weakly imply read-only 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?

The description is a single, well-structured sentence. It front-loads the core identity ('public corrections ledger') and then efficiently lists the content and ordering. Every phrase 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?

For a zero-parameter, read-only list tool, the description is nearly complete: it defines scope, content, ordering, and public accessibility. Without an output schema, it could be more explicit about the exact returned fields, but 'what was wrong, what changed, and when' gives a solid expectation.

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

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

The tool has zero parameters, and the schema confirms this with an empty properties object. The description provides all necessary semantic context; there are no parameter expectations to clarify. The baseline for zero-parameter tools is 4.

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 tool as a corrections ledger listing logged errors on published pieces, including what was wrong, what changed, and when. It is easily distinguishable from sibling tools like get_audit or list_letters because it specifically targets corrections entries, though it does not explicitly name a sibling alternative.

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 when to use it: whenever an agent needs the public record of corrections for published pieces. It does not explicitly state when not to use it or compare it to related tools such as get_audit or get_claim_ledger, leaving some routing inference to the agent.

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

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

With no annotations, the description must disclose behavior; it mentions the content format (excerpted, initialed, replies) but does not state whether this is a read-only operation, any ordering/pagination, or side effects. The 'only interactive surface' phrase is ambiguous about interaction.

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

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

Two sentences, no fluff, front-loads the subject. The second sentence adds useful context about the desk's relationship with readers, though it is not strictly necessary.

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

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

For a parameterless list tool without an output schema, the description gives a sense of what is returned (excerpts and replies) but omits an explicit statement of the listing action, ordering, or scope, leaving some ambiguity.

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

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

The tool has zero parameters, so per baseline the schema leaves nothing undocumented; the description adds contextual detail about the letter content, which is sufficient for a parameterless tool.

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 the resource ('Letters to the Desk') and characterizes the content ('reader mail, excerpted and initialed, with the desk's replies'), but it lacks an explicit verb such as 'lists' or 'returns'. The tool name supplies the action, yet the description alone does not clearly distinguish it as a retrieval operation.

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 is given on when to use list_letters versus alternatives like submit_letter or get_chain. The note that it is 'the desk's only interactive surface' hints at its role but does not explain conditions 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?

With no annotations, the description carries the full behavioral burden. It discloses that the tip only lands in a queue, that the desk decides whether anything is filed, and that a reader key is required. This clarifies the tool is a suggestion mechanism, not a direct filing action.

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 action and target are front-loaded, and the second sentence efficiently adds queue behavior, desk discretion, and the authentication requirement.

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 three-parameter tool with no output schema, the description provides enough context to call it correctly: purpose, queue destination, desk discretion, and auth. It could mention the response or lack of confirmation, but that is not essential for making the call.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the reader-key requirement but adds little beyond the schema's own field documentation for tip and chain.

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 ('Tip the desk') and names the resource ('a development on an existing chain or a story worth auditing'). It also situates the tool in the proposed-developments queue, distinguishing it from sibling write tools like submit_letter and report_error.

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 first clause implies when to use it — when a story has moved or is worth auditing — and the queue explanation clarifies what happens after the call. It does not explicitly exclude alternatives or name sibling tools, so it stops 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?

No annotations are provided, so the description carries the full burden. It discloses the outcome of verified reports (fixed and logged on public corrections ledger), the attribution ('Caught by a reader'), and the auth requirement. This goes beyond the schema and gives the agent a realistic model of the tool's behavior.

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

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

Two sentences, zero filler, front-loaded with the action and target. Every clause earns its place: purpose, examples, outcome, and auth requirement.

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 3-parameter report tool, the description covers the essential behavior and outcome. It omits what the tool returns on submission, but with no output schema and low complexity, that is a minor gap. An agent can safely invoke it with the described context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it reinforces that the key is required and gives examples of what a description should contain, but it doesn't meaningfully augment the parameter docs.

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 ('Report') and resource ('a suspected error in a published piece'), with concrete examples of what counts as an error. It is clearly distinct from sibling read/list tools and other submission tools like submit_letter or propose_development.

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 makes clear when to use the tool (for suspected errors in published pieces) and states a prerequisite ('Requires the reader key'). It doesn't explicitly name alternatives or exclusion cases, but the purpose is specific enough that an agent can route to it 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?

With no annotations provided, the description carries the burden and discloses that the operation is a read-only search, specifies the exact return fields (slug, title, URL, highlighted snippet), and notes ordering (best matches first). It also scopes the search to published pieces and lists which parts of the content are searched. It does not mention rate limits or error behavior, but for a simple search tool this is substantial.

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

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

The description is two sentences with no wasted words. It front-loads the purpose, then provides return details and a workflow pointer. It avoids repeating schema descriptions, making every clause valuable.

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 search tool with no output schema, the description covers search scope, return fields, ordering, and the follow-up action. The schema handles search term semantics and limits. Minor gaps like behavior on zero results are non-essential, so the description is effectively complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents both 'query' and 'limit'. The description adds useful context about what corpus is searched, but it does not add parameter-level semantics beyond the schema, so the baseline 3 applies.

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

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

The description uses the specific verb 'search' over a clearly defined resource ('every published piece') and enumerates the exact fields searched. It also distinguishes itself from sibling get_audit by noting that the slug should be used for full detail, so an agent can tell which tool does which job.

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 explicit workflow guidance: after searching, use the returned slug with get_audit for full detail. It provides clear context for when search_corpus applies (full-text search for published pieces) though it does not explicitly enumerate when not to use it or name alternative search tools.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does well by explicitly stating that publication is never direct, is subject to the desk's normal editorial process, and may be excerpted and initialed. This meaningfully informs an agent's expectations about side effects, though it does not mention any immediate return or confirmation 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?

The description is two sentences with no filler. The primary action is front-loaded, and the second sentence adds necessary editorial-process context that prevents the agent from assuming direct publication.

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 three-parameter submit tool with no output schema and no annotations, the description covers the core behavior, the reader-key requirement, and the non-obvious publication pipeline. It is slightly light on what happens immediately after submission, but it is otherwise sufficient to call the 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 description coverage is 100%, so the schema already documents key, from, and text. The description adds only that the reader key is required, which restates a schema requirement rather than adding new parameter semantics. 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 uses a specific verb and resource: 'Submit a letter to the desk.' It also clarifies the publishing nuances (excerpted, initialed, through editorial process), which distinguishes it clearly from read-only siblings like list_letters and verify_piece.

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 states a prerequisite ('Requires the reader key') and describes the outcome if the desk answers, but it gives no explicit guidance about when to choose this tool over alternatives or when not to use it. No sibling comparisons or exclusion conditions are provided.

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

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

With no annotations, the description carries the full burden and does a good job: it discloses that the hashes are as-of the last corpus sync and that live re-hashing is required, signaling potential staleness. It does not discuss error cases or response format, but the read-only verification nature is clear.

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 compact sentences: the first states what the tool returns and its as-of-sync limitation, and the second explains how to use it for verification. Every sentence earns its place, with no filler or redundancy.

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

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

For a single-parameter tool with no output schema, the description covers the core return value (hashes for JSON and HTML), the staleness caveat, and the required verification workflow. It could optionally mention output structure or missing-slug behavior, but nothing essential is missing.

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

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

The input schema already documents the slug parameter fully with an example, so the description does not need to add much. The phrase 'at the piece's URL' lightly ties the slug to the verification workflow, but the semantic load is primarily handled by the schema, meriting the baseline score.

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 (one piece) and the main purpose: providing SHA-256 hashes so the caller can verify that published artifacts match live content. It is easy to distinguish from audit or chain-related siblings, though it does not explicitly name or contrast any sibling tool.

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

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

The description gives a concrete usage scenario: re-hash the live artifacts at the piece's URL and compare to confirm what was read is what the desk published. It offers clear context for when to use the tool, but it does not mention when not to use it or suggest an alternative sibling.

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