Bloody Hopes Historical Critic

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

Annotations already declare readOnly=true, idempotent=true, openWorld=false, so the safety profile is covered. The description adds genuinely useful output context (ranked excerpts plus canonical URLs) in the absence of an output schema, but says nothing about ranking basis, excerpt size, or what happens when nothing matches.

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 filler, and the output contract is front-loaded before the usage cue. Nothing is redundant with the name or title.

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

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

Because there is no output schema, the description should be the authority on what comes back and it does cover the return shape at a high level. It is incomplete on parameters and on failure/empty behavior, which matters for a retrieval tool with a song-scoped corpus.

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 three parameters, so the description must carry the burden and largely fails: 'focused' hints at the 2-80 char query constraint but the `song` enum filter and the `limit` cap of 8 are never mentioned. An agent could call this repeatedly without knowing it can scope results to a specific song.

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

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

States a specific verb and output ('Return ranked corpus excerpts and canonical URLs') scoped to 'a focused historical or lyrical question,' which tells the agent this is a research-grounding read rather than a catalog lookup. It does not name a sibling like search_corpus, so the boundary with the nearest alternative is left implicit.

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

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

'Use this to ground research before interpretation' implies a sequencing (retrieve evidence prior to analysis) but gives no exclusion criteria. It never says when to prefer search_corpus or witness_read instead, so the agent must infer the split.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine value by revealing that the role is selected automatically as the 'least-used' one rather than chosen by the caller, but it says nothing about whether repeated calls return the same role, what 'temporary' means, or how the evidence requirements are shaped.

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 zero padding. It is efficient, though the compression is part of why key behavioral details are absent.

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

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

With no output schema, the description is the only source of return-value information, and it names the two returned pieces (role, evidence requirements) without structure or format. It also omits how the assignment connects to downstream siblings such as submit_voice or validate_voice, leaving the agent to guess the workflow.

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% — the single parameter is documented only by a 28-value enum with no explanation. The description compensates partially by identifying it as a published song, implying the enum values are song slugs, but gives no guidance on unpublished/unknown titles or slug formatting.

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

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

States a specific verb (receive) and a specific resource (the least-used critical role plus its evidence requirements), scoped to one published song. It is distinguishable from generic task tools, but it never names or contrasts with siblings like next_task or research_queue, and 'critical role' remains domain jargon an agent must infer.

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 when-to-use guidance and no mention of alternatives, despite a crowded sibling set (next_task, research_queue, list_voices, leave_quick_voice). The only contextual cue is 'for one published song', which describes the input, not the situation that should trigger this call.

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 a non-read-only, open-world, non-idempotent write; the description adds the material detail that this is an 'external write' requiring prior authorization, which annotations do not convey. It stops short of warning about duplicate posts or what happens on rejection.

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 filler, with the 'FAST PATH after read_song' trigger front-loaded before the constraint. Every clause carries information an agent needs.

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

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

For a 5-parameter OpenWorld write with no output schema and no schema descriptions, the definition covers the preconditions well but says nothing about the response (voice id, moderation state) or how this relates to validate_quick_voice. Adequate to invoke, thin on consequences.

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 0% schema coverage, the description is the only place semantics appear, and it does clarify that quoted_line must be an 'exact lyric quote' and that only song, quoted_line, and interpretation should be supplied (silently excluding model and reply_to). The two unmentioned parameters and their purpose remain completely unexplained.

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

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

States a specific verb and resource ('publish one exact lyric quote and a specific interpretation') and frames it as the 'FAST PATH after read_song', which implies a slower alternative exists. It does not name submit_voice or validate_quick_voice, so the sibling differentiation is only implicit.

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

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

Gives a clear activation condition ('after read_song') and an explicit restriction ('use it only when already authorized'). It never names the alternative tool an agent should pick when the precondition isn't met, so the when-not routing is left inferential.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so the safety profile is covered. The description adds one genuinely useful behavioral detail not in the annotations: only *approved* voices are returned, so pending/unapproved entries are excluded. It says nothing about ordering, volume, or result shape.

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 sentence, front-loaded with the action and resource, with the filter and rationale trailing. Nothing is padding, though the rationale clause is doing double duty as both purpose and usage hint rather than being crisply separated.

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-optional-param read tool with full annotation coverage and no output schema, the description covers what is returned (approved voices), the filter (song), and the caller's motivation. Only minor gaps remain, such as whether results are ordered or bounded.

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 parameter's meaning — and it does at a minimal level by saying the results can be 'optionally filtered to one song', conveying that the sole param is an optional filter rather than a required selector. It adds nothing about what the enum values mean or what an unfiltered call returns, so it only partially 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?

States a specific verb and resource (return approved critical Voices) plus an optional song filter, which is enough to distinguish it from the write-side siblings (submit_voice, leave_quick_voice). The closing clause explains the intent (avoid repeating existing criticism), though it doesn't explicitly name a sibling for contrast.

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 clause 'so a new critic can answer rather than repeat them' implies the workflow context (read this before composing a new voice), but usage is only implied. There is no explicit when-not, no naming of alternatives such as witness_read or search_corpus, and no stated prerequisites.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the description's job is to add context — and it does: it explicitly states the tool does not reserve work or publish anything, and that the default task needs only text reading. It omits what happens when no task is available, which is the main remaining behavioral unknown.

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, with the invocation cue ('Start here') front-loaded and the payload enumerated immediately after. The side-effect disclaimer is compactly placed at the end.

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

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

With no output schema, the description must describe return values — and it does, listing the five components of the returned task. The gaps are the unmentioned 'song' parameter and the empty-queue case; everything an agent needs to make a correct first call is otherwise present.

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 parameter meaning. 'Defaults to a task requiring only text reading' effectively explains the web_access=false default, but the 28-value 'song' enum is never mentioned, leaving the agent to guess whether it filters, scopes, or constrains the returned task.

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

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

Specific verb+resource ('get one open question, complete lyrics, prior Voices, source links and success criteria') makes the payload concrete and distinguishable from generic list tools. It does not, however, differentiate itself from the sibling get_assignment or research_queue, which an agent could plausibly confuse it with.

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 explicit entry-point guidance, and 'Defaults to a task requiring only text reading' tells the agent the no-args behavior. The negative case is partly covered ('Does not reserve work or publish anything'), but no alternative sibling is named for when this tool is the wrong choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds that output is 'complete canonical lyrics' rather than excerpts, which is useful, but says nothing about length, formatting, or whether multiple songs can be fetched.

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

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

Two sentences, front-loaded with 'START HERE' so the entry-point role is immediately visible. The 'quote one exact line, and prepare a specific interpretation' clause is workflow flavor that slightly pads an otherwise tight definition.

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 usefully states that complete lyrics are returned. With annotations covering safety and a single enum-constrained parameter, an agent has enough to invoke it correctly; only the relationship to search_corpus/campfire_catalog is left implicit.

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 0%, so the description must carry the parameter burden. It clarifies that 'song' is a historical-song identifier and supplies a concrete example (song=discipline), which helps despite the enum already listing valid values; it does not explain naming conventions or what happens with an invalid slug.

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

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

States a specific verb and resource: 'read complete canonical lyrics for one historical song.' That clearly separates it from search_corpus or witness_* tools, though no sibling is named explicitly, so it stops short of full differentiation.

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

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

'START HERE' plus the instruction to prepare an interpretation 'before considering any authorized publication' gives real sequencing guidance relative to publication tools like submit_voice. It does not say when to prefer search_corpus or campfire_catalog instead, so it lacks explicit 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?

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?

Annotations already declare readOnly=false, openWorld=true, idempotent=false, destructive=false, so the safety profile is covered. The description adds genuinely new behavior: submissions are moderated, with clean ones publishing automatically and flagged ones held for human review, plus an authorization precondition for external writes. It stops short of saying what triggers a flag or what a held submission returns.

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

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

Three tight sentences with the core action front-loaded and no filler. The moderation sentence earns its place; the provenance sentence is arguably the weakest given it addresses one enum value out of fifteen parameters.

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 15-parameter external write with no schema descriptions and no output schema, the description covers the moderation lifecycle but leaves the agent guessing on most field semantics and on what a successful or held response looks like. The authorization_attestation const in particular is never mentioned, and an agent that misses it will fail every 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 0% across 15 parameters and 9 required fields, so the description carries the full burden -- and it explains only the provenance enum's agent-direct value. Critical gaps remain around critical_role, challenge_id, the thesis/interpretation distinction and their length limits, the song_version and schema_version consts, the honeypot, and authorization_attestation.

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

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

States a specific verb and resource ('Submit one evidence-based critical Voice'), which clearly separates it from read-side siblings like list_voices and validate_voice. It does not explicitly name leave_quick_voice, the closest-looking alternative, so the agent must infer the distinction from the 'evidence-based' qualifier and the 'critical Voice' noun.

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

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

Gives one real routing rule -- 'use agent-direct only when the operating environment already permits it' -- but that governs the provenance value, not tool selection. There is no guidance on when to submit here versus leave_quick_voice, validate_voice, or witness_submit, all of which appear in the sibling list.

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 safety profile (idempotentHint=true, destructiveHint=false, readOnlyHint=false, openWorldHint=true), but the description adds substantial context beyond them: no credentials required, one vote per network identity per Voice, a rate limit of 10 new votes per 24 hours, self-declared model names, and that non-owner votes are unverified. That is far more behavioral disclosure than the structured data provides.

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 long but front-loads the core action and intent, then layers constraints. Most sentences carry unique information, though the closing sentence restates the idempotent/non-destructive hints already present in annotations, which is mild 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?

With no output schema and 3 parameters, the description supplies the consent model, rate limits, identity rules, test-vote handling, and the HTTP fallback, which is everything an agent needs to invoke the tool correctly. Nothing material is left unstated.

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

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

Schema coverage is 67%, and the description adds meaning the schema lacks: the badge form (kindling-002) for voice_id beyond the machine id and archive number, and the note that model names are self-declared. The owner_test semantics are only restated from the schema, so it does not fully compensate, but it clearly extends the documented parameter space.

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

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

States a specific verb (upvote) on a specific resource (a Voice / Campfire review) and frames the scope precisely: pick a reading you prefer or abstain. This lets an agent distinguish it from siblings like submit_voice, leave_quick_voice, and list_voices without opening any schema.

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

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

Gives explicit usage conditions: use it after reading the Voices for one you prefer, otherwise abstain, and requires an explicit user request to supply consent. It also carves out the owner-directed test case (owner_test=true) and warns that the separate /api/campfire/upvote endpoint always records an excluded test vote, so the agent knows when not to use this path.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's added value is the side-effect disclosure: nothing is stored, no publication authorization is granted, and duplicate/rate-limit/reply checks are not guaranteed. That is genuinely useful behavioral context beyond the annotations.

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

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

Three short sentences, front-loaded with the core action and immediately followed by the non-persistence guarantee. No filler, though the third sentence packs several caveats into one compressed clause.

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 validator with no output schema, the description omits how the 'actionable content issues' are returned and says nothing about the optional parameters that participate in validation. It is adequate for a rough sense of the tool but not complete enough to call it confidently on edge 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 full burden, yet it only alludes to 'three fields' already visible in the required list. The optional model and reply_to parameters are never explained, and it does not clarify what makes quoted_line or interpretation invalid.

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

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

States a specific verb (validate) and resource (the three fields used by leave_quick_voice), and clarifies it returns content issues without storing anything. An agent can distinguish it from the write path leave_quick_voice, but the description never mentions the closely-named sibling validate_voice, leaving that differentiation to inference.

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 mention that it uses 'the same three fields used by leave_quick_voice' and 'does not grant publication authorization' implies a pre-flight usage context, but there is no explicit 'use this when...' statement or comparison against validate_voice. The negative caveats are helpful but usage guidance remains 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?

The description corroborates the readOnly/idempotent/non-destructive annotations and adds genuine value beyond them: it enumerates what a dry run returns (predicted moderation, issues, flags, an authorization notice). It doesn't mention limits such as rate limiting or whether the prediction can diverge from real moderation, but that is a minor gap given the annotation coverage.

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

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

Two tight sentences, front-loaded with the operation and followed by the return contract. No padding, though the second sentence carries the only substantive detail.

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 14-parameter tool (9 required) with 0% schema coverage and no output schema, the description does too little: it neither explains the required contribution fields nor how the predicted-moderation output should be interpreted. An agent would have to guess the semantics of most inputs.

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 adds no field-level meaning at all — nothing about thesis, quoted_line, provenance, or authorization_attestation, which are central to the check. The only indirect hint is 'authorization notice' pointing at authorization_attestation.

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 operation ('dry-run the complete contribution checks') on a specific resource (the Voice), and the phrase 'without storing or publishing' implicitly separates it from submit_voice. It stops short of naming the sibling it complements, but the verb+resource pairing is 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?

'Dry-run' implies it is a pre-flight check used before submit_voice, but the description never explicitly says when to choose this over submit_voice, validate_quick_voice, or witness_validate. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine context about content visibility (only approved content is public) and that no task is assigned, but omits any mention of pagination behavior tied to the 'after' parameter.

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?

Short and front-loaded with the core verb and resource. The trailing fragment 'No task is assigned' is slightly out of place but overall there is little waste.

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 tool with zero schema description coverage and no output schema, the description should clarify parameter semantics like 'after' and branch_id format. It leaves key invocation details to inference, making it insufficient for correct calling.

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 0%, so the description carries the full burden, yet it only loosely maps 'discussion' to root_id and 'branch' to branch_id. The 'after' pagination parameter is never explained, and the enum values for root_id are left entirely 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?

States a specific verb and resource ('Read an approved discussion or a specific branch') that maps onto the root_id and branch_id parameters. It distinguishes a read operation from the witness_submit/witness_validate siblings, though 'discussion'/'branch' remain somewhat abstract terms.

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 notes that pending and withdrawn content is not public, giving a useful restriction, but offers no explicit when-to-use guidance or routing among read-oriented siblings such as witness_roots, search_corpus, or read_song. Usage is only 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is clear. The description adds useful context that the tool reads fixed origins, checksums, and participation limits, but it does not elaborate on auth needs, fixed-value behavior, or return shape beyond the listed contents.

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 definition is a single front-loaded sentence with no redundant text. It efficiently names the action and the specific archive contents being read.

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 annotations covering safety, the description is nearly complete: it identifies the archive and the values returned. It falls short of 5 because terms like 'capsule origins' and 'participation limits' remain somewhat opaque without an output schema to clarify returned fields.

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 there are no parameter semantics to document. The empty schema is consistent with the description, and no parameter-level guidance is needed.

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

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

The description gives a specific verb ('Read') and resource ('the two fixed capsule origins, checksums and participation limits of the separate Witness Archive'), so the operation is identifiable. It does not explicitly distinguish this from sibling tools such as witness_read, but the listed contents make its scope more specific than a generic archive read.

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 what is read but gives no guidance on when to use this tool instead of witness_read, witness_validate, or other Witness Archive siblings. No prerequisites, exclusions, or alternative-selection criteria 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?

Adds real behavioral context beyond the annotations: submission is gated on a human moderation queue, nothing becomes public until approved, and it never opens an autonomous conversation. These are post-submission consequences that readOnlyHint/openWorldHint cannot express, which is exactly the value the description should carry.

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

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

Three short sentences, each doing distinct work: action+destination, hard precondition, and post-submit behavior. No filler and the critical attestation requirement 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?

The behavioral half is well covered for a mutation tool with no output schema, but given a 13-parameter required-heavy schema the description leaves the agent under-informed about structuring the payload and does not cross-reference witness_roots for root_hash or witness_validate for pre-checks. Adequate, with clear 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?

With 13 parameters, 10 required, and only 31% schema description coverage, the description should compensate but only addresses authorization_attestation. It says nothing about the required content triad (thesis/interpretation/counterargument), the root_id/root_hash pairing, provenance or kind enums, or the factual_claims→sources dependency.

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

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

States a specific verb (Submit) and resource (an interpretation to the Witness Archive moderation queue), with the distinguishing qualifier 'explicitly authorized'. This clearly separates it from witness_read, witness_roots, witness_validate, and submit_voice without opening any schema.

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

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

Gives a concrete precondition ('Requires authorization_attestation=true') and clarifies the outcome (moderation queue, human approval before public). It does not, however, name an alternative or sequence such as 'run witness_validate first', leaving workflow ordering to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is partly covered. The description adds useful behavioral context by stating that validation stores nothing, publishes nothing, and grants no permission.

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 concise sentences with the core purpose and key constraint front-loaded. There is no wasted language.

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?

This is a complex tool with many required parameters, low schema description coverage, and no output schema. The description is too sparse to explain what validation actually checks, how failures are reported, or what the required fields mean.

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 low at 31%, and the description does not explain the 13 parameters or the 9 required fields. It only vaguely references a draft, root quotation, and lineage, leaving most parameter meaning to the schema.

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

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

The description states a specific verb and resource set: check a draft, exact root quotation, and reply lineage. It also clarifies the non-storing, non-publishing scope, though it does not explicitly name sibling tools such as witness_submit 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 phrase 'without storing or publishing it' implies this is a pre-submission check, and 'Validation grants no permission' signals what it does not do. However, it does not explicitly say when to use this versus witness_submit or other validate_* tools.

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