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

With no annotations, the description carries the responsibility for behavioral disclosure. It explains the aggregation behavior, the output components, and adds an important caveat that rates are not gold-standard calibrated and are only as valid as the sample. It does not mention side effects, but the operation appears read-only and an output schema exists.

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

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

The description is three sentences with no filler: purpose first, then parameter usage, then a caveat. Every sentence earns its place and the front-loaded structure helps an agent quickly understand the tool.

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

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

The description covers purpose, both input modes, and the key validity limitation, while the output schema handles return-value details. It leaves minor ambiguity about behavior when both `assessments` and `use_session` are supplied or when neither is supplied, but this is not a major gap.

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

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

Schema description coverage is 0%, so the description must add meaning. It explains both parameters: `assessments` accepts an array of assessment objects, and `use_session=true` switches to aggregating every assessment produced this session. It could be more precise about the required shape of assessment objects, but it provides enough guidance.

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

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

The description opens with a specific verb ('Roll up') and resource ('many assessments'), and clearly names the output: per-item completeness rates plus coverage denominators. This distinguishes it from sibling tools that parse, assess, or render individual items rather than aggregate them.

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

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

The description gives concrete usage instructions: pass an array via `assessments` or set `use_session=true` to aggregate session-produced assessments. It does not explicitly name sibling alternatives or state when not to use the tool, but the two modes are clearly explained.

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

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

With no annotations, the description carries the behavioral burden and does so well: it reveals that scaffold mode returns a prompt/schema/hash for the caller to execute, judge mode triggers a pinned-model API call requiring ANTHROPIC_API_KEY, and scoring is caller-independent. Minor gaps remain such as explicit side-effect/cost phrasing, but the core execution flow is disclosed.

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 front-loads the main purpose and then structures the two modes clearly. It is longer than average but each section adds behavioral or usage value, with 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 five-parameter tool with two distinct modes and a rich output schema, the description covers the overall flow and inter-tool dependencies well. It is incomplete on three parameters and does not explicitly describe the output schema's role, though an output schema exists to fill that gap.

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

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

It gives strong semantics for the two most important parameters: document (path/raw text/text_sha256) and mode (scaffold vs judge). However, with schema description coverage at 0%, model, spec_version, and manuscript_id are left completely unexplained, so the description only partially compensates for the missing schema 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 first sentence states a specific action ('Assess a manuscript') against a defined scope ('all applicable TARGET leaves in one batched pass'), and the rest distinguishes the two execution modes. This sets it apart from siblings like parse_manuscript (ingestion) and submit_scaffold_verdicts (validation) without needing to open schemas.

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

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

It explicitly maps scaffold mode to interactive LLM-in-the-loop review and judge mode to headless/batch corpus runs, and even advises that judge is 'overkill' for interactive review. It also names the follow-on tool submit_scaffold_verdicts and references parse_manuscript as the input source.

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

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

With no annotations, the description carries the full burden and does useful work: it discloses that blind mode withholds the instrument's verdict to prevent coder anchoring and that the emitted rows are blank except for intent and boundaries. It does not mention failure behavior when neither `assessments` nor `use_session` is provided, but the core behavioral traits are clearly stated.

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 dense sentences with no filler. The output purpose and structure are front-loaded, followed by the critical behavioral caveat and the invocation prerequisite. Every clause adds distinct value.

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 that an output schema exists, the description does not need to restate return values. It covers purpose, output shape, the blind mode, and data-source options. The main gap is the absence of explicit behavior when neither `assessments` nor `use_session` is set, and the vague semantics of `use_session`.

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 explains `blind` well and indicates that `assessments` and `use_session=true` are alternative data sources, but it does not describe the expected structure of `assessments` entries or what `use_session` actually retrieves, leaving two of three parameters under-specified.

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 ('Emit') and resource ('blank per-paper coding sheets') and explains the exact output structure: one row per applicable leaf with intent, verdict boundaries, and empty verdict/evidence/note fields. This clearly distinguishes it from sibling rendering, parsing, and assessment 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?

It gives explicit context for the primary reference standard use case ('use blind coding for the primary reference standard') and tells the caller to pass `assessments` or `use_session=true`. It does not explicitly name alternatives or when not to use the 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?

With no annotations provided, the description carries the burden for behavioral disclosure. It explicitly marks the tool as 'introspection only', notes the version pinning behavior, and warns about duplicated rubric payloads when called alongside assess_manuscript. It does not explicitly state that it makes no modifications, but 'introspection only' strongly implies a read-only operation.

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

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

The description is front-loaded with the core purpose and content details, followed by a useful usage warning. It is slightly longer than strictly necessary because the second paragraph restates the optionality that earlier wording implies, but every sentence contributes actionable information and there is no fluff.

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

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

For a single-parameter, no-annotation, introspection tool, the description covers what the tool returns, how the version parameter works, and how it relates to the assess_manuscript flow. The presence of an output schema reduces the need to describe return structure. It does not discuss relationships to render_checklist siblings, but the word 'encoded' and the detailed content list make the tool's role reasonably clear.

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 provides a 'version' parameter with a default but no description, and schema coverage is 0%. The description compensates by explaining the parameter's meaning: 'Pass a version id to pin; omit for the current default.' This is sufficient for selecting a version, though it does not enumerate valid version values or formats.

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 ('Return the encoded TARGET checklist spec') and enumerates the exact content of the spec: 39 leaf subitems, 21 published items, intents, notes, signal terms, pairing links, and applicability rules. It also differentiates from assess_manuscript by clarifying that get_checklist is for standalone inspection, not an assessment prerequisite.

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 when-to-use and when-not-to-use guidance: it is 'OPTIONAL in the review flow', 'introspection only', and should not be combined with assess_manuscript because that already embeds the rubric. It closes with a direct instruction: 'Use this when you want to inspect the spec on its own, not as a required step before assessing.'

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains server-side file visibility, error-on-missing-path behavior, the effect of hints on text_sha256, the default behavior of supplement_status, warnings about swallowed introductions, and the return payload. This is far beyond what the schema alone conveys.

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-loaded with its primary purpose and then organized by parameter. Every section earns its place because the tool has six parameters, several subtle failure modes, and important integration caveats. It could be tightened slightly, but the length is justified by the complexity.

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, parameter semantics, error behavior, defaults, alternatives, and return values. It even explains why supplements matter for TTE methods and what happens when citation is omitted. Given the tool's complexity, the absence of annotations, and 0% schema coverage, this description is remarkably complete.

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 every parameter, and it does. citation, document, supplements, supplement_status, and section_hints all receive detailed semantic guidance, including formats, defaults, failure modes, and examples. Only manuscript_id is left undocumented, but the critical parameters are thoroughly explained.

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

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

The description opens with a specific verb and deliverable: 'parse a manuscript into a SectionMap with character-offset, source-tagged section spans.' This clearly distinguishes the tool from siblings like get_checklist, render_checklist, and assess_manuscript, and it identifies parse_manuscript as the 'PRIMARY entry point,' making its role in the pipeline unambiguous.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: paste text rather than a server-invisible path, use parse_pmcid for open-access PMCIDs, pass supplements when they exist, and reserve section_hints for last-resort section detection failures. It also names the alternative tool directly, so an agent can route correctly without guessing.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It covers fetching behavior (JATS plus supplements), supplement_status interpretation, the error condition (raises if no open-access full text), the return relation to parse_manuscript, and the auto-built citation with override. This is rich, concrete context beyond what the schema shows.

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?

Every sentence in this multi-sentence description adds functional information: batch use, alternative, fetch scope, status semantics, error, return, and citation. No filler or repetition; dense but scannable.

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?

Despite no annotations, the description covers selection criteria, behavior, error handling, return type (same summary as parse_manuscript), and an override option. The presence of an output schema covers structural return details, so the description is effectively complete for an agent deciding whether and how to invoke this tool.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies pmcid (by PMCID from Europe PMC) and citation (override auto-built reference), but include_supplements is only implicitly covered by the statement that supplements are fetched if available. The description never explicitly names the parameter or explains the effect of setting it false, leaving partial compensation.

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

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

The description opens with a clear verb-object pair: 'retrieve an open-access article from Europe PMC by PMCID and parse it.' It also explicitly distinguishes itself from parse_manuscript, so an agent can select between siblings without reading the schema.

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

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

States exactly when to choose this tool: 'corpus/batch case (no file in hand)' or 'auto-fetch an open-access paper's supplement' and when not to: 'for a single manuscript you were given, use parse_manuscript instead.' Also ties its output to assess_manuscript via the text hash, strengthening routing.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool is a pure projection, returns structured rows plus a completeness tally and Markdown table, and that views affect columns. It could go further on edge cases like conflicting inputs, but the core behavior is clearly communicated.

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 dense but efficiently structured: purpose, detailed output/views, return artifacts, input options, and a final behavioral boundary. Every sentence adds value and the front-loading lets an agent quickly identify the tool's purpose.

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 that an output schema exists and covers return shape, the description appropriately focuses on input selection, view modes, and the pure-projection guarantee. This is enough for an agent to decide when and how to invoke the tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. It explains both view values ('enriched' and 'official') with column-level effects and clarifies the two possible input sources: assessment or manuscript_id. It does not fully document the structure of the assessment object, but all parameters receive meaningful guidance.

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

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

The description begins with a specific verb and resource: 'Render a finalized assessment as the completed TARGET checklist form'. It details the 21 published items, 39 leaf rows, the Location-reported column, and clarifies the output type, clearly distinguishing this from scoring and document-rendering siblings. The explicit 'pure projection — no re-scoring' further disambiguates it from assessment 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 clear context for when to use the tool: pass either a full assessment object or a manuscript_id assessed earlier in the session. It also signals that this is not a scoring tool. However, it does not explicitly name alternatives such as render_checklist_docx or render_checklist_html when a different output format is needed.

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

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

With no annotations, the description carries the full burden, and it goes well beyond a basic summary. It discloses the base64 return payload, the caveat that the server filesystem path is not the caller's and content_base64 should be used instead, and the nuanced logo behavior where the banner is ignored on the enriched view and logo_applied is False.

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 dense but every section earns its place: purpose, content differences, retrieval instructions, path caveat, and logo behavior. It is front-loaded with the main purpose and uses clear paragraph headers to separate retrieval and logo guidance, making it easy for an agent to scan.

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

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

Given the five parameters, zero annotations, and the need to explain file retrieval and view-specific behavior, the description covers everything required to call the tool correctly. It explains how to obtain the deliverable, the effect of each key parameter, and the subtle logo restriction, leaving no critical gap.

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

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

Schema description coverage is 0%, so the description fully compensates. It explains the alternatives assessment vs. manuscript_id, the meaning and effect of view='official', the semantics of path as a server-local temp location that callers should avoid, and the behavior of logo including its default off state.

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

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

The description opens with a specific verb and resource: 'Write the completed TARGET checklist to a Word (.docx) file and return it.' It clearly distinguishes itself from render_checklist and render_checklist_html by specifying the docx serialization and the added Location-reported column, so an agent can identify which sibling to invoke.

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 strong context: it explains when to pass an assessment object vs. manuscript_id, how view='official' changes the output, and what logo=True does. It does not explicitly state 'use this instead of render_checklist_html when you need a Word document,' but the docx naming and 'serialized as a submission-ready landscape table' make that usage context clear.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses return values (html string and base64 content), the provenance stamp, the self-contained nature, and view behavior ('view='official' strips to the published form's three columns'). This is strong, though it does not discuss side effects or failure modes.

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 dense but every clause adds value: purpose, relationship to sibling, output details, input requirements, and view option. It is front-loaded with the primary action and maintains a clear structure despite its length.

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

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

The description covers the essential operational needs: inputs, output format, and a view variant. It is slightly incomplete regarding what happens when no input is provided or when both assessment and manuscript_id are supplied, but overall it gives enough context for correct invocation.

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

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

Schema description coverage is 0%, but the description compensates by explaining that either an assessment object or manuscript_id should be passed, and that view='official' changes the output. It does not fully describe all possible view values or the exact shape of the assessment object, leaving some room for ambiguity.

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 ('Render the completed TARGET checklist as a self-contained HTML page') and clearly identifies the output format. It also distinguishes the tool from its sibling render_checklist by noting 'same content as render_checklist' while adding the HTML/browser context.

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 guidance on when to use this tool: when an HTML page is needed, viewable in any browser. It also tells the agent what inputs to provide ('Pass a full assessment object or the manuscript_id of one assessed this session'). However, it does not explicitly state when not to use it or compare against render_checklist_docx.

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

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

With no annotations, the description carries the behavioral burden and fully discloses consequences: the only canonical output is the stamped report, extra formats increase context usage, parse cache is not persistent, and re-parsing can be triggered transparently via document. It also clarifies intended authority of analytic memos so agents do not substitute commentary for the stamped form.

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?

Long but tightly organized: the opening defines the operation, the middle establishes canonical output and exclusions, and the final paragraph covers rendering and caching edge cases. The emphasis markers and repeated no-hand-assembly warnings are intentional guardrails, not 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?

Given the tool's complexity with 7 parameters, no annotations, and an output schema, the description supplies all essential operational context: return value identity, verification semantics, alternative format paths, and failure/recovery scenario for cache misses. Nothing needed to invoke it correctly is omitted.

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 does for the important parameters: items structure, text_sha256/document cache behavior, render false, and report_formats allowed values. It leaves model and spec_version semantically unexplained, though their defaults and titles reduce the risk.

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 opening states a specific action — validate verdicts and return the stamped assessment plus rendered deliverable — with clear scope (scaffold-mode completion). It also distinguishes itself from render_checklist/render_checklist_docx by naming them as the re-rendering route rather than hand-assembly.

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

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

The description makes the when explicit: it is the forced completion call after verdicts are produced, and it gives explicit alternatives for format conversion (render_checklist, render_checklist_docx, report_formats) and for skipping rendering (render=false). It warns against hand-assembling the deliverable, which prevents a common misuse.

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

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

With no annotations, the description carries the full behavioral burden, and it does so well: it discloses that agreement is computed per leaf, that the pooled figure is orientation-only, that the human coding is the reference standard, and that a span-keyed disagreement list is produced. It does not discuss side effects or error conditions, but 'Compute' implies a read-only analysis and the output schema presumably covers return structure.

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 dense sentences with no filler: the first states what is computed and the metrics, the second clarifies the per-leaf vs pooled distinction, and the third defines both parameters. Every sentence earns its place and important scope qualifiers are 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?

Given the output schema exists, the description is not required to explain return values, and it provides the essential input relationship and reference-standard orientation. Minor gaps remain around exact required fields inside the array objects and potential constraints like same-length or spec-version matching, but the description is sufficiently complete for a generic-object validation tool.

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

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

Schema coverage is 0%, so the description must compensate. It names both arguments, states they are arrays of objects, identifies their roles ('instrument' vs 'human_codings'), and clarifies that they share manuscript ids and spec version. It does not enumerate individual object fields, but since the schema uses additionalProperties: true, there is no structured field detail to compensate for.

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

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

The description opens with a specific verb ('Compute') and a precise resource ('per-leaf agreement between instrument assessments and human gold-standard codings'), then enumerates the concrete metrics produced. This clearly distinguishes it from the parse/render/assess/aggregate sibling tools, none of which perform gold-standard validation.

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 this tool is appropriate: when you have instrument assessments and human gold-standard codings to compare. It does not name alternatives or explicit exclusions, but the context is unmistakable given the siblings are all about parsing, rendering, assessing, or aggregating—not validating against gold standards.

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