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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description details the output structure (coverage statement, counts per tier, red/orange rows), the meaning of red and orange (check this vs cannot verify), and the deep mode behavior (slower, opt-in, limited to 3/month, answers are a review queue not a verdict). It also discloses free tier limits and API key lifting. No contradictions 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?

The description is long but every sentence carries critical information. It is front-loaded with the core function, then usage, then output details, limitations, deep mode, and free tier. It is organized logically without redundancy, making efficient use of the reader's attention.

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 no output schema, so the description must explain the return values. It does: coverage statement, counts per tier, one line per row needing human, number of citations, and report id for render_report. It also explains what it cannot do and the meaning of red/orange. The description fully equips an agent to call the tool correctly and interpret results.

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?

Although schema coverage is 100%, the description adds substantial meaning to the 'deep' parameter: it explains that it checks whether the opinion supports the sentence, is slower (1-2s per citation), sends the clause to a model judge, is limited to 3/month, and returns a review queue. For 'text', the schema already describes it, but the description reinforces its use for prose. The description adds value beyond the schema.

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

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

The description states a specific verb and resource: 'Check every case citation in a text against proofread.law's register of about 10 million US court opinions'. It also specifies the use case (draft brief, memo, letter) and differentiates from siblings by explicitly stating what it cannot do (resolve WL/Lexis, check statutes/regulations).

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 instructs when to use it: 'Use it on a draft brief, memo, letter or any prose that cites cases, before the citations are relied on.' It also lists exclusions (cannot resolve WL/Lexis, check statutes, etc.) and describes the deep mode option with clear trade-offs (slower, opt-in, limited). This provides clear guidance for selecting this tool over 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?

Richly discloses behavior beyond annotations: file is uploaded to proofread.law, processed in memory, and discarded; deep mode sends clauses to a model judge with speed/cost limits; red/orange row semantics are explicitly defined. This gives agents crucial context that annotations (readOnlyHint, openWorldHint) do not cover.

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?

Front-loaded with the main purpose and then details, but is a dense block of text that could be broken into bullets for readability. Still, every sentence carries informative value, so it is appropriately sized for the tool's 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?

Covers purpose, input constraints, data handling, output shape (coverage statement, counts, red/orange rows, report id), limitations, and deep-mode semantics. With no output schema, the description proactively explains what the agent will receive and how to interpret results, making it highly 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?

Although schema coverage is 100%, the description adds significant meaning: for path it adds the 10 MB limit and unreadable formats; for deep it explains what it does, the performance cost, free-tier quota, and that results are a review queue rather than a verdict. This is well beyond the schema's basic property descriptions.

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 action ('Check every case citation in a document on disk') with explicit formats, size limit, and target register. It distinguishes from siblings by referencing the 'same compact result as check_citations' and explicitly excludes 'resolve Westlaw (WL) or Lexis identifiers', separating it from resolve 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?

Gives clear context for when to use (file-based citation checking) and lists exclusions (scanned PDFs, encrypted PDFs, legacy .doc, .docx paid plan). It also states what it cannot do, which is an implicit when-not, but it does not explicitly name sibling tools as alternatives for specific cases (e.g., 'use check_citations for text input').

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?

Beyond the readOnly and idempotent annotations, the description adds meaningful behavioral details: nothing submitted is stored, known gaps and un-checked item types are disclosed, and the call has no billing impact. This gives the agent accurate expectations about side effects and scope.

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 well-structured, with the main claim front-loaded and parenthetical details kept relevant. Every clause adds either content coverage, usage timing, or a caveat about cost, so no sentence is wasted.

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

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

For a parameterless informational tool with no output schema, the description is complete: it explains what the result contains, when to invoke the tool, and the privacy/billing implications. An agent has everything needed to decide to call it and to understand the response.

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

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

The tool has zero parameters and the schema coverage is 100%, so there is nothing for the description to clarify about inputs. The description instead explains what information the call returns, which is the appropriate contribution for a parameterless tool.

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

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

The description states exactly what the tool returns: a coverage statement and a storage notice, with the scope of the coverage spelled out. It is clearly distinguished from the sibling tools, which perform checking, resolution, or report rendering, by being the meta-informational tool.

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

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

The description gives explicit trigger conditions: use it when a user asks what the check covers, how current it is, or what happens to their text. It also clarifies that the call is free and not counted as a check, which prevents 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior; the description adds valuable non-obvious details: the exact output structure and the fact that report ids live only in server memory until the server exits. There is 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 dense sentences carry all essential information: the first covers purpose and output composition, the second covers usage context and parameter provenance. There is no filler or redundant restatement of the 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?

For a read-only rendering tool with two optional parameters and no output schema, the description fully covers what the tool does, what it produces, and how to obtain valid inputs. The server-memory warning is especially valuable for correct invocation. Nothing critical 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?

Both parameters are already documented in the schema, so the baseline is 3. The description adds meaning by clarifying that report and report_id are alternatives, where each comes from, and the server-memory lifetime constraint that affects whether a report_id remains valid.

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

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

The description clearly states the tool's function: turning a finished check into a markdown diligence report, and enumerates the report's components. It distinguishes render_report from check_citations and check_document by positioning those as producers of the report_id this tool consumes.

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 an explicit use condition: 'Use it when the user wants a report to keep or attach to the file.' It also explains the expected input sources (report_id from check tools or full JSON from /verify), but it does not explicitly list when not to use the tool or compare it against coverage/resolve siblings.

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 extensive behavioral context beyond annotations: it enumerates all possible statuses, explains that 'not in the register' is never proof of nonexistence, clarifies the meaning of red and orange rows, and discloses quota impact. This is consistent with the openWorldHint and readOnlyHint 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?

Although long, every sentence carries essential operational information: purpose, scope, statuses, exclusions, interpretive warnings, and quota behavior. The opening sentence front-loads the core function, and the rest is a compact structured list of caveats.

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 compensates fully by explaining what the tool answers, the statuses an agent may encounter, and how to interpret ambiguous or negative results. Nothing critical is missing for an agent deciding whether 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?

The single parameter is fully documented in the schema, which already explains that 'only the reporter citation is resolved.' The description adds concrete examples ('590 U.S. 644', 'Bostock v. Clayton County, 590 U.S. 644 (2020)') and clarifies that surrounding case name and year are acceptable, slightly enriching what the schema provides.

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 ('look up a single case citation ... in proofread.law's register') and the exact question it answers, including the fields returned. It explicitly distinguishes itself from sibling tools by noting this is a register lookup and that a mismatch means 'the citation points elsewhere.'

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 when-to-use guidance: 'Use it when one citation is in doubt; use check_citations for prose, and resolve_citations for a list.' It also lists clear exclusions ('Cannot: resolve Westlaw (WL) or Lexis identifiers, check statutes, regulations or secondary sources, or say whether a case is still good law').

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 provide read-only, open-world, idempotent, and non-destructive hints. The description goes further by disclosing result categories, quota accounting, red/orange row semantics, and unsupported inputs. It adds substantial operational context beyond the annotations with no contradiction.

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 front-loaded with the core purpose, followed by usage guidance, limitations, and quota. Every clause contributes useful information, though it is slightly long and repeats 'up to 500', keeping it from a perfect 5.

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 tool has one well-described parameter, rich annotations, and no output schema, so the description must carry return-value and interpretation details. It fully covers result categories, ordering, limitations, quota, and how to interpret ambiguous rows, making it complete for agent invocation.

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

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

The schema already fully describes the single 'cites' parameter at 100% coverage, so the baseline of 3 applies. The description reinforces that these are case citation strings and that output preserves input order, but it does not add syntax, formatting, or example details beyond the schema.

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

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

The description states a specific verb ('look up'), a specific resource ('up to 500 case citation strings in proofread.law's register'), and a clear output shape (one line per citation). It explicitly contrasts this tool with check_citations, distinguishing it from a key sibling.

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 contexts: 'table of authorities or any list of citations you already have.' It names the alternative for prose (check_citations) and lists exclusions (Westlaw/Lexis identifiers, statutes, regulations, secondary sources, good-law checks), so an agent can decide when not to use it.

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