Check legal citations in a file

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

Annotations already mark the tool readOnly and idempotent, and the description adds valuable behavior beyond that: the file is uploaded and discarded, red rows mean 'check this' not 'case does not exist', orange rows mean 'cannot verify', and the deep=true mode sends the clause to a model judge but returns a review queue, not a verdict. 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?

The description is longer than average but densely packed with essential constraints and disclaimers. It front-loads the core action and then efficiently layers limitations, result semantics, deep mode, and API-key behavior. There is minor duplication with the schema's deep parameter description, which keeps it from a 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?

Despite having no output schema, the description specifies the return shape (same compact result as check_citations: coverage statement, tier counts, one line per red/orange row, citation count, report id). It also covers file constraints, semantic meaning of each result color, deep-mode caveats, and auth/rate-limit behavior. Nothing critical is missing.

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

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

The input schema already covers both parameters with high quality and 100% coveragechers, so the baseline is 3. The description adds meaningful extra semantics: path must point to PDF/DOCX/TXT/MD up to 10 MB, excludes scanned/encrypted/.doc files, explains .docx plan requirement, and elaborates what deep=true does beyond the schema's 'slower, opt-in, 3 per month'. This is more than compensation, so 4 is justified.

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 the verb ('Check'), the resource ('every case citation in a document on disk'), and the matching authority (proofread.law's register of ~10 million opinions). It clearly distinguishes itself from the sibling check_citations by being file-based, while still referencing check_citations for result-shape continuity.

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

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

The description gives a clear operational context: what file types are supported, size limit, paid-plan requirement for .docx, and explicit exclusions ('Cannot: resolve Westlaw or Lexis identifiers, check statutes, regulations or secondary sources, or say whether a case is still good law'). It lacks an explicit 'use sibling X instead when...' recommendation, so it misses the top score by a small margin.

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