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

Beyond the annotations, it discloses that no charge happens until the owner pays, that the plan activates within a minute, that an API key is required, and that an existing subscription yields 409. This adds meaningful behavioral context without contradicting the structured 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 front-loaded with the core action, then efficiently covers usage triggers, prerequisites, plan details, and behavioral caveats. Every sentence contributes distinct, decision-relevant information; there is no filler.

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

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

For a one-parameter tool with no output schema, the description covers the essential context: when to call it, what it returns (a checkout link), authentication needs, plan semantics, payment timing, and the error case for existing subscriptions. An agent has what it needs to select and invoke the tool correctly.

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 plan parameter is already enumerated in the schema, but the description adds real business meaning: payg is per-check with no monthly fee, solo and firm are monthly, and firm includes more keys. It also points to current pricing, going well beyond the schema's bare enum.

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: "Get a Stripe Checkout link that upgrades this API key's account to a paid plan," and even includes the endpoint. It clearly distinguishes this billing tool from the sibling checking/reporting tools like check_citations and coverage.

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 triggers: use it when a check returns 402 or 429, or when the user asks to upgrade. It also explains when not to use it: an account with an existing subscription returns 409 and should use the billing portal instead.

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 annotations (readOnly, idempotent), the description discloses the return format (coverage statement, counts per tier, rows per tier, report id), the semantics of red/orange rows, the fact that deep mode sends clauses to a model judge, and rate limits (free tier 20/month, deep 3/month). This goes well beyond the annotations and gives the agent a clear behavioral model.

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: purpose in the first sentence, usage in the second, then returns, limitations, result interpretation, deep mode, and limits. Each sentence adds distinct information with no redundancy, though it is long. It could be trimmed slightly, but the detail is mostly necessary for correct use.

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 fully specifies what the tool returns (coverage statement, counts per tier, one line per row needing human, number of citations, report id) and how to interpret red/orange rows. It also covers limitations, deep mode, and rate limits, making it complete for an agent to invoke correctly.

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 100%, so parameters are already documented. The description adds context for deep=true: it generates white rows, takes 1-2 s per citation, sends clauses to a model judge, and produces a review queue, not a verdict. For text, it repeats the schema's 'paragraphs, footnotes, a whole brief' but adds context about draft briefs and memos; the added value is moderate but meaningful.

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 (CourtListener bulk data).' It also lists what the tool cannot do ('Cannot: resolve Westlaw (WL) or Lexis identifiers, check statutes, regulations or secondary sources...'), which clearly distinguishes it from sibling resolve_citation(s) and check_document 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 explicitly says 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 states exclusions via the 'Cannot' list, and describes deep=true as an optional mode, so an agent knows when not to enable it. The interpretation guidance for red/orange rows further clarifies usage.

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 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.

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant context beyond these: it details what is not checked (Westlaw/Lexis identifiers, statutes, regulations, secondary sources), clarifies the storage notice (text not stored, only saved briefs encrypted), and notes the tool is free and not counted as a check. 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 dense but well-structured. It front-loads the core purpose (coverage statement and storage notice), then elaborates on the jurisdiction parameter, then gives usage triggers. While it is a bit long, every sentence contributes necessary information—no fluff. The structure aids readability.

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 tool with one optional parameter and no output schema, the description is fully self-sufficient. It covers what the tool does, when to call it, parameter semantics, behavioral details (storage, free usage), and jurisdiction variants. An agent has everything needed to invoke it correctly without additional context.

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 describes the 'jurisdiction' parameter with a default and options. The description adds valuable context: it explains what the Swiss register includes (BGE/ATF/DTF, Federal Supreme Court dockets, federal courts, 26 cantons) and that it lists courts held and share of live index. This goes beyond the schema's simple enum description, enriching the parameter's meaning.

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 clear purpose: it returns the coverage statement and storage notice. It explicitly lists what the coverage includes (opinions, date, gaps, exclusions) and mentions the jurisdiction option, making it distinct from any sibling tool that deals with checking or briefs. No ambiguity about what it does.

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: 'Call it when a user asks what the check covers, how current it is, or what happens to their text.' It also explains the jurisdiction parameter for Swiss case law. It does not explicitly say when not to use it, but the conditions are clear enough for an agent to decide.

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 destructiveHint=true and readOnlyHint=false, but the description adds crucial context: deletion is permanent and unrecoverable, no check is run before deletion, and saved briefs are stored encrypted until removed. It also explains the API key requirement. This goes well beyond the annotations and fully discloses the destructive behavior.

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

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

The description is compact and front-loaded with the most important fact (permanent deletion). Every sentence adds meaningful context: permanence, when to call, no-check behavior, opt-in saving, encryption, and API key. Slightly long but each clause earns its place; no 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?

For a destructive single-parameter tool with no output schema, the description covers everything an agent needs: what gets deleted, permanence, confirmation step, no-check behavior, storage/encryption context, and authentication requirement. The sibling list and schema complete the picture.

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 100% and the single parameter 'id' is already described in the schema. The description adds value by explaining the id comes from save_brief or list_briefs and that it should be confirmed if in doubt. Since the schema already covers the parameter well, a 4 is appropriate rather than 5.

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 ('Permanently delete'), a specific resource ('a brief and all its saved versions'), and the account context ('user's proofread.law account'). It clearly distinguishes from siblings like save_brief, update_brief, and list_briefs by emphasizing permanence and deletion.

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?

Explicitly says 'Only call it when the user asks to delete that brief' and instructs to confirm with list_briefs if the id is in doubt. It also clarifies that saving is opt-in and that check_citations/check_document never save, which prevents misuse. This is strong when-to-use guidance with an alternative named.

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 annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds specific behavioral context: it only reads, saves nothing, runs no check, and explicitly names the tools that do save (save_brief, update_brief). It further discloses that saved briefs are stored encrypted until delete_brief removes them and that an API key is needed. This goes well beyond the annotation booleans.

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 information-dense; every sentence delivers actionable detail (what the report contains, the read-only guarantee, opt-in saving, encryption, API key). It front-loads the core purpose in the first sentence and then layers usage, constraints, and caveats logically. A slight trim could tighten it, but the verbosity is justified given the tool's scope.

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 tool with 3 parameters and no output schema, this description covers all necessary facets: return contents, parameter usage, side effects (none), storage/encryption, authentication, and relationships to sibling tools. Nothing an agent needs to invoke it correctly is missing, and the annotations already handle safety hints, so the description is 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?

The input schema already documents all parameters thoroughly (coverage 100%), so the baseline is 3. The description adds practical semantics: id is sourced from save_brief or list_briefs, version refers to an earlier entry in the versions list, and include_text=false is recommended for long briefs. This enriches the schema's descriptions with real-world usage context, pushing it to a 4.

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 ('Get') and resource ('one brief saved in the user's proofread.law account'), then enumerates exactly what is returned (saved text, report details, versions). It explicitly differentiates from siblings like save_brief, update_brief, delete_brief, and list_briefs by describing its read-only retrieval role and mentioning render_report and update_brief as downstream consumers.

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 tells the agent when to use it ('to pick up where the user left off' or 'to get the exact saved text before editing it for update_brief'), and when not to (it saves nothing, runs no check, and saving is opt-in only via save_brief or update_brief). It also clarifies the use of include_text and version parameters with practical guidance ('a long brief is long'), and mentions the required API key.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by explicitly stating that the tool 'only reads: this tool saves nothing and runs no check,' reinforcing the read-only nature and clarifying that it does not trigger any analysis. It also discloses that saving is opt-in and never happens implicitly, which is crucial for agent decision-making. This goes beyond the annotations by clarifying the side-effect-free guarantee in operational terms. Minor gap: it doesn't mention pagination or sorting, but for a zero-parameter tool, the return is likely a complete list, so this is acceptable.

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 moderately sized, covering multiple aspects: what is returned, when to use it, and the non-saving guarantee. It is appropriately front-loaded with the primary purpose and returned fields, and only later explains the saving semantics, which is secondary. The sentences are information-dense but not excessive; they earn their place by adding unique behavioral and usage context. A slight deduction because the save-semantics explanation could be condensed, but it is relevant for avoiding misuse.

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 simplicity (zero parameters, no output schema, no nested objects), the description is complete. It tells the agent what the tool does, what it returns, when to use it, and what side effects (none) it has. The annotations cover safety, and the description provides all the operational details needed for an agent to call it correctly. The only missing piece might be an explicit statement about the return format (e.g., 'array of objects'), but the description's enumeration of fields implies the structure. For this complexity level, nothing essential 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 tool has zero parameters, and the schema is effectively empty, so there is nothing to document. The baseline for zero-parameter tools is 4, as the description doesn't need to add parameter details. The description appropriately focuses on the return value and usage context, which is what the agent needs to know. It does not repeat any schema information because there is none. This is a well-handled case where the description compensates for the lack of parameter structure by being clear about outputs.

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 purpose: listing saved briefs and their metadata. It specifies the exact resource ('briefs saved in the user's proofread.law account') and enumerates the returned fields (id, title, timestamps, citation counts, tier counts, versions). It distinguishes itself from siblings by explicitly stating 'Use it to find a brief's id... before get_brief, update_brief or delete_brief,' which differentiates it from get_brief (which retrieves a single brief) and other operations.

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 provides explicit when-to-use guidance: 'Use it to find a brief's id when the user refers to a draft by name, before get_brief, update_brief or delete_brief.' It also clarifies when not to use it relative to saving operations: 'Saving is opt-in: nothing is saved unless save_brief or update_brief is called (check_citations and check_document never save anything).' This helps the agent decide between list_briefs and save/update tools, and provides clear context for the typical workflow.

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 mark it read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: report IDs live in server memory only until exit, the tool is free and uncounted, and it expects a 'finished' check rather than an arbitrary input.

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 each earn their place: purpose and output structure, usage condition and input sources, then a terse free/uncounted note. The content is front-loaded with the core verb and resource before details.

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 by detailing what the report contains. It also covers both input alternatives, the memory constraint, the finished-check prerequisite, and cost behavior, leaving no obvious gap for an agent to call it correctly.

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 100% and both parameters already have clear descriptions. The description adds useful cross-tool context by tying report_id to check_citations/check_document results and clarifying that either report_id or full report JSON can be supplied, though it does not add substantial new syntax-level detail.

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 phrase, 'Turn a finished check into a markdown diligence report,' and enumerates the report's exact composition: header, coverage/storage notices, sorted summary table, and per-row detail blocks. This makes the tool's role as a rendering step distinct from sibling checking and resolution 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 explicitly states when to use the tool: when the user wants a report to keep or attach, or when the compact result was cut short. It does not explicitly state when not to use it or name alternatives, so it falls 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description substantially adds behavioral context: enumerates statuses (found, ambiguous, not in register, cannot verify, known citation, no citation recognised), clarifies that a 'not in register' result is 'never proof that the case does not exist,' and explains red/orange row semantics. It also discloses quota impact and API-key behavior. 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 long but every sentence earns its place. It front-loads the core purpose, then lists statuses, usage guidance, exclusions, and quota notes in a logical order. No redundancy or filler; each clause adds distinct information that 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?

With no output schema, the description carries full responsibility for explaining return semantics, and it does so comprehensively: statuses, coverage qualifiers, red/orange row meanings, quota limits, and API-key behavior. It covers error cases and ambiguity handling. Nothing an agent needs to call this correctly or interpret the result 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?

Schema description coverage is 100% (the citation parameter is described as 'One citation string'), so baseline is 3. The description adds meaningful nuance: 'A case name and year around it are fine; only the reporter citation is resolved,' which clarifies acceptable input formats and what will be parsed. This goes beyond the schema and helps agents format calls correctly.

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 ('look up'), a specific resource ('a single case citation in proofread.law's register'), and precisely defines the output: whether a case exists, its details, and register completeness. It explicitly distinguishes from siblings by naming check_citations (for prose) and resolve_citations (for a list), and lists what it cannot do (Westlaw/Lexis IDs, statutes, good-law status). An agent can unambiguously identify when to use this 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?

Explicitly states when to use: 'Use it when one citation is in doubt' and directly names alternatives: 'use check_citations for prose, and resolve_citations for a list.' It also lists exclusions (cannot resolve WL/Lexis, check statutes, etc.), giving clear routing guidance. No inference is required.

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 mark the tool as read-only, idempotent, and open-world, and the description goes further: it explains per-line outcome categories, red/orange row meanings, the open-world caveat, quota counting, and authentication behavior. There is no contradiction with 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?

The purpose is front-loaded and every subsequent clause carries operational meaning: outcomes, caveats, usage split, quota, and auth. Despite its length, the description packs high-density guidance 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 one-parameter lookup tool with a rich but unspecified output, the description covers the return shape, per-row semantics, error interpretation, limits, quota, and authentication. There is no output schema, so this level of detail is necessary and sufficient.

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 documents cites as up to 500 strings, so the baseline is 3. The description adds that these are case citation strings, clarifies that Westlaw or Lexis identifiers cannot be resolved, and ties each entry to a returned line in input order, giving the agent more usable constraints than the schema alone.

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 action ('Look up up to 500 case citation strings') and names the resource (proofread.law's register). It also distinguishes list lookup from check_citations, so an agent can select the right tool without opening 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?

It states exactly when to use the tool ('for a table of authorities or any list of citations you already have') and when to use check_citations instead. It also lists unsupported inputs and quota/API-key conditions, removing ambiguity about 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?

The description goes well beyond annotations by explaining non-idempotency (each call saves a new brief), opt-in saving, encryption, API key requirement, and the precise meaning of red/orange rows. It also lists limitations (cannot resolve WL/Lexis, statutes, etc.) and clarifies red means 'check this', not 'case does not exist'. 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 long but each sentence carries distinct value: purpose, usage, return format, limitations, semantics, opt-in, storage, and auth. It front-loads the core purpose and flows logically. While it could be tightened, the density is justified by 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?

With no output schema, the description thoroughly explains the return values (brief id, coverage statement, tier counts, attention rows with red/orange meaning, report id) and includes auth, storage, opt-in, and limitations. Nothing critical is missing for an agent to call it correctly.

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 fully documents both parameters (100% coverage) with clear descriptions. The tool description adds no additional parameter-level semantics; it focuses on behavior and usage. Baseline 3 is appropriate given the schema's completeness.

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 a specific verb (save), resource (brief to account), and an additional action (check citations). It distinguishes from siblings by explicitly naming check_citations as the alternative for checking without saving, leaving no ambiguity.

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 provides explicit when-to-use instructions: when the user wants to keep a draft or start the edit-and-recheck loop, and when-not: only when saving is desired, with the alternative tool named. It also maps the workflow with update_brief for subsequent edits.

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 only indicate readOnlyHint=false, idempotent=false, destructive=false, but the description discloses key rotation on repeated signup, the 409 on confirmed/paying accounts, session adoption of the key, the need to persist it in PROOFREAD_API_KEY, rate limits, and quota limits. This goes well beyond annotations without contradicting them.

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 carries necessary operational detail—purpose, usage trigger, email requirement, key handling, repeat-call behavior, quotas, and rate limit. Dense but not bloated, with key actions 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?

For a mutation tool with no output schema, it explains the critical outcome (key shown once), error condition (409), post-call persistence steps, and account limits. An agent has everything needed to invoke it correctly and handle the result.

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 100%, so baseline is 3. The description adds real constraints: email must be the account owner's real inbox and placeholder domains are rejected, which is more than the schema's phrasing. Agent_name gets no additional meaning, but overall parameter semantics are enhanced.

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: 'Open a proofread.law account for its owner and get an API key, in one call'. It also names the endpoint and explicitly differentiates from siblings by tying its use to quota ownership and billing_link sequencing.

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 when-to-use: 'when the user wants their own quota instead of the anonymous per-IP free tier, or before billing_link'. It also implies when not to use by describing 409 for confirmed/paying accounts and warns never to send the key elsewhere, giving clear routing and safety guidance.

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 and idempotentHint, so the description correctly doesn't repeat those. It adds rich behavioral detail: the ranked-list output structure, per-row fields (citation, date, field, rank, quoted passage, links), the flag semantics for changed precedents ('a row without a flag is not evidence that its practice still holds'), the language selection rule, and the billing note. 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 every sentence carries a distinct piece of information: scope, input requirement, output structure, caveats, language, and billing. It is front-loaded with the core function and then flows logically through constraints and output details. The length is justified by the tool's complexity, so 4 is appropriate rather than 5 for slight over-brevity in some clauses.

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 tool with four parameters and no output schema, the description is exceptionally complete. It covers the input format, the output fields, the ordering behavior, the language default, the trial-phase key requirement, and the relationship to check_citations. An agent has everything needed to call it correctly and interpret 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that the query must be a statute article (or a paragraph citing one) and that free-text search is not supported, which is not in the schema. It also explains the domain filter keeps order within a field, which is not in the schema. These additions justify a 4.

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-resource pair: 'get the leading Federal Supreme Court cases (BGE/ATF/DTF) the court cites with that article'. It explicitly differentiates from the sibling check_citations by stating that suggestions are not checked against the user's sentence and pointing to check_citations for that. No ambiguity remains about what the tool does.

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 when to use it (you have a Swiss federal statute article) and when not (cantonal law, free-text queries). It explicitly says 'a query without one answers that no article was recognised' and names the alternative tool check_citations for verification. It also notes the trial-phase API-key requirement, which is a practical usage constraint.

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 only state readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds substantial behavior not in annotations: it creates a new version and keeps the previous one, saving is opt-in and encrypted, check counts, red/orange row semantics, and the caveat that 'red row means check this, never this case does not exist'. 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?

Description is long but every sentence earns its place. It front-loads the core purpose and loop, then covers edge cases (recheck, title-only, versions, limitations, red/orange semantics, opt-in saving, encryption, API key). It is densely packed with actionable information and avoids 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?

Given the tool's complexity (4 params, no output schema, many behavioral nuances), the description is remarkably complete. It explains the full workflow, versioning behavior, check counting, limitations, row semantics, saving policy, and security. An agent has everything needed to call it correctly and interpret results despite no output schema.

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 100%, so baseline is 3. The description adds value by clarifying that 'text' must be the whole edited text (not a diff or excerpt), that it replaces the latest version, and that recheck=true re-runs without editing. It also emphasizes sending full text, which the schema doesn't explicitly state. This goes beyond the baseline.

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 ('Save an edited version') and resource ('brief'), and immediately positions it as the loop for fixing flagged citations, distinguishing it from siblings like check_citations and save_brief. It clearly tells the agent what it is for and how it differs from related 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 explicit when-to-use guidance (the loop for fixing flagged citations, repeat until user has reviewed every row), when not to use it (Cannot resolve Westlaw/Lexis identifiers, check statutes/regulations/secondary sources), and when to use recheck. It also distinguishes from save_brief (opt-in saving) and check_citations (never saves).

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