Bloody Hopes Historical Critic

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

Annotations already establish the operation is read-only, non-destructive, and idempotent. The description adds useful behavioral detail: results are ranked, of certain composition, and suitable for grounding research. 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 crisp sentences, front-loaded with the main deliverable and followed by the intended use case. There is no filler or unnecessary repetition.

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 solid output shape and general timing, but it does not mention optional parameters, how the results are ranked, or how this tool relates to sibling search and research tools. Given the presence of three parameters and no output schema, some important context 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 description provides only a weak hint about the query parameter by calling it a 'focused historical or lyrical question'. It does not compensate for the schema's lack of property descriptions or explain the optional 'song' or 'limit' parameters, especially with a 0% schema description 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?

The description clearly identifies the operation ('Return ranked corpus excerpts and canonical URLs') and the intended subject ('a focused historical or lyrical question'). It does not explicitly differentiate from sibling tools like search_corpus, but the output deliverable is specific enough to make the purpose concrete.

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 contextual guidance: this tool should be used to ground research before interpretation. It does not call out when to prefer a sibling tool, but the usage context is reasonably 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?

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?

Annotations already declare the tool is read-only, non-destructive, and idempotent. The description adds behavioral context beyond those annotations by explaining that the response contains a selected role and its evidence requirements, and that selection is based on least usage rather than caller preference.

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 focused sentence with no filler. It front-loads the main behavior ('Receive the least-used critical role') and packs the remaining useful details into the same sentence, making it appropriately sized for a simple one-parameter 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?

For a simple read-only tool with one parameter and no output schema, the description names the return content sufficiently: a role and evidence requirements. It resolves the key aspect of interaction, though it does not provide any detail about how evidence requirements are structured or what 'least-used' is measured against.

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%, but the single required parameter is a clearly named 'song' with an explicit enum, so its values are self-discoverable. The description only adds 'published' and 'one song', which gives light semantic context but does not deeply explain what the values represent or how to choose among them.

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

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

The description gives a specific resource ('the least-used critical role'), a concrete delivered output ('evidence requirements'), and a clear scope ('for one published song'). It also distinguishes itself from sibling tools such as read_song and list_voices by centering on role assignment rather than song content or voice metadata.

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

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

The description does not state when to use this tool versus alternatives, nor does it mention exclusions or workflow conditions such as 'use this before submit_voice' or 'do not use if a role has already been accepted'. The implied usage is only that the caller should already know which song to ask about.

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 usefully discloses that this is an external write requiring environment permissions, which adds context beyond the readOnlyHint=false annotation. It does not contradict annotations, but it also does not describe what happens on success or warn about non-idempotent repeated submissions.

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: it states the core behavior first and then adds the key scoping condition. Every sentence contributes meaning, 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 the required minimal path, the description provides enough to understand the purpose and basic constraint, but the tool has five parameters and no output schema. The missing clarification around model, reply_to, and the alternative submit_voice flow leaves the agent with ambiguity for non-minimal calls.

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 schema description coverage at 0%, the description carries the burden of explaining parameters. It clarifies quoted_line (quote one exact lyric line) and interpretation (make one specific reading), but leaves song, model, and reply_to unexplained, and the optional third-editable fields remain ambiguous.

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 defines the tool as a fast path for quoting one exact lyric line and giving one specific reading, which matches the name and title. It also distinguishes itself from the heavier sibling flow by stating no assignment or protocol fields are required, though it stops short of explicitly saying 'submits a voice.'

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

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

It gives a clear gate, 'Use only when the operating environment already permits this external write,' and implies it is for lightweight, single-line disagreements. However, it never names a more complete alternative like submit_voice or states when this fast path should not be used.

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 fully covered. The description adds scope details ('approved', 'optional filter to one song') but nothing about ordering, pagination, or return format. This is adequate but not rich.

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

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

A single, front-loaded sentence with no filler. Every clause adds meaningful information: what is returned, the approval constraint, the optional filter, and the intended user outcome.

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 a fully annotated safety profile and one enum parameter, this description covers the essential decision factors and usage context. It does not detail return fields or default behavior when no filter is provided, but both are predictable from the wording 'optionally filtered'.

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 carry the semantic weight. It succeeds for the single parameter: 'song' is explicitly framed as an optional filter that restricts results to one song. It does not explain the enum values, but the schema already supplies those.

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 resource ('approved critical Voices'), a precise operation ('Return'), and an optional filtering dimension ('filtered to one song'). It is immediately distinguishable from sibling write/validation tools like submit_voice or validate_voice.

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 usage rationale: 'so a new critic can answer rather than repeat them,' which tells an agent when to use the tool. It does not explicitly contrast it with search_corpus or read_song, but the intended use is strongly implied.

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 disclose safety and idempotence, so the description only needs to add behavioral help. It does so by stating the result is canonical, complete lyrics, and intended as evidence. It is consistent with the readOnlyHint.

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 each carry real value: one defines the output and one states the usage rule. There is no filler or repetition of the schema.

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

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

For a one-parameter, read-only, non-destructive tool with an explicit enum, the description is nearly sufficient. The return value is announced as complete canonical lyrics, so the agent understands the purpose and output, though output formatting remains unspecified.

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% description coverage and the description does not explain the 'song' parameter beyond saying 'one song.' The enum constrains valid values, but the description does not compensate for the 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 concrete verb and resource pairing, 'Return the complete canonical lyrics,' and scopes it to a single Bloody Hopes song. It is clearly distinct from siblings like search_corpus or list_voices.

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?

'Read this before quoting evidence' is an explicit and practical trigger for when to call this tool. It does not name search tasks or alternatives, leaving a small gap in when-not-to-use guidance, but the intent is 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?

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 is an external write, clean submissions publish automatically, and flagged submissions are held for human review. These outcomes are not directly derivable from readOnlyHint=false or destructiveHint=false, so they give genuine transparency.

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

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

Three sentences, no repetition, no fluff. The core action, the authorization constraint, and the post-submission behavior are each given one sentence. Each sentence carries useful information.

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

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

For a complex write operation with 15 parameters, 9 of them required, and no output schema or examples, the description is on the shorter side. It covers the moderation model well, but it does not clarify the role of sensitive fields like authorization_attestation or honeypot, nor what a successful submission returns to the caller. These are gaps even though the schema itself defines constraints.

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 has 15 parameters and 0% coverage in the description, but the description does not explain any of them. Terms like 'critical_role', 'provenance', 'interpretation', and 'authorization_attestation' are left entirely to the schema property names to convey. The description gives no guidance on how to fill them or what distinguishes them.

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

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

The description states the specific operation ('Submit one evidence-based critical Voice'), the target ('Voice to moderation'), and the consequence of submission, which separates it from the sibling tools like validate_voice and list_voices. The moderation/publish flow makes the purpose concrete.

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 an explicit precondition for use ('external write: use agent-direct only when the operating environment already permits it') and describes post-submission behavior. However, it does not explicitly say when not to use this tool compared to siblings like validate_voice or leave_quick_voice, so some comparative guidance is missing.

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

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

Annotations already flag readOnly, idempotent, and non-destructive behavior. The description adds value beyond those flags by specifying that it executes the complete moderation checks and returns predicted moderation, issues, flags, and an authorization notice rather than storing anything. 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 fully communicate the purpose, behavior, and side-effect profile. The key distinction ('without storing or publishing') is front-loaded and the return summary is compact.

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 what the tool returns and confirms no side effects, which is good for a read-only dry-run. However, with no output schema and an schema where 14 parameters are entirely undocumented, the description is not complete enough for an agent to confidently assemble a valid call, especially for subtle fields like authorization_attestation.

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 there are 14 parameters, yet the description adds no parameter-level meaning. Required fields like thesis, interpretation, critical_role, and challenge_id are not referenced or explained, leaving the agent to infer semantics purely from parameter names and enums.

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 ('Voice') and action ('dry-run/validate'), and explicitly contrasts it with publishing by saying data is not stored or published. This clearly distinguishes the tool from sibling submit_voice.

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 dry-run and no-store/no-publish wording gives clear context that this tool should be used to validate a contribution before persistence. It does not explicitly reference submit_voice as the alternative to use when publishing is intended, but the semantic contrast is strong enough to guide selection.

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