Stipple — Document Verification & Extraction

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

Annotations supply readOnlyHint=true, and the description adds useful behavioral context beyond that: it is free/costs 0 credits, returns a known shape with cached, warrant_id, and permalink, and implies idempotent read-only behavior. It does not fully describe behavior when cache is missed, but that is minor.

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 concise and front-loaded with the key concept 'cheap cache-check,' then states the workflow, return value, and cost in compact, high-signal sentences. 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 single-parameter read-only tool with an output schema, the description covers purpose, usage, cost, hashing instructions, and expected return fields. Nothing essential is missing for an agent to decide whether and how to call it.

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 bears the burden. It compensates by explaining exactly how to derive the sha256 parameter: hash the file using sha256, lowercase hex. This adds meaning beyond the schema's bare string type, though it could more explicitly label it as the document hash.

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 verb and resource: 'Cheap cache-check' to determine if a document has already been inspected. It distinguishes itself from the sibling verify_document by framing this as a pre-check to skip a redundant paid inspection, so an agent can immediately tell the tools apart.

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 when to use: hash the file yourself and 'call this before verify_document to skip a redundant (paid) inspection.' This gives direct workflow context and names the alternative, leaving no ambiguity about the tool's role.

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. The description goes well beyond this, disclosing that each document gets only a cheap page-1 classification, that documents are never stored, that this is coverage checking rather than genuineness/approval, and that it costs 3 credits per call.

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 information-dense without padding. Every section earns its place, key conditions are front-loaded, and formatting uses bullets and bold to aid scanning.

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 sparse schema details, the description fully equips an agent to call the tool correctly: input shapes, alternative usage routes, output structure, behavioral limits, and cost are all covered. 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?

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It thoroughly defines scheme presets, the two formats for requirements, and the two accepted forms of documents, including size limits and field names.

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. It clearly differentiates from siblings by naming verify_document, extract_fields, and verify_identity and explaining what this tool is not for.

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?

Provides explicit 'USE THIS WHEN' guidance and spells out when to use each alternative tool instead. This leaves no ambiguity about selection among the sibling 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?

Beyond the readOnlyHint=true annotation, the description discloses the probability is model confidence, not calibrated truth, warns of false-flagging on templated/coached or non-native-English writing, and explains the abstention behavior (applicable:false) for forms/tables/numeric docs. It also reveals server-side URL fetching and the 1-credit cost — rich behavioral context the annotation alone cannot provide. No contradiction with the annotation.

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 labeled sections (core purpose, USE THIS WHEN, HONEST SCOPE) plus a parameter line and return line make the description highly scannable. Every sentence adds new information — purpose, triggers, parameter semantics, return shape, limitations, alternatives, cost — with zero filler, and the purpose is front-loaded in the first sentence.

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 4 optional parameters with 0% schema coverage and multiple behavioral edge cases, nothing an agent needs to invoke this correctly is missing: purpose, trigger context, both alternative tools, parameter formats, return shape, false-positive limitations, and cost are all present. An agent could select and call this tool accurately without opening any other structured data.

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 bears the full burden and fully compensates: it explains text (pasted markdown/plain prose), url (public http(s) link fetched server-side and noted as the cheapest), bytes_b64 (base64 PDF/file), and filename (for routing). Crucially, it states the document must be provided ONE way — a critical constraint not visible in 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 opening sentence states a specific verb ('Estimate'), a resource (a document's text), and a measurable outcome ('PROBABILITY that it was AI-generated'). The scope is sharpened by example document types (essay, cover letter, article, review), and it distinguishes itself from siblings by explicitly routing non-prose documents to verify_document and verify_references.

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' section names concrete triggering questions ('did an AI / ChatGPT write this? is this human-written?') and input types, giving an agent a strong positive signal for selection. It then gives explicit when-not guidance: non-prose documents return applicable:false and should go to verify_document, and verify_references covers citation checking — exactly the when/when-not/alternatives pattern.

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, which is consistent with the description's statement that 'The document is never stored.' The description goes far beyond annotations by disclosing that extraction is not proof of genuineness, that missing fields go into not_found instead of being guessed, that scans produce bbox:null and grounding:'none', that redaction is best-effort, and that unsupported options cause an explicit error rather than a silent no-op. This is rich behavioral context that structured annotations could 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-organized with clear sections like USE THIS WHEN, COST, CAPABILITY-ONLY, and Returns, and it front-loads the core purpose and routing guidance. It loses a point because the final 'Costs 1 credit(s) PER PAGE read (minimum 1) — cap a long document with max_pages' duplicates the much more detailed COST section earlier, adding avoidable length to an already very long description.

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 — 9 parameters, a fully undocumented schema, a large options object, and many edge cases — the description is remarkably complete. It covers all parameters, all currently supported options, cost calculation, scan versus born-digital behavior, page caps, return shape, and limitations. Even though an output schema exists, the description still explains enough that an agent can predict behavior and choose sensible defaults.

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

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

Schema description coverage is 0%, so the description must compensate, and it does comprehensively. It explains url versus bytes_b64 plus filename routing, the fields parameter with names/objects/types and 'question' alternative, template presets, country as an optional hint, max_pages default/ceiling/cost impact, render_scale allowed values, and the entire options object with sub-options, defaults, costs, and edge cases. An agent can construct a correct invocation with no other source of parameter information.

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 sentence states a specific action and resource: 'Extract structured FIELDS from a document (PDF or image) with a vision model.' It also distinguishes itself from verification and classification by saying 'rather than a yes/no about the document' and explicitly routes 'is this genuine?' to verify_document. An agent can immediately tell what this tool does and what it does not do.

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 has a dedicated 'USE THIS WHEN' section with concrete examples such as a payslip's gross/net, an invoice's total/ABN, form checkboxes, and table cells. It also gives explicit alternatives: 'For "is this genuine?" use verify_document; "what kind of document is this?" is options={"classify": true} right here.' This is exactly the kind of when-to-use versus when-not-to-use guidance an agent needs.

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

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

With only readOnlyHint=true in annotations, the description adds substantial behavioral context: jurisdiction is populated on all rows while location is not, link_is_listing marks portals without per-tender URLs, and coverage explains which sources returned nothing. However, it contains an internal cost contradiction — 'FREE — no credits' versus 'Costs 1 credit(s) per call' — which keeps this from a 5.

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 dense and well-structured: use cases first, then parameter semantics, then return-value caveats. Most sentences earn their place, though the conflicting 'FREE — no credits' and 'Costs 1 credit(s) per call' statements add confusion rather than 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?

The description is highly complete for a read-only search tool: it covers when to use it, what filters mean, data-coverage limitations, empty-result interpretation, and link behavior. Minor gaps remain around source and category parameter semantics, but the output schema and sibling tender_sources tool reduce the practical risk.

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

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

Schema description coverage is 0%, so the description must compensate. It documents jurisdiction values, tier values, and closing_before as an ISO date, and explains why a location filter is deliberately absent. But it does not explain q, source, category, limit, or include_closed semantics, leaving several optional parameters under-specified.

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

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

The description opens with a specific verb and resource: 'Search open government tenders across Australia and New Zealand.' It also distinguishes itself from match_tenders by stating that match_tenders is for ranking opportunities against a specific company, so an agent can tell them apart without inspecting schemas.

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

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

It includes explicit 'USE THIS WHEN' guidance with concrete example queries and names the alternative tool (match_tenders) and the condition that should route to it. It also tells the agent how to phrase empty results ('no match in what we searched' vs 'there are none'), which is actionable.

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 already marks this as a safe read; the description adds meaningful behavioral context: it is free, produces two possible output representations, and describes the bundle contents (every signal that fired, per-page findings, provenance). No destructive or hidden behavior is implied, and 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 description is logically structured and front-loaded with the core action. It is slightly redundant at the end — 'Free — costs 0 credits' repeats the same fact — and the usage block could be tightened, but there is no fluff and every major point 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?

With no output schema, the description compensates by outlining the return format (JSON or Markdown) and the contents of a warrant bundle. It also covers cost, the prerequisite source of warrant_id, and the human-facing report use case. For a simple two-parameter getter, 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?

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It supplies an id format example and clarifies that as_markdown=True produces a human-readable report while the default is the full JSON bundle. This adds real semantic value 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 opens with a specific verb and resource: 'Retrieve a stored warrant by id', and further specifies the id format. It also disambiguates from sibling verification tools by stating this returns the full evidence bundle rather than the summary from the original call.

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 includes an explicit 'USE THIS WHEN' block that states the condition (having a warrant_id from verify_document/check_document) and the goal (need FULL evidence rather than summary). It also gives a concrete instruction for when to set as_markdown=True, which is actionable 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?

The description goes well beyond the readOnlyHint annotation by disclosing that the tool reads the company website, builds a capability profile, costs credits, handles degraded scoring, and interprets `score` as relative fit rather than win probability. However, the cost is stated as both 'Costs 3 credits' and 'Costs 1 credit(s)', which muddies one disclosed behavioral trait.

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 one-sentence summary and is organized into easily parsed usage and caveat sections. However, it is long, and the final duplication of the credit cost ('Costs 1 credit(s) per call.') contradicts the earlier 'Costs 3 credits' and does not earn 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?

The description covers the main use case, input mode, output shape, score interpretation, degraded behavior, and cost. With an output schema present, it is largely complete, but it never states that `company_url` or `example` is effectively required, and it fails to clarify the two optional filter parameters.

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 prose must carry the parameter documentation. It explains `company_url` well — plain domain, resolved by the tool, used for site reading — and describes `example` clearly. But `jurisdiction` and `closing_before` are never given any meaning beyond their names.

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 states a specific verb and resource — 'Rank open tenders against what a company actually does' — with a title that matches. Example queries such as 'find work for acme.com.au' make the tool's purpose unmistakable and distinguish it from generic tender search.

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 marks when to use this tool with 'USE THIS WHEN' and gives concrete query phrasings. It also explains the `example` mode for demos, though it does not explicitly name an alternative tool or state 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.

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

The description goes well beyond the readOnlyHint annotation, disclosing that the tool is stateless, costs credits, returns corroboration-gated sanctions candidates where name-only hits are 'possible, NEVER confirmed', disambiguates media hits, and that results are screening coverage, not a determination. This is rich behavioral context that helps the agent interpret results safely.

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 organized into clear paragraphs: purpose, usage trigger, subject identification, output semantics, and limitations. It front-loads the core purpose and usage, and every section contributes essential detail for a complex KYC/AML screening tool. It loses a point for some repetitive phrasing and typos that slightly reduce polish.

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 has 9 optional parameters, no schema descriptions, and only a readOnlyHint annotation, the description covers everything an agent needs to call it correctly: when to use it, how to identify the subject, what the output contains, and how to interpret hits and non-hits. The output schema exists, but the description still usefully clarifies result semantics.

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 meaningful parameter group: name plus optional disambiguators (dob, country, aliases, employer, role) for sharper matching, and url/bytes_b64 plus filename as the document-based alternative. It also clarifies that no parameters are required and that the two identification paths are mutually exclusive in intent.

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: 'Screen a person or organisation for ADVERSE MEDIA and SANCTIONS/PEP exposure (KYC/AML)'. It clearly differentiates from sibling tools by framing the use case as negative-news and sanctions-list screening, and even notes it 'pairs naturally after verify_identity', distinguishing it from identity 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?

It explicitly states when to use the tool: 'USE THIS WHEN onboarding or due-diligence asks' whether a subject appears in negative news or on sanctions/PEP lists. It also clarifies the two identification modes (name-based vs document-based) but does not explicitly state when not to use it or name a direct alternative tool to pick 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?

Annotations already indicate this is a non-read, idempotent, non-destructive operation. The description adds useful behavioral context beyond that: it costs zero credits, it feeds the engine's learning loop, and it affects future inspections. No contradiction with annotations exists.

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

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

The description is compact and front-loaded, with a clear action clause followed by the usage trigger and a cost note. The 'USE THIS WHEN' section adds practical routing value, and every sentence contributes to correct invocation.

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 three-parameter tool with a required verdict constraint, optional note, and output schema present, the description covers the key behavioral and usage signals. It tells the agent when to invoke the tool, what values to pass, and what effect the call has, so 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?

Schema description coverage is 0%, so the description must compensate. It does so by constraining verdict to 'up' or 'down' and noting that note is optional free text. warrant_id is not described, but its meaning is evident from both the name and the phrase 'a warrant's rating,' making the compensation adequate.

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: 'Record thumbs up/down on a warrant's rating.' It clearly distinguishes the tool from verification and checking siblings by framing it as post-verification feedback, and it explains the rating's role as a precision-flywheel label source.

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 usage context: use when ground truth becomes known after a verify_document call, with concrete examples of genuine or fraudulent outcomes. It does not explicitly list when not to use it or name alternative tools, but the guidance is clear enough to route an agent correctly.

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?

readOnlyHint already covers the safety profile, and the description adds useful behavior context: it is the 'honesty surface,' discloses login-wall and robots.txt limitations, and reports last-run status. However, the description contains a direct contradiction between 'FREE.' and 'Costs 1 credit(s) per call,' which undermines transparency about call cost and could lead the agent to give conflicting information.

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: it opens with a clear summary, gives usage triggers, then details the return contract. It is slightly verbose and includes the cryptic standalone 'FREE.' line, which also conflicts with the later cost statement, but overall every major section 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 zero-parameter, read-only tool, the description is nearly complete: it explains use cases, sources covered, limitations, output shape, and per-source fields. The only gap is the unresolved cost contradiction, which prevents a perfect score.

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, so there is nothing for the description to explain about argument semantics. Schema coverage is effectively 100% with an empty schema. The description instead adds meaning about the return payload, which is appropriate here.

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: 'List tender data sources' and 'Every source we search, what it is allowed to do, and what the last run returned.' It clearly defines the tool's scope and the content of its output. No sibling tool exists for listing sources, so sibling differentiation is unnecessary.

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 says 'USE THIS WHEN' and lists concrete triggers: asking where data comes from, checking whether a portal is covered, or understanding why a search returned empty. This gives an agent clear conditions for selecting this tool, even without naming 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?

Beyond the readOnlyHint annotation, it discloses that this is a SIGNAL not a fraud verdict, that results are cached by content hash, that the call costs credits, and that the returned risk_band is complemented by inspection_quality. These are non-obvious behavioral traits an agent needs before calling.

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 organized with clear sections and front-loaded purpose. Nearly every sentence earns its place, though phrases like 'Both are available in this canonical suite' add little value and some explanation of cache/check_document is dense.

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 complex verification tool with no documented output schema details, it covers input alternatives, exclusions, cost, caching, output headline fields, and the adjudication caveat. It omits how to control the `fresh` flag and does not explain how 'deep mode' is activated, so a small gap remains.

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 explain the parameters, and it does for url, bytes_b64, and filename: it distinguishes server-side fetching from inline base64 and explains filename's routng role. However, the `fresh` boolean parameter is never mentioned, leaving one of four parameters unexplained.

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

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

The description names a specific verb and resource: 'Forensically inspect a document (PDF or image) for authenticity.' It enumerates concrete check types (tampering, AI-generation, arithmetic reconciliation, provenance) and distinguishes itself from siblings by naming detect_ai_text and verify_references for adjacent tasks.

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?

'USE THIS WHEN' states exact triggering scenarios (payslip, bank statement, invoice, etc. with questions about genuineness), and gives explicit exclusions: 'For did an AI *write* this prose use detect_ai_text; for are this report's citations real use verify_references.' This is model rounting 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 only show readOnlyHint=true, so the description carries the burden of explaining behavior. It discloses the vision-model reading step, deterministic tallying, what the result contains, that documents are never stored, that it is identity coverage rather than forgery judgment, and the credit cost. This is rich additive context well beyond 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 description is structured with clear sections: when to use, parameter formats, return shape, limitations, and cost. Every sentence adds value, and backticked fields keep references to parameters readable. The length is justified by low schema coverage and 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?

Together with the output schema, the description covers purpose, selection criteria, all input formats, scheme options, expected output fields, caveats, privacy, and credit cost. There is no missing piece needed for an agent to correctly select and invoke this tool.

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

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

Input schema description coverage is 0%, but the description fully compensates by documenting that `documents` accepts either public URLs or byte_base64 with filename, supports up to 10 items, and by enumerating the exact `scheme` values plus default. This gives the agent everything needed to construct valid arguments.

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: running an Australian identity check over a set of identity documents, tallying them against a scheme. It also distinguishes itself from authenticity checks by explicitly pointing to verify_document, which differentiates it from sibling 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?

Provides an explicit 'USE THIS WHEN' section covering KYC/onboarding and 100-point check scenarios, and instructs the agent to pass all documents together. It also names the alternative tool for authenticity verification, so the agent knows when not to use this tool.

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

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

With only readOnlyHint=true, the description carries behavioral weight: default provenance/citation-resolution/math checks, deep mode behavior, server-side fetching, honest boundary that it reports coverage not truth, and that it never affects the fraud risk band. 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?

Long but appropriately structured: what/why, when to use, one-document-three-ways input, default vs deep behavior, output, boundaries, cost. It is front-loaded and no sentence 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?

Covers input modes, selection tradeoffs, default and deep behaviors, returned artifacts, limitations, and cost; output schema exists so return details don't need full enumeration. An agent has everything needed to decide and call 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 0%, and the description compensates by explaining url (public link, server-fetched, cheapest), text (pasted markdown/plain prose), bytes_b64 (base64 PDF), and deep (fetch sources to judge support/contradiction). Only filename is left implicit, but its default makes that acceptable.

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 verb+resource: fact-check a document's REFERENCES and CLAIMS, specifically built for AI-generated reports. The phrase 'citations must be checked before they're trusted' distinguishes it from generic document tools like verify_document or check_document by scoping it to citation/reference 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?

Provides explicit trigger conditions: use when someone shares a report/link and asks about accuracy or citation legitimacy, plus proactively before relying on AI-written content. It doesn't name specific alternatives or list when-not cases, so it stops short of fully routing among siblings.

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