Claim Done

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

Annotations already declare non-readOnly, idempotent, non-destructive, closed-world, so the mutation profile is known. The description adds genuinely new behavior: it returns remaining open questions (making it a progress probe, not just a writer) and reports ready_for_protected_draft only for eligible ordinary documents, with no charge before payment. Missing only what happens on invalid keys or partial saves.

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 sentences, front-loaded with the write action before the return-value and pricing nuance. The second sentence is clause-heavy (open questions + eligibility + $0 + payment ordering) but every clause carries information 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?

There is no output schema, so the description carries the return-value burden and does so at a high level: open questions plus a ready_for_protected_draft boolean. For a 3-param, nested-answers write tool that is close to sufficient; only the shape of the returned open-questions collection and error behavior remain unstated.

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% and the answers property already documents 'Question key => the person's answer' and the one-choice rule, so the description's parenthetical restates rather than extends it. case_id and access_token provenance from start_document is likewise already in the schema. Baseline 3 applies.

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

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

States a specific action and resource: saves the person's answers, keyed by question key, scoped to a case. An agent can tell this is the answer-submission step of a document workflow, though it never names a sibling it is not (e.g. prepare_protected_draft) and uses 'case' where the title says 'document', leaving a small naming seam.

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 second sentence implies the loop (submit answers, receive still-open questions, repeat until ready_for_protected_draft appears) and mentions a $0 pre-payment draft gate, which nudges the agent toward when to call it. But there is no explicit when-not or alternative — nothing says what to do instead when questions remain unanswered or when the case is already paid.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds genuinely non-obvious behavior: a payment gate, watermarked raster pages before payment, and that raw text is never returned pre-payment. That is meaningful disclosure beyond the structured fields, though it doesn't address rate limits or error/auth failure modes.

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 sentences with no wasted words; the payment precondition is front-loaded and the negative constraint (raw text never returned) is a useful closing qualifier. The parenthetical phrasing ('and, for eligible letters, has it sent') is slightly convoluted but still compact.

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 correctly carries the return-value burden by naming the full text and dashboard link. It explains the gating behavior that determines whether anything usable comes back, leaving only minor gaps around failure responses.

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 both case_id and access_token are already documented as values returned by start_document. The description adds no additional syntax, format, or coupling detail for either parameter, which is the expected baseline when the schema does the work.

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 outcome (the full text of each drafted document plus the dashboard approval link) tied to a clear resource, so an agent knows this reads drafted output rather than metadata. It does not explicitly contrast itself with the closest siblings (prepare_protected_draft, start_document), so it falls short of a 5.

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 a hard precondition — 'After genuine payment only' — which is real when-to-use guidance, and implies the pre-payment state is a when-not-to-use case. It stops short of naming an alternative tool for the pre-payment situation, so no explicit routing is provided.

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 declare readOnlyHint=false and idempotentHint=true, and the description adds real behavioral context beyond them: what payment unlocks (clean PDF, download and delivery options) and the acknowledge_notice sequencing requirement. It never states idempotency itself, but the annotation covers that.

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

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

Front-loaded with the return value, then prerequisites, then the notices caveat. Dense but every sentence carries information; no obvious filler. The middle clauses are slightly clause-heavy but not wasteful.

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 gated mutation tool with no output schema, it covers the return value, the gating prerequisites, the alternate flow, and the notice edge case. Remaining gaps (expiry, error shapes) are minor and largely outside the tool's core contract.

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 the baseline is 3, but the description goes further by tying acknowledge_notice to the eligibility-notice flow and hinting at delivery options (registered_post). This adds flow meaning on top of the already-documented fields.

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 and resource: it returns a hosted Stripe Checkout URL at the live flat price. That is concrete and distinct from the read-oriented siblings (get_document, get_status), though it never explicitly contrasts itself with a named alternative.

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 clearly lays out preconditions: the protected draft must be ready and the private review accepted, with a documented exception for report/workspace flows. It stops short of naming any sibling as an alternative, so it is strong context without explicit 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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: it discloses the exact result categories and a deliberate access boundary ('never returns raw unpaid document text'), which tells the agent what it will and will not get back.

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 sentences with no filler, but the first is a run-on list of 'whether...' clauses that is not front-loaded with a purpose statement, so the reader must assemble the tool's role from the enumeration rather than a leading verb. Compact but weakly structured.

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 correctly takes on the burden of describing return values and does so across the four status categories, plus the privacy caveat. For a simple two-parameter read it is nearly complete; only failure/error behavior (e.g., invalid or expired token) is unaddressed.

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% and both parameters (case_id, access_token) are documented in the schema as coming from start_document, so the schema carries the load. The description adds no parameter-level meaning such as format, validation, or token expiry, so the baseline 3 applies.

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 enumerates exactly what status information the tool surfaces (payment state, protected-draft processing state, review acceptance, dashboard link), which lets an agent distinguish it from get_payment_link (returns a link, not a paid/unpaid flag) and prepare_protected_draft (triggers the draft, this reports on it). It stops short of a clean verb+resource statement like 'Returns the status of a case', reading instead as a fragment list, so it is clear but not exemplary.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The agent can infer this is a polling/status check after start_document, but that sequencing and any exclusion of get_document is left entirely to inference.

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, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered. The description adds marginal context — prices are 'live' and denominated in AUD — but says nothing about ordering, pagination, or result size.

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?

A single economical sentence that front-loads the resource and immediately lists the returned fields. It is a fragment without a verb, but nothing is padded or redundant.

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 partially compensates by naming the fields each entry carries (price, deliverables, delivery). However it omits result count, ordering, and whether the optional query filter narrows the list, leaving an agent to guess at basic list behavior.

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% and the single optional 'query' filter is documented in the schema with examples, so the baseline of 3 applies. The description adds no filter syntax or matching behavior beyond what the schema already provides.

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

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

The description restates the title ('Every document Claim Done drafts') and notes what each entry carries — price, deliverables, delivery method — but never states a verb or says it returns a list. The mismatch between the name 'list_services' and the title's 'documents' is left unresolved, and no sibling (get_document, match_problem) is distinguished.

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?

There is no when-to-use guidance, no exclusions, and no pointer to alternatives such as get_document for fetching a single document. The agent must infer usage purely from the name and annotations.

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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds real value beyond that by disclosing what comes back (the matching document, its price in AUD, and what it does) and what the input should contain (who, what happened, what they want). It stops short of covering no-match behavior or match confidence.

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?

A single sentence that front-loads the input and then the return payload, with no filler. Slightly dense due to the parenthetical, but every clause carries 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?

With no output schema, the description does the work of describing the return payload (document, AUD price, description), and with only one well-documented parameter the input side is covered. A minor gap remains around failure/no-match behavior for a matching 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?

Schema coverage is 100% and the schema already documents the 10-500 character limit, so the baseline is 3. The description's '(who, what happened, what they want)' is a helpful structuring hint but largely restates the schema's 'situation in the person's own words'.

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 (takes a plain-English problem, returns the matching document) and resource (Claim Done document). An agent can tell this is a semantic matcher rather than a lookup. It never names or contrasts with siblings like get_document or list_services, which is the only missing piece.

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?

Usage is implied by the input format: use this when you have a free-text problem description rather than a known document name. There is no explicit when-not guidance and no alternative tool is named, so the agent must infer that get_document is for known IDs and list_services for browsing.

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 (not read-only, idempotent, non-destructive), the description adds material behavior: the draft costs $0, the return is a private dashboard link with authorised watermarked raster pages, raw unpaid text and original PDF/DOCX are never returned, and daily/email/network limits apply. That is rich context the structured fields do not carry.

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?

Four tight sentences lead with the purpose/precondition and then cover cost, output, and limits without padding. Slightly dense and the data-handling sentence is long, but every clause carries information 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 correctly explains what comes back (the private dashboard link and watermarked raster pages), what is withheld (raw text and original files), and the preconditions and limits. Nothing essential for invoking it correctly appears to be 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%, and both parameters are documented as coming from start_document, so the schema already does the work. The description adds no syntax, format, or usage nuance for case_id or access_token, making the baseline of 3 appropriate.

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 pairs a specific verb ('starts the real draft') with a clear resource ('protected draft') and scopes it with the precondition 'eligible ordinary document whose questions are complete'. That locates the tool in the flow relative to answer_questions and get_payment_link, but no sibling is named or explicitly excluded, so it falls short of full differentiation.

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 when the tool is applicable ('for an eligible ordinary document whose questions are complete') and the title reinforces the pre-payment timing. However, it names no alternative tools or failure cases, so the agent must infer what to do when the document is ineligible.

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 establish that this is a non-read-only, non-destructive, non-idempotent write. The description adds genuinely new context beyond them: 'Nothing is charged at this step' clarifies billing behavior, and it discloses the artifacts returned (case_id, access_token) needed for subsequent calls. It stops short of warning that repeated calls create duplicate cases.

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 sentences with zero filler; the creation action and its outputs are front-loaded and the billing reassurance follows immediately.

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 correctly carries the return-value burden by naming the questions, case_id, and access_token. It could go one step further and name answer_questions as the next call, but it is otherwise sufficient for an agent to invoke this 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 description coverage is 100% and each of the five parameters is documented, including the enum for 'state'. The description adds no format, syntax, or constraint detail beyond the schema, so the baseline of 3 applies.

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 ('Creates a Claim Done case for a document') and names what is produced (questions, case_id, access_token). It is clearly distinguishable from siblings like get_document or answer_questions, though it does not explicitly contrast itself with 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?

Usage is only implied: the mention of 'the later steps' and the returned access_token signals this is the entry point of a multi-step flow. There is no explicit when-to-use guidance and no pointer to the prerequisite siblings (list_services / match_problem) that produce the required 'service' slug, even though the schema hints at it.

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