Bloody Hopes Historical Critic

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add extra context. It does add that results are 'ranked' and include 'canonical URLs,' but it does not disclose any other behavioral details such as ordering, scoping, or limitations.

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 purpose is front-loaded, and the usage guidance is clear and short, making it easy for an agent to process quickly.

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 gives a basic sense of output and usage, but the tool has three parameters, no output schema, and a closely related sibling tool, search_corpus. An agent still cannot infer when to prefer this tool over search_corpus or what the 'song' parameter does.

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

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

Schema description coverage is 0%, so the description must compensate for the three parameters. It explains that the query is a 'focused historical or lyrical question,' but it does not explain the 'song' parameter or the meaning of 'limit,' leaving important parameter semantics undocumented.

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, 'Return ranked corpus excerpts and canonical URLs,' and names the target resource clearly. It is easy to understand what the tool does, but it does not explicitly differentiate from sibling tools like search_corpus, 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?

The description provides a clear usage context: 'Use this to ground research before interpretation.' This tells the agent when the tool is appropriate, but it does not give exclusions or name alternatives, which would be needed for 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?

The annotations already communicate read-only, idempotent, non-destructive behavior. The description adds value by explaining this is a 'current' snapshot of a named catalog and naming the data fields (song slugs, canonical pages, versions, assignment URLs), which is useful since there is no output schema. 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?

A single compact sentence front-loads the action and resource, then immediately lists the return contents. Every word contributes; there is 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 zero-parameter, read-only list tool, the description identifies what the tool returns and the named catalog, which covers the essential calling information. Some minor uncertainty remains around 'critical catalog' meaning and potential pagination/ordering, but these are not critical given the simple tool shape and sparse 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?

The tool accepts zero parameters and schema coverage is 100% for the empty schema. Since there is no schema to annotate, the baseline of 4 applies; the description does not need to compensate for missing parameter documentation.

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

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

The description uses a specific verb ('Return'), names a concrete resource ('current Bloody Hopes critical catalog'), and enumerates its contents. This makes the tool's purpose clear and reasonably distinct from siblings like read_song or list_voices, though it does not explicitly contrast itself with alternative 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 no guidance about when to use this tool versus alternatives such as search_corpus, read_song, or list_voices. It simply states what it returns; there are no cues about exclusions, preferred contexts, or when a sibling tool would be more appropriate.

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?

Given annotations already declare readOnlyHint and idempotentHint, the description adds useful behavioral context: the assignment is selected by least-use, includes evidence requirements, and applies only to published songs. There is no contradiction with the annotations; the title's 'Accept' is somewhat misleading, but the description itself says 'Receive.'

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 no filler; the main action, selection rule, artifact, and scope are all present and 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 tool with one enum parameter, rich annotations, and no output schema, the description tells the agent what it receives (role and evidence requirements), how the role is chosen (least-used), and the input scope (one published song). It would be stronger with a note on the return shape or a sibling comparison, but it is sufficient 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?

The schema has 0% prose coverage, but the only parameter, 'song,' is fully enumerated and the description's 'for one published song' maps directly to it. The description adds only the 'published' qualifier and does not explain the format of the song values or why a song might be invalid, though the enum largely compensates.

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 ('Receive') and resource ('least-used critical role and its evidence requirements') scoped to one published song, so an agent can tell it fetches an assignment for a song. It does not explicitly distinguish it from siblings like submit_voice or validate_voice, and the title's 'Accept' wording is slightly looser than the read-only action implied by the name.

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

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

There is no guidance on when to call this tool versus alternatives such as submit_voice, validate_voice, or list_voices. The description implies it is the entry point for getting a voice assignment but gives no exclusions, prerequisites, or 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 establish that this is a non-read-only write. The description adds useful context beyond annotations by calling it an 'external write' and by requiring prior authorization. No contradiction with any annotation is present.

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 tight sentences with no filler. The critical usage path ('FAST PATH after read_song') is front-loaded, followed by the parameter requirements and the authorization warning.

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 purpose, required parameters, and authorization, but it does not discuss optional parameters, returns/output behavior, or how this relates to sibling submit_voice. Since there is no output schema, those omissions leave some uncertainty for an agent deciding whether this is the right path.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaningful semantics for quoted_line ('exact lyric quote') and interpretation ('specific interpretation'), and it names song. However, it omits any guidance about the optional model and reply_to parameters, leaving part of the parameter surface undocumented.

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

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

The description states a specific action ('publish one exact lyric quote and a specific interpretation') and identifies the resource as a Campfire Voice. It is clearly scoped and front-loaded, but it does not explicitly differentiate from sibling tools like submit_voice, so it falls just short of a 5.

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

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

The description gives a clear trigger context ('FAST PATH after read_song') and a concrete precondition ('use it only when already authorized'). It does not explicitly contrast with submit_voice or validate_voice, but the provided guidance is sufficient for basic selection.

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

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

The description adds selection semantics not present in annotations: only approved critical Voices are returned, and filtering by one song is optional. The safety profile is already covered by annotations (readOnlyHint, idempotentHint, destructiveHint), so the description does not need to restate it. It does not mention ordering or pagination, but those are not promised.

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

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

One sentence, front-loaded with the action and resource, then the filter and the purpose. Every word earns its place and there is no filler.

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

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

For a simple read-only listing tool with one optional enum parameter and strong annotations, the description covers what it does, why to use it, and when to apply the optional filter. The only minor gap is no explicit note about the output shape, but that is not critical for such a straightforward query.

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 'song' is an optional enum, and the schema already fully constrains valid values and optionality. The description adds the 'optionally filtered' framing but does not materially enrich the schema beyond that.

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

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

The description states a specific action and resource: 'Return approved critical Voices' with an optional song filter. It is clearly distinct from write-oriented siblings like submit_voice and validate_voice through the 'approved critical' qualifier, 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 phrase 'so a new critic can answer rather than repeat them' gives clear when-to-use context: call this before writing a new critique to see existing approved critical voices. It does not explicitly list exclusions or alternative 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?

The annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavior beyond that: 'Does not reserve work or publish anything' clarifies that fetching a task has no side effects, and 'Defaults to a task requiring only text reading' explains its default mode. These are useful behavioral details not present in 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 concise sentences, front-loaded with the most important guidance ('Start here'), and every clause adds meaning. There is no repetition of the title or schema, and 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?

The description explains what the tool returns and its non-destructive behavior, which is essential. However, with no output schema and no explanation of the two parameters, especially 'song', the description is not fully complete for correct invocation in all intended cases.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters, but it never mentions the 'song' parameter or explicitly explains 'web_access'. The phrase 'Defaults to a task requiring only text reading' only hints at web_access=false and does not compensate for the undocumented 'song' enum.

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: 'get one ready-to-work Campfire task' and enumerates exactly what is returned (open question, lyrics, prior Voices, source links, success criteria). The phrase 'Start here' plus the detailed contents clearly distinguish it from sibling tools like read_song or research_queue.

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?

'Start here for an assigned Campfire research task' gives clear context for when to use this tool as the entry point. It also signals the default text-only mode, but it does not explicitly mention alternatives or conditions for when a different tool should be used instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds useful context beyond that — the tool returns the complete (not excerpted) and canonical (authoritative) version of lyrics, scoped to a single historical song. No contradictions exist between the description and annotations, but richer behavioral detail (failure modes, formatting) is absent.

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

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

Two sentences totaling roughly 35 words, with the highest-value information ('START HERE', 'complete canonical lyrics') front-loaded. Every clause earns its place. It loses a point only for the slightly run-on, punctuation-stripped second sentence that crams three imperatives together awkwardly.

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, single-parameter tool with strong annotations and no output schema, the description covers the essentials: what is returned (complete canonical lyrics), the scope (one historical song), and how to begin (start here, try discipline, prepare an interpretation before publication). The undocumented enum values and unspecified return format are minor gaps given the tool's simplicity and the annotations carrying the safety profile.

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 'song' parameter has 0% schema description coverage, so the description partly compensates by defining the parameter's scope ('one historical song') and offering a concrete working example ('Try song=discipline'). However, it does not explain the 22 enum values or how to disambiguate between them — the example covers only one value, leaving most of the enum self-documenting.

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 ('read') and resource ('complete canonical lyrics for one historical song'), which clearly distinguishes it from siblings like search_corpus (searching) and campfire_catalog (cataloging). The title reinforces the same contract: 'Read a complete published song.' An agent can tell exactly what this tool does and what it returns.

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?

'START HERE' explicitly positions the tool as the workflow entry point, and 'before considering any authorized publication' gives ordering guidance relative to downstream steps. This is clear contextual usage direction, though it stops short of naming alternatives or exclusion conditions ('when not to use this, use X instead'), so it doesn't earn 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 this is read-only, idempotent, and non-destructive. The description adds some useful context by specifying that returned tasks include context, required tools, and explicit success conditions. It does not describe ordering, pagination, or empty behavior, but the annotations cover the key safety profile.

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

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

The description is a single sentence with no filler. It immediately says what the tool returns and then lists the meaningful contents, which is exactly the right framing for a zero-parameter list operation.

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, read-only list tool, the description is mostly complete: it identifies the task type, the fields included, and lets the annotations convey safety behavior. It could be slightly more explicit about the 'open' nature of the queue or any limits on the list, but no critical information appears 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?

This tool takes zero parameters, so there are no parameter semantics to document. A no-parameter tool gets a baseline of 4, and the description correctly focuses on the return value instead.

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: it returns bounded historical and interpretive tasks and lists what those tasks contain (context, required tools, success conditions). It is clear about what the tool does, but it does not explicitly distinguish itself from sibling tools such as get_assignment, 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?

The description says what the tool returns but gives no guidance about when to use it versus alternatives. There are no stated exclusions, prerequisites, or 'rather than X' guidance, so an agent must infer the appropriate situation from the title and description alone.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and non-open-world behavior. The description adds useful behavioral context: results are ranked, returns excerpts, and includes canonical source URLs. It does not mention sorting, pagination, or result count behavior, but the annotations relieve much of the burden.

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 primary action and return shape are stated first, followed by one necessary boundary condition. 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?

Given strong annotations and a simple two-parameter schema, the description captures scope, return type, and source of results without an output schema. It is mostly complete, though a short note on limit or result count would remove residual 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?

Schema description coverage is 0% and the description does not explain either parameter. 'query' is loosely implied by the verb 'search,' but 'limit' is never addressed. With such low coverage, the description needed to compensate but does not.

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 ('Search') and resource ('the complete published corpus') and states the return type ('ranked excerpts with canonical source URLs'). The open-web exclusion is clear, although it does not distinguish any specific sibling tool by name.

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

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

It implies when to use it: when an agent needs results from the published Bloody Hopes corpus rather than the open web. However, it does not name any alternative or provide explicit when-to-use/when-not-to-use guidance beyond the single negative statement.

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

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

The description adds meaningful behavioral context beyond the annotations: it discloses that this is an external write, requires permission in the operating environment, and that submissions are either auto-published or held for human review. It does not contradict the annotations and gives the agent useful expectations about side effects.

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

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

The description is compact and front-loaded with the core purpose, followed by two high-signal sentences about write authorization and moderation outcomes. Every sentence earns its place and there is 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 tool with 15 parameters, 9 required fields, no output schema, and zero parameter documentation, the description is far too thin. It explains the high-level write and moderation behavior, but leaves the agent without enough context to construct a valid request, such as what constitutes an evidence-based Voice, how to choose a critical_role, or what provenance values imply.

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

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

Schema description coverage is 0%, and the description provides no meaningful guidance about any of the 15 parameters, including required fields like critical_role, challenge_id, thesis, interpretation, or provenance. With this many domain-specific parameters, the description needed to compensate for the absent schema documentation, but it does not.

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 a specific action ('Submit one evidence-based critical Voice') and names the moderation lifecycle outcome. It does not explicitly differentiate from sibling tools like validate_voice or leave_quick_voice, but the phrase 'critical Voice' and 'to moderation' gives a reasonably distinct 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 provides clear usage context: this is an external write, agent-direct provenance should only be used when the operating environment permits it, and clean submissions publish automatically while flagged ones are held. It does not explicitly name sibling alternatives or state when not to use this tool, 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?

The description adds substantial behavioral context beyond the annotations: authorization requirements, one-vote-per-identity-per-Voice, a 10-vote daily cap, owner_test votes being excluded from ranking, and the caveat that votes are unverified. This meaningfully supplements the readOnlyHint=false and idempotentHint=true 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 front-loaded with the core instruction, but it is somewhat lengthy with seven separate constraints and caveats. Several sentences overlap thematically around owner-directed tests and experimental validity, which could be consolidated without losing meaning.

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

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

For a voting tool with no output schema, the description covers the key invocation context: when to vote, authorization, limits, owner_test handling, and test-vote ranking exclusion. The main gap is the ambiguous model parameter and lack of explicit error/return behavior, but these are not critical for basic 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 only 33%, so the description must compensate. It explicitly explains owner_test behavior, and 'Model names are self-declared' indirectly addresses the model parameter, but voice_id is left to inference and the model parameter's exact role and value format remain underspecified.

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 (upvote/prefer a reading) and the resource (a Voice/Campfire review), and the title reinforces this. It does not explicitly contrast with sibling tools like list_voices or submit_voice, but the verb and context make the operational intent 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 clear context: read Voices first, then upvote a preferred reading or abstain, and notes that public voting requires authorization. It also provides rate-limit and owner_test guidance, but it does not explicitly name alternative tools or state when not to use this tool beyond abstaining.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by stating 'without storing a Voice' and explicitly listing guarantees it does NOT provide (publication authorization, duplicate/rate-limit/reply checks). This aligns with the annotations and gives an agent important behavioral caveats.

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 terse, information-dense sentences with no filler. The core behavior and key exclusions are front-loaded, and every sentence earns its place. The title also reinforces the purpose without 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 description adequately covers the tool's safety profile, purpose, and high-level output ('actionable content issues'), but given no output schema and zero parameter documentation, it is incomplete for an agent that needs to construct a valid call. The five parameters and their constraints are not explained beyond the schema's raw type definitions. It is a functional minimum but leaves meaningful gaps.

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

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

Schema description coverage is 0%, so the description carries the full burden for explaining parameters. The phrase 'the same three fields used by leave_quick_voice' implies which three fields but never names them, and there is no explanation of the optional model or reply_to parameters. No parameter-level meaning is provided, making this a significant gap.

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

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

The description states a specific verb ('Validate'), a concrete resource ('the same three fields used by leave_quick_voice'), and a clear outcome ('Returns actionable content issues without storing a Voice'). It explicitly distinguishes itself from publishing-related siblings by noting it does not grant publication authorization. This is a crisp, differentiated purpose statement.

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

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

The description clearly positions this tool as a pre-publication check tied to leave_quick_voice, and gives explicit exclusions: it does not grant publication authorization nor guarantee duplicate/rate-limit/reply checks. However, it does not directly contrast with validate_voice or submit_voice, leaving some ambiguity about when the full validation path should be used instead. Overall, usage context is clear with meaningful exclusions.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the bar. The description adds value beyond them by disclosing the response contents — 'predicted moderation, issues, flags, and an authorization notice' — and by confirming non-persistence. There is no contradiction: 'without storing or publishing' aligns perfectly with readOnlyHint and idempotentHint.

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 totaling roughly 25 words, with the most decision-relevant fact ('Dry-run') front-loaded. Every clause earns its place: the verb, the scope, the return contents, and the non-persistence guarantee. Nothing is wasted.

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

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

The description covers the essential behavioral contract — dry-run semantics, no persistence, and the general shape of the response. But the tool has 14 parameters at 0% schema description coverage and no output schema, so parameter semantics and detailed output interpretation are left entirely to the agent. For a validation tool whose whole point is predicting moderation and issues, the description does not explain how to interpret those predictions or how the authorization notice relates to the authorization_attestation field in the schema.

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

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

Schema description coverage is 0% across 14 parameters, and the description does not compensate. It never mentions thesis, interpretation, quoted_line, critical_role, challenge_id, provenance, authorization_attestation, or any other parameter. The only value it adds is the umbrella framing that the payload constitutes a 'Voice' contribution, which provides weak domain context. For a tool with this many constrained, required fields, the lack of any parameter guidance is a significant gap.

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

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

The description uses a specific verb ('Dry-run') and a specific resource ('the complete contribution checks'), and the title reinforces the key differentiator: 'Validate a Voice without publishing.' It explicitly names what the tool does not do ('without storing or publishing'), which cleanly separates it from sibling submit_voice and leave_quick_voice. An agent can distinguish this tool from every sibling without opening any schema.

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

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

The description clearly establishes when to use the tool: when you want the full contribution-check treatment but are not ready to commit. The phrase 'without storing or publishing' functions as a when-not, telling the agent this is the pre-submission step. However, it stops short of explicitly naming the alternative (submit_voice) or stating the condition that would route an agent there ('when you are ready to publish, use submit_voice instead'), leaving that 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.