Stipple — Document Verification & Extraction

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

Annotations provide readOnlyHint=true, so safety coverage is already present. The description adds useful behavioral context beyond that: it is a cheap cache check, it requires the caller to hash the file first, and it returns a structured result containing cached status, warrant_id, and permalink. It does not describe edge cases or failure behavior, but for a simple read-only check that is sufficient.

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 tight sentences with no filler. The core purpose is front-loaded ('Cheap cache-check'), followed by the essential workflow note and return payload. Every sentence adds 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?

For a one-parameter read-only check, the description covers what the tool does, when to call it, how to compute the input, and what it returns. The presence of an output schema means return details need not be fully spelled out, but they are included anyway, so 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 schema only defines a string named sha256 with no description, so the description carries the full burden. It specifies the exact hashing algorithm and format (sha256, lowercase hex) and explains that the hash identifies the exact document, making the parameter unambiguous.

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 precise predicate: whether a specific document, identified by its SHA-256 hash, has already been inspected and cached. This is distinct from verify_document, which actually performs the inspection, and from sibling tools like check_pack or check_source_overlap.

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 instructs the agent to call this before verify_document to avoid a redundant paid inspection, naming the sibling alternative and the condition that should trigger the call. Also tells the agent to compute the SHA-256 hash itself, which is essential for correct use.

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 provide readOnlyHint=true, and the description adds complementary context: documents are never stored, classification is a cheap page-1 read only, and the tool checks type coverage not authenticity or approval. This goes well beyond the annotation and manages agent expectations about side effects and output semantics.

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 a clear purpose, then organized into short labeled segments ('USE THIS WHEN', 'Define the checklist ONE of two ways:', 'Returns...'). Every sentence conveys necessary information without redundancy. The length is justified by the zero-coverage schema.

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 3 parameters, 0% schema coverage, no parameter enums, and an output schema, the description is complete: covers input formats, limits (12 docs), checklist definitions, alternatives, and return semantics. It also clarifies exclusions (not authenticity check, not approval). Nothing an agent needs to invoke it correctly 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 0%, so the description carries full responsibility for parameter meaning. It thoroughly explains scheme presets (with example names), requirements ad-hoc forms (strings or objects with key/accepts/optional), and the documents list (up to 12, with url or bytes_b64+filename formats, including URL fetching behavior).

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 whether a SET of documents satisfies a checklist — completeness, cheaply.' It clearly distinguishes this tool from siblings by explicitly naming alternatives for other use cases (verify_document, extract_fields, verify_identity), so an agent can tell which tool fits.

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 includes an explicit 'USE THIS WHEN' condition with a concrete scenario ('application / onboarding pack') and the exact question the tool answers ('do we have the required documents, and what's still missing?'). It also gives when-not-to-use guidance and names alternative tools for different intents.

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 far beyond the readOnlyHint annotation by disclosing the two-tier evidence system (matches vs possible_paraphrases), the fact that paraphrases are model judgements and never quotes, the cap on overlap band for paraphrase-only results, the capped query limits, the exclusion of the fetched page and host from matches, and the explicit statement that plagiarism is a judgement the tool never makes. This is rich behavioral disclosure that prevents misuse.

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-organized: purpose first, then input modes, then output tiers, then honest scope. Every sentence earns its place. It loses one point for length — the honest-scope section could be tightened slightly — but the structure is logical and front-loaded with the most critical information.

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, 0% schema coverage, output schema present, 13 siblings), the description is remarkably complete. It covers input constraints, output structure, evidence reliability, limitations, language support, and cost implications. The output schema exists to explain return values, so the description's focus on behavior and constraints is exactly right.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains the semantics of text, url, and bytes_b64 (including that url is fetched server-side and excluded from matches, and that bytes_b64 needs filename for routing). The only minor gap is that filename's default and role are only partially explained, but the core parameter semantics are well covered.

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 ('Check whether text OVERLAPS text published on the public web') and immediately frames it as a plagiarism-style check with concrete questions ('does this text appear elsewhere? was this copied? find the source of this text'). It clearly distinguishes itself from siblings like detect_ai_text and verify_document by focusing on source overlap rather than authorship or document verification.

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 explicitly states the three mutually exclusive input modes ('Provide the document ONE way: text, url, or bytes_b64'), which is critical usage guidance. It also gives clear when-not-to-use context: 'not an academic-database check', 'absence of matches is never an originality certificate', 'English-language prose only; non-prose and unsupported languages abstain'. This is exemplary routing and exclusion 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?

Beyond the readOnlyHint annotation, the description discloses that the probability is the model's confidence, not calibrated truth, that false-flagging can occur, that non-prose documents return applicable: false and abstain, and that URL fetching is server-side. This is substantial behavioral context that annotations alone do not provide.

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 well-structured with clear sections: core definition, usage trigger, input modes, return shape, and honest limitations. Every sentence adds actionable information, and the key scoping and usage details 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?

The description covers input modalities, expected output fields, abstention behavior, limitations, and alternative tools for out-of-scope inputs. Despite the presence of an output schema, it still summarizes the return object, and no critical calling context 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?

With 0% schema description coverage, the description fully compensates by explaining each input mode: text for pasted prose, url for server-fetched public links/PDFs, and bytes_b64 plus filename for base64 files. It also clarifies that exactly one document input should be provided, which is essential for correct invocation.

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 precise verb and resource: 'Estimate the PROBABILITY that a document's text was AI-GENERATED (LLM-written prose).' It clearly defines the tool's scope and differentiates it from related tools by naming verify_document and verify_references for non-prose cases.

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?

Explicit 'USE THIS WHEN' guidance covers the exact scenario: someone shares prose and asks whether it was AI-written. It also provides explicit exclusion criteria (forms, tables, numeric documents) and names alternative tools for those cases, making selection unambiguous.

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?

Discloses far beyond the single readOnlyHint annotation: the full credit model ('1 credit per page read, minimum 1... Pages charged is min(max_pages, the document's real length), resolved before the call runs'), error semantics ('asking for one that this server does not support is an ERROR naming it — never a silent no-op'), abstention behavior (not_found), non-verification ('values are what the document SHOWS, not proof it is genuine'), per-option caveats (redact is best-effort and a second model pass; grounding is born-digital-only), and 'The document is never stored.' No contradiction with readOnlyHint.

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?

Well front-loaded: purpose and when-to-use precede parameters, and it is organized into scannable sections (input, options, COST, returns, caveats). It is long (~700 words), but that length is largely earned by 9 parameters, 10 options, and a cost model; minor redundancy between per-option cost notes and the dedicated COST section 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?

For a very high-complexity tool with a bare schema, minimal annotations, and an output schema, the description covers input selection, output shape (mode, fields, not_found, pages_read), cost prediction, error behavior, and edge cases (AUTO mode, unrecognised types, capability-only calls, both url and bytes_b64). It even points to GET /v1/extract/capabilities for the machine-readable capability list.

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% — the schema supplies only types and defaults — so the description must compensate fully, and it does: fields is explained in three shapes including the type enum and the 'question' alias, template lists concrete presets ('payslip', 'tax_invoice', 'bank_statement', 'receipt'), url vs bytes_b64 carries routing and cost implications, max_pages has 'default a few; hard ceiling 10', render_scale is fully enumerated, and every option's sub-parameters are 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?

Opens with a specific verb+resource+method: 'Extract structured FIELDS from a document (PDF or image) with a vision model.' It explicitly differentiates from siblings — 'For "is this genuine?" use verify_document' — and routes classification to an option here rather than a separate tool. An agent can tell this apart from every sibling without reading a schema.

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

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

Gives an explicit trigger with concrete examples: 'USE THIS WHEN you need specific values OUT of a document — a payslip's gross/net, an invoice's total/ABN... rather than a yes/no about the document.' It names the alternative (verify_document), states that classification is handled via options.classify, and explains the capability-only modes that replace the retired classify_document and redact_pii tools.

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?

Description reveals two distinct output modes (full JSON bundle vs human-readable Markdown) and enumerates bundle contents (every signal, per-page findings, provenance). Annotations already mark readOnlyHint=trueahan, with no contradiction. It doesn't cover errors/limits, but for a read-only getter 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?

Two tight sections: first sentence states action and output variants, second block gives concrete usage trigger and distinguishes from the summary the original call returned. No redundant text.

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 simple read-by-id tool with two params incl. one boolean, the description covers input source, id format, output formats and intent. No output schema exists, but return content is described. Minor gaps: no explicit error cases or auth, and 'when not to use' is only implicit.

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

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

Schema coverage is 0%, so the description must carry parameter explanation. warrant_id comes from earlier verify/check calls and has format warrant_<hex>; as_markdown switches the output format. Both parameters are fully 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?

Description states a specific verb ('Retrieve'), resource ('stored warrant'), parameter (warrant_id), and adds scope (full evidence bundle vs. summary). It clearly differentiates from sibling tools like verify_document and check_document, which produce warrants rather than retrieve 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?

Explicitly says 'USE THIS WHEN you have a warrant_id from an earlier verify_document / check_document call and need the FULL evidence—rather than the summary'. Names the origin of the ID and the use case for as_markdown=True. This gives an agent clear selection criteria versus 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?

Beyond the readOnlyHint annotation, the description discloses key behavioral traits: statelessness ('Stateless — nothing is stored'), corroboration-gating for sanctions hits ('a name-only hit is `possible`, NEVER confirmed'), entity disambiguation for media, and the interpretive caveat that a hit means 'review this', not 'guilty'. This is rich, non-obvious context that materially affects how an agent should use the results.

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 it is organized into clear functional sections: purpose, when to use, identification methods, and result interpretation. Every sentence carries substantive guidance or a caveat; nothing is 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?

Despite having an output schema, the description adds valuable interpretation of the return shape and its limitations, such as corroboration-gating, `excluded` same-name articles, and the non-determinative nature of screening. For a tool with 9 optional parameters and dual identification modes, the description covers the key decision points an agent needs.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains all 9 parameters: the name-based identification path with 'dob', 'country', 'aliases', 'employer', and 'role' as matching sharpeners, and the document-based path via 'url'/'bytes_b64' plus 'filename'. It also adds format guidance ('dob as YYYY-MM-DD') and explains the matching benefits.

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 ('Screen') and a clear resource (person or organisation) for 'ADVERSE MEDIA and SANCTIONS exposure (KYC/AML)'. It also explicitly states what is NOT included (PEP lists), distinguishing the tool's scope from a generic screening 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 THIS WHEN onboarding or due-diligence asks: does this subject appear in negative news... or on a sanctions list?' and notes it 'Pairs naturally after verify_identity'. It does not explicitly name alternatives or say when not to use it, but the context is clear enough for correct 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so no contradiction. The description adds behavioral context beyond annotations — this is the precision-flywheel label source and feedback sharpens future inspections for everyone — which helps an agent understand downstream effects.

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 tightly written paragraphs with no filler. The first gives function and constraints; the second gives the when-to-use context. Every sentence earns its place.

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

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

For a 3-parameter, 2-required feedback tool with an output schema and informative annotations, the description is close to complete. The only minor gaps are side effects like batching or timing of learning, but these are not required for a correct call.

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

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

Schema description coverage is 0%, so the description must carry the semantic burden; it does. It tells the agent verdict must be 'up' or 'down', note is optional free text, and warrant_id refers to the warrant whose rating is being labeled. Without this description, the agent would have no way to know the only valid verdict values.

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 ('Record thumbs up/down') on a specific resource ('a warrant's rating') and ties it to the engine's precision-flywheel label source. This distinguishes it from siblings like verify_document, which performs verification rather than outcome feedback.

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 an explicit trigger condition ('when the ground truth became known after a verify_document call'), concrete examples ('later confirmed genuine or fraudulent'), and the reason to use it ('so the engine learns from the outcome'). The when-to-use guidance is unambiguous.

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 provide `readOnlyHint`, yet the description voluntarily discloses server-side fetching, content-hash caching, the 'signal not a fraud verdict' limitation, and a downstream `get_warrant` path for full evidence. It meaningfully expands beyond annotations and is consistent with readOnlyHint.

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 clearly structured with purpose, when-to-use, input mechanisms, and output semantics, and it front-loads the most load-critical information. It is longer than minimal but uses that length for operational nuance such as caching and cost guidance, so the length is justified.

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, the description covers purpose, triggers, bypass path, document input choice, output semantics, and next-step evidence retrieval. The only notable completeness gap is the undocumented `fresh` parameter, but the description still gives strong guidance for an agent to invoke and trust the call.

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

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

With 0% schema description coverage, the description provides real value by explaining `url` as a server-side-fetched http(s) link and `bytes_b64` plus `filename` as the inline-base64 route with PDF-vs-image routing. It omits `fresh` entirely, which is a minor but real gap given that parameter is otherwise undocumented.

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

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

The description leads with a specific verb and resource: 'Forensically inspect a document (PDF or image) for authenticity', and enumerates concrete checks like tampering signs, AI-generation indicators, and provenance. It also differentiates from siblings by naming `detect_ai_text` and `verify_references` as the tools for other question types, so an agent can disambiguate 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 'USE THIS WHEN' block gives concrete document types and user questions, making the trigger condition explicit. It also states when not to use it by pointing to `detect_ai_text` and `verify_references`, and it tells the agent to use `check_document` first to skip a redundant, paid inspection.

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 declare readOnlyHint=true, meaning no mutation. The description goes beyond that by disclosing that documents are never stored, which is critical privacy context. It also reveals the deterministic engine behavior and that it returns a structured coverage result. However, it doesn't explicitly state whether the vision model introduces variable latency or potential failures, but that is minor given the strong context.

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 well-structured with a clear opening paragraph on the method, a 'USE THIS WHEN' section for usage, and inline parameter explanations. Every sentence provides value, and the critical distinction (coverage vs. forgery) is front-loaded. It is verbose but appropriately so for a complex 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 the purpose, usage, parameters, output structure, and privacy implications. It also routes to siblings when neededcars. Although an output schema exists, the description goes beyond by explaining semantics of the return fields (e.g., whether documents counted and why-not), which is rich enough for an agent to use the results effectively.

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 fully compensate. It does: `documents` is described as a list of one of two forms (url or bytes_b64+filename) with exampleslor and a limit of 10. `scheme` is explained with its two possible values and defaults, and each is defined. This adds substantial meaning beyond the bare 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 clearly states a specific verb 'verify' and resource 'Australian identity check' over documents, and distinguishes it from siblings like verify_document and check_document by explaining it tallies documents against a scheme for coverage, not forgery. It also clarifies what it does not do, which helps an agent differentiate it immediately.

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: for KYC/onboarding and 100-point check queries, and when not to: it is not a forgery judgment, so use verify_document for authenticity. It also gives practical guidance to pass all documents together and explains the 100-point threshold, which is essential for correct invocation.

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 readOnlyHint annotation is present, and the description adds substantial behavior beyond it: server-side fetching, the three default checks (provenance, citation resolution against arXiv/Crossref, internal math recomputation), the deep=true mode with a time estimate (~a minute), the return shape (trust summary, per-item tables, permalink), and an explicit 'HONEST BOUNDARY' disclaiming that it reports coverage, not truth. This is model-level transparency.

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?

Despite its length, every sentence earns its place: purpose, usage triggers, input modes with tradeoffs, default-vs-deep behavior, returns, and limitations are each in their own paragraph with helpful flags like 'USE THIS WHEN' and 'HONEST BOUNDARY'. The description is front-loaded with purpose and contains no filler or repetition of the schema.

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 complexity (five parameters, three mutually exclusive input modes, no required params, zero schema coverage), the description is remarkably complete: it explains the mutual-exclusivity constraint, the deep-mode toggle, time cost, outputs, and interpretatin caveats. The output schema exists, so return values need not be spelled out. The only substantive gap is the undocumented filename parameter and the absence of any error-mode notes (e.g., failed URL fetch or malformed PDF).

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

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

Schema description coverage is 0%, so the description carries the full burden, and it compensates well: url (public HTTP(S), text (pasted markdown/plain prose), bytes_b64 (base64 PDF with exact link-annotation URLs), and deep (default fast vs fetch-each-source mode) are all given meaningful semantics, including cost tradeoffs. However, the filename parameter is never mentioned anywhere in the description or schema, leaving one of five parameters undocumented.

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

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

The opening line, 'Fact-check a document's REFERENCES and CLAIMS — built for AI-generated reports whose citations must be checked before they're trusted,' states a specific verb (fact-check), a specific resource (references and claims), and the target use case. There are no sibling tools to differentiate from, and the title 'Verify a report's citations' is reinforced rather than merely restated.

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 includes an explicit 'USE THIS WHEN' block with concrete trigger scenarios and example user questions ('is this accurate / legit?', 'did the AI make this up?'), plus proactive guidance ('use it proactively before relying on any AI-written document'). It also routes input selection by explaining when to choose url vs text vs bytes_b64, so an agent knows how to invoke it correctly.

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