PaperPorter

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

Annotations only declare the generic safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false); the description adds real behavioral context the annotations cannot convey — the draft is pinned to the form's current reviewed version and is immune to later template edits, it is visible only to the signed-in user, and it returns application_id plus a revision.

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 sentences, zero filler, and the ordering is deliberate: what it creates, its pinning/privacy semantics, the return value and next call, then the when-not condition last as the deciding constraint.

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?

Even without an output schema the description explains what comes back (application_id and revision), how the draft behaves over time, who can see it, and which tool to call next. Nothing needed to invoke or sequence 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?

There is a single parameter with 100% schema description coverage ('Template ID (UUID) from a search_forms result'), which already documents source and format. The description adds no further parameter meaning, so the baseline 3 for high coverage 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 ('Start a private draft for one form so answers can be saved') and immediately names the sibling that continues the workflow (update_application). An agent can distinguish this from get_application, search_forms, or validate_application without opening any 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 when-not: 'Create it only when the user wants to fill the form, not just to read its questions.' It also names the alternative/next step (update_application with the user's answers), so routing is fully determined.

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 flag destructiveHint=true and idempotentHint=true, but the description adds what the annotations cannot: that the deletion is irreversible ('This cannot be undone') and that it cascades to all generated PDFs. That cascade scope is the key behavioral fact an agent needs before invoking.

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 short sentences, front-loaded with the destructive scope and consequence before the usage guard. Every sentence carries a distinct, necessary piece of 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?

For a single-parameter destructive tool with no output schema, the description covers the effect, the cascade, irreversibility, and the invocation precondition. Nothing an agent needs to call it safely 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 a single parameter at 100% schema coverage, the schema already documents application_id fully, including its UUID format and origin from create_application. The description refers to 'that draft' only implicitly and adds no format or sourcing detail beyond the schema, 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?

States a specific verb (permanently delete), the resource (a user's draft/application), and the cascade scope ('every PDF generated from it'). This distinguishes it from siblings like update_application or get_pdf_download without needing the schema.

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

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

Gives an explicit gating condition: 'Only call it when the user explicitly asks to delete that draft,' which functions as a when-not rule, and adds a required confirmation step ('confirm which one first'). No alternative delete tool exists among the siblings, so there is nothing further to disambiguate.

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?

Adds substantial behavior beyond the annotations: signatures are never filled, nothing is submitted to any agency, generation is refused if the revision changed, and it returns an artifact_id. These are side-effect and safety facts an agent cannot derive from readOnlyHint=false/destructiveHint=false alone.

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 dense sentences, each carrying distinct information (action, precondition, side-effect boundary, return/next-step), with the core action and the confirmation gate both front-loaded. No filler or restatement of the title.

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?

Although there is no output schema, the description supplies the return value (artifact_id) and the follow-up tool, and covers the mutation's boundaries (no signatures, no submission, revision mismatch refusal). Nothing needed to call 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 coverage is 100%, so parameters are already documented (baseline 3). The description nonetheless enriches the semantics meaningfully by pinning reviewed_revision to 'the exact revision reviewed' and clarifying that question completion is not the same as confirmation, which goes beyond the schema's terse 'Must be true' text.

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+resource+output ('Fill the official PDF in its original layout') and its input source ('from a validated draft'), which cleanly separates it from validate_application (which only checks) and get_pdf_download (which only yields a link). An agent can tell what this produces without reading the schema.

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

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

Explicit precondition — call only after showing every answer and getting explicit confirmation of that exact revision — plus an explicit non-condition ('finishing the questions is not confirmation'). It also routes the agent forward by naming get_pdf_download as the next step for obtaining a link.

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 genuine context beyond that: the response carries validation issues and still-unanswered questions, and the revision number is a required input for update_application and generate_filled_pdf — a real cross-tool constraint not visible in the schema.

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, zero filler. The payload contents are front-loaded and the usage clause follows, so an agent gets the what before the when.

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?

No output schema exists, but the description compensates by enumerating the returned fields (answers, revision number, validation issues, unanswered questions). Combined with annotations covering the safety profile and a fully documented single parameter, nothing needed to call this 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 100% and the single application_id parameter is already documented as a UUID returned by create_application. The description adds no syntax or format 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 (read) and resource (saved draft/application), then enumerates exactly what comes back: current answers, revision number, validation issues, and unanswered applicable questions. This is clearly distinguishable from create_application, update_application, and validate_application.

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 two concrete use cases: resume a draft, or display all answers before confirming generation. It also names the downstream consumers of the returned revision number (update_application, generate_filled_pdf), which routes the agent effectively. No explicit 'when not to use' or named alternative read path, so not a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious operational context the annotations cannot convey: multi-minute latency, that polling is wasteful, and that a human review step follows. It does not cover error/not-found behavior or how long results remain retrievable, keeping it short of 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?

Two sentences, zero filler, and the useful constraints (call once, no polling) are front-loaded right after the purpose statement. Every clause 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 carries the return-value burden and does name the returned fields (stage, passes, final status), plus the timing expectation an agent needs to interpret those values. Nothing required to invoke or interpret the call 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 100% and the single job_id parameter is fully documented in the schema, including UUID format and origin. The description reinforces the link to start_conversion but adds no syntax or format detail beyond the schema, 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?

States a specific verb (Get) and resource (PDF conversion status), and enumerates exactly what is returned: stage, completed passes, final status. It ties the resource to the sibling that created it (start_conversion), so an agent can distinguish this status-lookup from the other form/application 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?

Explicitly states when to call (once, when the user asks for progress) and when not to (do not poll in a loop), with the reason given (conversion takes a few minutes; new templates need human review). This is a rare case of a tool actively steering the agent away from a plausible misuse.

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 annotations already covering read-only/idempotent safety, the description goes further and enumerates the actual response payload (questions with id, label, type, choices, required, conditions/shown_when, approx_max_chars; plus sections, provenance with source_url, limitations, and blank/sample PDF links) and the paging model. This is exactly the behavioral context needed since there is no output schema.

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 purpose, then the return shape, then paging, then the read-only guarantee. Dense but every sentence carries information; the field enumeration is long but justified given there is no output 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?

A read tool with no output schema, yet the description fully covers the return structure, paging behavior, the opt-in heavy 'include_mapping' debug flag implications, and the safety profile. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'section' is tied to the sections list of a previous response and offset/limit are framed as the paging mechanism. It adds context on how parameters interact across calls rather than restating types.

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+resource ('Read a form's questions') plus the scope and the goal it serves ('before collecting answers or creating an application'). It is clearly separable from siblings like search_forms (discovery) and update_application (the writer of answers).

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 clear usage context (call before collecting answers or creating an application) and names the downstream tool that consumes the returned ids ('the answer key for update_application'). It also explains the paging procedure (read sections list, then pass section and/or offset). No explicit when-not-to-use statement, so not a full 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the 15-minute link expiry and the required re-call pattern, plus the downstream user obligation to verify, sign and submit. It does not state whether the link is single-use or bound to the requesting user, which would be the remaining useful detail.

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 short sentences, front-loaded with the core action before the expiry caveat and the user reminder. Each sentence carries information, though the reminder-to-user instruction is workflow guidance rather than tool semantics and could be seen as slightly out of scope.

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

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

There is no output schema, so the description correctly characterizes the return as a link and warns about its lifetime. Combined with a single fully-specified parameter and a complete annotation set, an agent has what it needs to invoke this correctly; only the link's single-use/user-binding semantics are left 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 single artifact_id parameter is fully documented in the schema with format and pattern. The description only alludes to it indirectly via generate_filled_pdf, adding no syntax or sourcing detail beyond 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 verb (get) and resource (download link for a PDF) and ties the artifact's origin to a named sibling, generate_filled_pdf. An agent can distinguish this from generate_filled_pdf or get_application without opening any 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?

The description establishes the prerequisite (a PDF produced by generate_filled_pdf) and tells the agent what to do when the link lapses ('call again for a fresh one'). It stops short of explicit exclusions or naming an alternative tool for other artifact types, but the context is clear.

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 openWorldHint=false, so safety is covered. The description adds genuinely non-structured behavior: results are short summaries rather than question lists, the query is phrase-matched across title/description/issuer/jurisdiction/form number/aliases, and an empty result has a specific meaning. Pagination semantics are left to the schema.

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?

Dense but front-loaded: the purpose comes first, then return shape, then routing, then query syntax. Four sentences each carry distinct information. Slightly long, but 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?

There is no output schema, and the description compensates by enumerating the returned summary fields (template id, title, issuer, jurisdiction, category, document_id, review status) and by explaining routing, query semantics and empty-result behavior. An agent has everything needed to call it and act on the result.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond it by explaining the matching model for 'query' (one phrase, one or two keywords) and by steering the city out of the query and into filters.jurisdiction — non-obvious usage guidance the schema does not provide.

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 ('Find official PDF forms PaperPorter can fill') and immediately grounds it with concrete examples of the domain (building, reroof, sign, tree permits, licenses). It also distinguishes itself from siblings by naming get_form_requirements and create_application as the downstream consumers of a returned id.

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 entry-point guidance ('Start every fill here') plus a clear handoff rule ('pass a returned id to get_form_requirements or create_application'). It also tells the agent how to phrase the query and what an empty result means, which are exactly the when/how conditions 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?

Annotations only cover the safety profile (readOnly=false, idempotent=true, destructive=false); the description adds the genuinely non-obvious behavior: optimistic-concurrency failure on stale expected_revision, automatic clearing of answers invalidated by conditions (surfaced in cleared_conditional_answers), and the returned revision/issues/questions. This is exactly the beyond-annotation context that prevents silent data loss.

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 sentences, each carrying distinct payload: the patch guardrail, the revision-conflict contract plus recovery, the conditional-clearing side effect, and the return shape. The most consequential constraint (never guess values) is front-loaded and there is no filler.

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

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

With no output schema, the description compensates by naming the return payload (new revision, issues, remaining questions). For a mutation tool with nested-object params, it covers concurrency, side effects, and recovery, so an agent has everything needed to call and retry 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%, so the schema already documents the three parameters, including the answers_patch value formats and the null-clears rule. The description still adds decision-level semantics the schema cannot express — only send keys you have answers for, and expected_revision's role as a conflict guard with a defined retry path — which lifts it above the baseline 3.

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 (save answers into a draft application) and the guardrail 'answers the user actually gave' makes the write intent unmistakable, distinguishing it from read siblings like get_application and from create_application. It stops short of explicitly contrasting itself with the other mutating sibling (validate_application), so it lands just under 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?

It gives concrete usage rules: only include keys you have answers for, never invent values, and on a revision conflict re-read with get_application and retry. That is clear operational guidance, though it frames conditions rather than explicitly stating when to prefer this tool over validate_application or generate_filled_pdf.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by naming the returned fields (valid, revision, issues, remaining_questions) and the follow-up routing, though it does not say whether all issues are reported or just the first, or whether results are cached per revision.

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 compact sentences, front-loaded with the core action and its scope, then the return shape, then the workflow. Every sentence carries information; the workflow sentence is slightly dense 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?

With no output schema, the description compensates by naming the returned fields, and for a single-parameter read-only tool it fully covers what an agent needs: what is checked, what comes back, and what to do next.

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?

Only one parameter, application_id, with 100% schema description coverage that already explains it comes from create_application. The description adds no further semantics about the ID, 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?

States a specific verb (validate/check a draft) and enumerates exactly what is inspected: answer types, allowed choices, date formats, required questions, conditions, and overflow text. It also explicitly distinguishes itself from generation ('without generating anything'), so an agent can tell it apart from generate_filled_pdf and update_application without reading 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?

Gives an explicit workflow: validate here, fix issues with update_application, then show the user and get explicit confirmation before generate_filled_pdf. The when-not condition ('without generating anything') is stated directly, leaving nothing to inference.

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