Emboss

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

Annotations only give the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false); the description adds real behavioral detail beyond them: accepted formats (PDF, PNG, JPEG), a hard cap of 20 per proposal, that file_url must be a public https link, and that re-uploading against a requirement overwrites the previous file. It still says nothing about failure modes or async behavior, so it falls short of a full 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 definition is compact and information-dense, but the lead sentence spends its effort describing prepare_form rather than this tool, pushing the actual purpose into second position. A reader has to parse a workflow preamble before learning what add_attachment does.

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 an output schema present, return values need not be explained, and the description covers the important call-time facts: accepted inputs, format and count limits, requirement matching, replacement behavior, and cost. Remaining gaps are minor (proposal_id provenance, error handling), so it is adequate for a 4-parameter write 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 description coverage is 0%, so the description must carry the load, and it largely does: file_url is defined as a public https link, file_base64 as the inline alternative, and requirement as the named entry from attachments_required with defined replace semantics. proposal_id is only implicitly identified via 'proposal from prepare_form', leaving one parameter less precisely specified than the others.

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 second sentence states a specific verb and resource: attach one document (file_url or file_base64) to a proposal produced by prepare_form. That is enough to separate it from siblings like compose_pdf or merge_pdf. The opening sentence, however, describes prepare_form's workflow rather than this tool's, which muddies the front of the definition.

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 establishes the precondition clearly: the proposal must come from prepare_form, and the requirement must name an entry in that form's attachments_required list. The replacement rule (a second upload for the same requirement replaces the first) and the cost note give the agent decision context. It never states when NOT to use it or which sibling to prefer for other attachment 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses billing behavior, the async job model ('Returns a job_id; poll get_job about every 20 seconds'), validation rules ('two yeses in one pair are refused'), checkbox semantics, and exactly what dry_run does and cannot check. This is rich behavioral context an agent could not infer from 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?

It is front-loaded with the action and result, which is good, but it is a single dense paragraph mixing workflow, validation rules, billing, and rehearsal semantics. All sentences carry information, yet the density makes it harder to scan than a short structured list.

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 six-parameter mutation with an output schema, the description covers prerequisites, side effects, cost, async polling, edge-case validation, and dry-run limits. Nothing an agent needs in order to call it correctly is missing; return-value detail is appropriately left to the output schema.

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

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

Schema description coverage is 0%, so the description must carry the full burden, and it does: proposal_id source, confirm as field ids 'get_proposal lists under confirmations', values shape (field_id, value, optional note), policy values (safe or strict) and its override semantics, package meaning and billing, and dry_run behavior. Every one of the six parameters is given meaning beyond its bare name.

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 specific verbs and resources: write/confirm answers, render the form, check it, return the PDF with report and receipt or a submission package. It clearly distinguishes this commit step from prepare_form (the source of proposal_id) and from composition/fill siblings, so an agent can tell what it produces without opening the schema.

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

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

It states the prerequisite ('Give the proposal_id from prepare_form'), the free-tier boundary ('Free within the proposal's already-billed prepare, up to 10 commits per proposal'), and when to use dry_run. It does not explicitly name an alternative sibling to use instead in any scenario, but the workflow position is unambiguous.

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

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

Annotations declare a non-read-only but non-destructive, non-idempotent write; the description adds real behavioral value beyond that by disclosing cost ("Free"), that a new artifact is created, and that the returned download_url expires in about an hour. Missing only details like permissions or whether existing artifacts are untouched.

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 core content is compact, but the opening is redundant — "Build one PDF from pages of several artifacts" is restated almost verbatim in the next sentence ("Build one PDF from several artifacts"). The "Free." lead is useful but oddly front-loaded, and the trailing docs link is a reasonable close.

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

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

For a one-parameter composition tool with an output schema, this covers everything an agent needs: source structure, page-range syntax, rotation options, cost, and the expiring download link. Since an output schema exists, the description is not obligated to document return values, yet it usefully summarizes them anyway.

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

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

Schema coverage is 0% — the single nested `sources` object has no property descriptions at all — so the description carries the full burden and does so: it defines sources as a list of {artifact_id, pages, rotate}, shows range syntax (1-3,7), states that omitting pages means every page, and enumerates rotate values (90, 180, 270). This fully compensates for the schema gap.

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 concrete verb and resource — building one PDF from pages of several artifacts — and specifies page selection and rotation, which is more than a generic merge. However, it never distinguishes itself from the near-twin sibling merge_pdf (or extract_pages/reorder_pages), leaving the agent to guess which combining tool to pick.

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 page-range and rotation options suggest this is for assembling a subset of pages across artifacts, but there is no explicit when-to-use, when-not-to-use, or named alternative (merge_pdf, extract_pages, rotate_pages). The agent must infer the selection criterion itself.

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 context beyond annotations: blocking behavior with typical latency ('under two minutes'), billing ('one form creation; first 5 each month free'), retention semantics including the 60–70 minute deletion window, and precisely what dry_run does and cannot check. This goes well past readOnlyHint/destructiveHint=false.

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 core action and source options, then billing, retention, and dry_run in a logical order. Slightly dense as one paragraph, and the dry_run explanation repeats part of the retention sentence's cadence, but nearly every sentence 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?

Given no annotations detail beyond hints, 0% schema coverage, and an existing output schema (so return shape needn't be explained), the description covers source inputs, blocking latency, cost, retention lifecycle, and rehearsal limits. An agent has what it needs to call this correctly and predict side effects.

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

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

Schema coverage is 0%, so the description must carry the load, and it explains pdf_url format ('public https link'), pdf_base64, library's origin in find_form, retention's two allowed values and default, and dry_run's effect. It leaves title unexplained and doesn't say the source parameters are mutually exclusive or that one is required.

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 ('Turn a flat or scanned PDF form into a fillable PDF with detected fields') and distinguishes itself from nearby siblings like prepare_form and read_form by describing field detection on upload. An agent can tell what this creates without opening the schema.

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

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

Says explicitly when to supply library=<slug> from find_form versus uploading a PDF, and explains what dry_run does. However, it never states what to do when neither pdf_url nor pdf_base64 nor library is present, despite zero required parameters, so the agent has no explicit instruction on the requirement to supply a source.

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 adds substantial behavioral context beyond the annotations: the deletion is permanent, it removes the form and its PDFs, dry_run has no side effects, and the rehearsal response reports whether the real call would succeed or be refused, its cost, and what rehearsal cannot check. This is consistent with destructiveHint=true and readOnlyHint=false.

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

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

The description is front-loaded with the permanent deletion behavior and then explains the dry_run path. It is appropriately sized, though the final sentence packs several output-related points together and could be slightly tighter.

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

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

For a destructive delete tool with an output schema and destructive annotations, the description covers the key deletion scope and rehearsal semantics well. It leaves minor gaps around permissions, prerequisites, and the exact treatment of attachments or related records, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains dry_run thoroughly, including side-effect behavior and response meaning, but says nothing about form_id beyond the implied form reference; the schema example shows a UUID but the description does not add further semantics for that required parameter.

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: it permanently removes a form and its PDFs from the user's library. That is clear enough to distinguish it from most siblings, but it does not explicitly differentiate it from delete_pages or other deletion-adjacent tools.

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

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

It clearly explains how to use dry_run=true as a rehearsal, including that nothing is stored, charged, sent, or AI-processed. However, it does not explicitly state when to choose delete_form over alternatives such as delete_pages, nor does it give prerequisites or exclusions.

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 covering the mutability profile (readOnlyHint=false, destructiveHint=false), the description still adds real value: the operation produces a new artifact rather than altering the original, ordering is preserved, and the returned download_url expires in about an hour. It does not restate the safety hints, so there is no contradiction.

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 tight sentences with zero redundancy; the cost note is front-loaded and the operational detail follows in priority order. Every sentence 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?

For a two-parameter tool with an output schema, the description covers the operation, the indexing convention, the ordering guarantee, and even the return values despite the output schema existing. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 0% (both params have bare titles), so the description must carry the load, and it does for 'pages' by giving both format and indexing convention ('1-based, like 1-2,17'). 'artifact_id' is only contextualized as the source document, without format details, which keeps this below a 5.

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

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

States a specific verb and resource ('Remove the pages you name from a PDF') plus the scope constraint ('keep the rest in order'), which cleanly separates it from siblings like extract_pages and reorder_pages. An agent can pick it without opening the schema.

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

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

The behavior implies when to use it (you want pages gone, not extracted or reordered), and 'Free' signals cost-relevant context. However, it never explicitly names an alternative operation or a condition for choosing it over extract_pages/reorder_pages, leaving routing 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 it is a non-read-only, non-destructive, non-idempotent operation, so the bar is lower; the description still adds real value by noting it is free, that the output is a NEW artifact (source untouched), and that the download_url expires in about an hour. It does not cover failure modes for out-of-range page numbers.

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 cost and the core operation, and it is compact. There is mild redundancy between 'Keep only the pages you name' and 'Keep only the pages named in pages', but nothing bloated.

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?

An output schema exists, so return values need not be spelled out, yet the description helpfully summarizes them anyway. For a 2-param tool with 0% schema coverage, the format rules, ordering guarantee, cost, and link expiry make it complete enough to 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%, so the description must carry the load, and it does for pages: 1-based indexing, the '2,5-9' syntax, allowed repeats and arbitrary order. artifact_id is only implied to be the source PDF, which is a minor gap, but the ambiguous parameter is well covered.

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

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

The description states a specific verb+resource: it extracts a named subset of pages from a PDF and preserves the caller's ordering. It is clearly distinguishable in effect from siblings like delete_pages, reorder_pages, and rotate_pages, though it never names an alternative explicitly.

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: 'Free' signals it costs nothing and the page-selection semantics suggest when it applies, but there is no statement of when to prefer this over delete_pages, reorder_pages, or inspect_pdf, and no prerequisites or exclusions.

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 context beyond annotations: per-row billing, the 50-row synchronous cutoff with polling, the 1000-row cap, the fact that retention is accepted but is a no-op because the form keeps its creation setting, and exactly what dry_run does and cannot check. It also discloses the hidden suggest_mapping cost when mapping is omitted.

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 core action comes first, then mapping behavior, then async/billing semantics, then caveats. Every sentence conveys a distinct operational fact with no filler.

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

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

For a 6-parameter mutation tool with an output schema (so return shape needn't be explained), the description covers cost, async behavior, parameter effects, and the rehearsal escape hatch. Only the csv_text/csv_url relationship is unaddressed, which is minor.

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 carries the burden well: it defines mapping as {column: field_id}, explains csv_text/csv_url as row sources with a 1000-row cap, and clarifies retention's inert behavior and dry_run's meaning. It never states that csv_text and csv_url are mutually exclusive or what form csv_url must take, which is the main remaining gap.

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 scope: 'Fill one copy of a PDF form for every row of a spreadsheet', immediately distinguishing it from single-fill siblings like fill_form and fill_form_from_context. The resource (PDF form) and cardinality (one per row) are unambiguous.

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 clear operational guidance: omit mapping to use suggest_mapping (and its billing consequence), poll get_batch for batches over 50 rows, and pass dry_run=true to rehearse. It does not explicitly say when to prefer fill_form over this tool for a single record, so routing against siblings is left partly implicit.

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?

A great deal of behavior beyond the annotations is disclosed: billing (one fill, first 5 monthly free), that retention is accepted but has no effect, that nothing is flattened, and what dry_run does and cannot verify. However, the claim 'fill_form itself never flattens' conflicts with the schema's own 'flatten' boolean parameter, leaving the agent unsure whether flattening is possible via this 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 first sentence front-loads purpose and the follow-on sentences each add a distinct constraint or behavior. It is dense rather than padded, though the dry_run and retention caveats make it longer than strictly necessary for a routine call.

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 an output schema present the description need not specify return values, yet it usefully notes the download link and unmatched labels. Combined with billing, dry_run, and locking guidance, an agent has nearly everything it needs, with the flatten ambiguity as the sole unresolved point.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does for most params: values are keyed by field id or label, checkboxes take yes/no, choice fields need one of their options, retention is a no-op, and dry_run rehearses without side effects. The 'flatten' parameter is left unexplained and implicitly contradicted, which is the one real gap.

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 gives a precise verb+resource ('Fill a PDF form from structured data') and scopes it to 'a ready form', which separates it from create_form, prepare_form, and fill_batch. A reader immediately knows the tool consumes an existing form and produces a filled PDF.

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 states the follow-up path ('to lock the filled PDF, call flatten_pdf with its artifact_id'), instructs the agent to ask the user about unmatched labels, and explains the dry_run rehearsal. It does not explicitly distinguish when to use this over the sibling fill_batch or fill_form_from_context, so it falls short of full routing 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?

Well beyond the annotations, it discloses asynchronous job behavior (returns job_id, poll get_job every ~20s), billing (one context fill, first 5 monthly free), retention scoping rules and the ephemeral 60–70 minute deletion window. The dry_run paragraph even explains what a rehearsal cannot verify, which is unusually candid.

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 core action and source-selection rules, then billing and retention. It is dense and somewhat run-on around retention/ephemeral/dry_run, but every sentence contributes operational information rather than filler.

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

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

For a nine-parameter, asynchronous, billable, file-touching write tool, the description covers inputs, cost, lifecycle, polling and rehearsal. With an output schema present, no return-value explanation is needed, and nothing material to correct invocation 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 0%, so the description carries the full load, and it defines all nine parameters: policy values (safe vs strict with their confidence thresholds), the three form-source options, context inputs, retention values and their applicability, and dry_run. This is exactly what the schema lacks.

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 concrete verb and resource — fill a PDF form using facts extracted from context_text/context_urls — which is far more specific than the title alone. It does not, however, contrast itself with close siblings like fill_form, fill_batch, or prepare_form, so an agent must infer that this is the context-driven variant.

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

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

Gives explicit routing between input modes (form_id for an existing library form, pdf_url/pdf_base64 for a new one, library=<slug> from find_form) and names get_job for polling. It never states when to prefer a sibling tool such as fill_form or fill_batch, which is the remaining ambiguity.

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 the safety profile is covered. The description goes well beyond that: each search consumes a rate-limit slot, up to 20 matches per call with limit up to 50, next_cursor must be echoed as cursor, and the call is free — all operational traits not present in any structured field.

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 core search purpose, then aliasing behavior, then rate-limit and pagination constraints, then the create_form handoff. Dense but each sentence carries distinct information; only the trailing 'Free.' is borderline filler, and the parenthetical alias examples are slightly verbose.

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?

An output schema exists, so the description's brief list of returned fields is a bonus rather than a necessity. Combined with rate-limit, pagination and handoff details, an agent has everything needed to invoke this correctly and chain it into create_form.

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

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

Schema description coverage is 0%, so the description must carry the load and it does: query accepts name, number or alias with a w9/W-9/word-spaced illustration, limit defaults to 20 and caps at 50, and cursor is tied to the returned next_cursor. All three parameters gain meaning absent from 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?

States a specific verb and resource ('Find a blank government form in the Emboss library') and clarifies it is a search over blank US federal forms by name, number or alias. That distinguishes it from siblings like get_form, read_form, list_forms and create_form without the agent needing to open 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 concrete invocation guidance: send the whole query once, do not search as the user types, and pass a resulting slug to create_form's library argument. What is missing is an explicit contrast with list_forms (browsing the whole catalog) or get_form (fetching one known form), which would have made the routing complete among 25 siblings.

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

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

Goes well beyond the annotations: it discloses that the original stays as-is, links keep working, fields stay uneditable, the download_url expires in about an hour, and what the report contains (fields_locked, annotations_locked, pages, calculated_left_blank). The refusal conditions add further behavioral context that annotations cannot express.

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 core action and the key input, then the return shape, then prerequisites and refusals. It is fairly long but nearly every clause adds usable information; the leading 'Free.' is minor filler.

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

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

Despite an output schema existing, the description adds the report field meanings and the download_url expiry, and covers prerequisites and refusal cases. Nothing an agent needs to invoke 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 0% for the single artifact_id parameter, so the description must carry the load. It explains that artifact_id is usually the filled PDF produced by fill_form, which meaningfully disambiguates the input, though it doesn't specify format or any validation constraints.

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 — lock/flatten a filled form by drawing every field value and comment into the page — and clearly distinguishes itself from siblings like fill_form, read_form, and verify_form by naming them. An agent can tell exactly what this does without opening the schema.

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

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

Explicitly says to run read_form or verify_form first because a locked form can't be read back or checked, and names the expected input source (the filled PDF from fill_form). It also states the two refusal cases (digitally signed PDF, dynamic XFA), which is when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description still adds real behavior: pagination in chunks of 100, a download link per finished row, and a zip link when the batch completes. It omits how in-progress or failed rows are represented and what happens with an unknown batch_id.

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 dense sentence that front-loads the purpose and tucks pagination and completion details into a parenthetical. Every clause carries information; nothing is padding.

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?

An output schema exists, so return-shape explanation is not required, and the description covers the two things an agent actually needs to drive it: page size and cursor chaining. Slightly incomplete on terminal states and error behavior for a bad batch_id.

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

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

Schema description coverage is 0%, so the description must carry the load — and it does for two of three params, explaining that the page size is 100 and that the output's next_cursor should be passed back as cursor. batch_id is left implicit, though the schema example makes it obvious.

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?

Names the resource precisely — the progress view of a fill_batch run — and states exactly what it returns: per-row download links plus a final zip link. It implicitly distinguishes itself from fill_batch (which starts the job) but does not differentiate from other polling-style siblings like get_job or get_fax.

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?

Clear usage context: this is the tool to poll after a fill_batch run, and the parenthetical explains how to page through results with the cursor. No explicit when-not guidance or named alternative (e.g. vs get_job) is given, keeping it out of the 5 tier.

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 readOnly/idempotent/non-destructive, yet the description adds substantial behavior beyond them: full status enum, retry-on-busy/unanswered/dropped semantics with attempt counts and ~17 minute window, and the field set surfaced on failure. This is exactly the polling and retry context an agent needs.

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 core purpose, then statuses, then polling, then retry, then failure payload. Dense but each sentence carries distinct information; the failure-field enumeration edges toward restating what the output schema likely covers.

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

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

For a one-parameter polling tool with an output schema carrying return values, the description covers everything an agent needs: what it returns, when to stop polling, how retries behave, and what failure states mean. Nothing material 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 0% and the single required parameter is undocumented in the schema (no description, format only shown via example). The description implies job_id identifies a send_fax job but adds no format, source, or reuse guidance, so the gap is only partially compensated.

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: retrieve delivery status and receipt for a send_fax job. Naming send_fax as the originating job makes it immediately distinguishable from send_fax (which creates) and from the generic get_job sibling.

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

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

Gives explicit operational guidance: poll about every 20 seconds and stop when status is delivered, failed or expired. It implies the post-send context but never explicitly states 'use this after send_fax' or names any alternative for other job types.

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 this read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the form has an asynchronous readiness state and only returns fields once ready, and the result includes a fillable-PDF download link.

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 short sentences, zero filler. The core purpose and the readiness caveat are front-loaded, and the return contents follow 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?

An output schema exists, so return values need not be explained, yet the description still summarizes them usefully. It discloses the not-yet-ready state but says nothing about what status values to expect or how to proceed while waiting, which is the main remaining gap for a status-style call.

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

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

There is one parameter with 0% schema description coverage, so the schema provides no meaning for form_id. The description only implies 'one form' by id and adds no format, sourcing, or lookup guidance; the UUID example lives in the schema, not the description. Adequate for a single obvious identifier but it does not compensate for the coverage gap.

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

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

The description names the resource ('one form') and specifies what comes back (every field plus a fillable-PDF download link), so the agent knows this is single-form retrieval with field detail. It does not differentiate itself from near-siblings such as find_form, read_form, or prepare_form, 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?

Usage is only implied: 'Status of one form' and 'When ready' suggest a poll-until-ready workflow for a form already identified by id. There is no explicit statement of when to choose this over find_form, list_forms, or read_form, and no exclusions given.

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, closed-world), so the bar is lower. The description adds genuinely new behavioral context: this is a state-dependent async result whose payload only materializes 'when ready', plus a conditional payload shape for commit jobs. It omits failure/pending states, which leaves a gap.

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, front-loaded with the core purpose and then the payload description; no filler. The final clause listing commit return fields is dense but each term is informative.

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?

An output schema exists, so return-value detail is not strictly required and the description redundantly supplies it. What is missing for an async polling tool is lifecycle coverage — pending vs. failed vs. ready states and what the caller should do before 'ready' — which an agent needs to use it correctly.

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

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

Only one parameter (job_id) with 0% schema description coverage, so the description must carry the burden. It indirectly tells the agent where the id comes from by naming the three producing tools, but never describes the id itself or its format. Partial compensation over an undocumented field.

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 resource (job status) and explicitly scopes it to three named producer tools — fill_form_from_context, prepare_form, commit_proposal — which distinguishes it from the many other get_* siblings. An agent can identify the polling role without opening the schema.

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

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

Naming the three job-producing tools makes the when-to-use implicit and unambiguous: call this after one of them to poll a job. It stops short of stating polling cadence, whether repeated calls are expected, or what to do on failure, so it is clear context without full operational guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context beyond them: it is free to call ('No charge to read it') and it discloses the shape of what is returned (field states, candidate values with evidence, open questions).

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 first sentence is long, off-topic for a read tool, and front-loads unrelated purpose before the actual behavior. The second sentence is tight and informative, but the preamble costs the definition its front-loaded clarity.

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 an output schema present, return values need not be explained, and the description still summarizes them. For a low-complexity, single-parameter, read-only tool the coverage is nearly sufficient, though it never clarifies where a proposal_id originates or how this differs from read_form/get_form.

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% and the single parameter has no description, so the schema does not carry the load. The description only says lookup is 'by its proposal_id', implying it is the key, but adds no format, source, or retrieval guidance (e.g., where a proposal_id comes from).

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 second sentence states a clear verb+resource with return contents: 'Read a proposal by its proposal_id: every field's state, its candidate values with evidence, and the questions still open.' However, the leading sentence ('Prepare a form from documents: a proposal of every answer...') describes content generation rather than reading, which muddies whether this tool reads or prepares and risks conflation with the sibling prepare_form.

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?

'...before writing' implies this is the read/preview step preceding a write such as commit_proposal, and 'No charge to read it' hints at cost considerations. But it never explicitly says when to use this instead of read_form, get_form, or prepare_form, leaving the routing 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 readOnly=true, idempotent, non-destructive. The description adds useful context: it returns billing link and readiness flags, and ties fax_ready to the send_fax workflow. With output schema present, no need to describe return values further, but it doesn't mention rate limits or caching, which 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?

Two tight sentences, front-loaded with primary purpose and finishing with the actionable cross-reference. No waste.

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 a zero-param read-only tool with output schema and annotations, the description covers what the tool does, when to use it, and the key workflow dependency. 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?

Zero parameters, so baseline 4. The description correctly implies no inputs are needed.

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 exactly what the tool returns: usage, remaining free operations, billing link, payment_method_on_file, and fax_ready. Specific verb+resource with no ambiguity against siblings like get_fax or get_job.

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 tells the agent to check fax_ready before send_fax, giving a clear usage condition. However, it doesn't mention when to use this versus other informational tools (like get_job), though the purpose is distinct enough.

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/closed-world, so the safety bar is low. The description adds genuinely new context: the operation is 'Free' and its scope is explicitly bounded to structure, excluding text and field values. It still says nothing about cost/latency on large files or whether the PDF must be pre-uploaded.

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 useful scope statement, but the second sentence redundantly re-lists nearly the same fields as the first (page count, sizes, rotations, encryption, form fields, annotations), padding the description without adding 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile; the description supplies the remaining scope boundaries well. The one real gap is the unexplained artifact_id, which an agent must resolve before it can call the 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?

Only one required parameter with 0% schema description coverage, so the description carries the full burden — yet it merely restates the name ('Structural facts about artifact_id') without saying what an artifact_id is, how to obtain one, or that it is a UUID reference to an uploaded document.

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 (report/inspect) and resource (a PDF's structure) with an enumeration of exactly what is returned: page count, sizes, rotations, encryption, form fields, annotations. The closing 'No text, no field values' cleanly separates it from content-reading siblings such as read_form and verify_form.

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 clear selection context by contrasting structural facts with content extraction ('No text, no field values'), which implicitly routes content needs to other tools. It stops short of naming an explicit alternative (e.g. 'use read_form for field values') or stating prerequisites like needing a previously uploaded artifact.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavioral context: the default state is "ready" and results are paginated via cursor. It does not mention ordering, page-size limits, or what an exhausted cursor means.

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 fragments with no filler, and the resource scoping is front-loaded ahead of the state and pagination notes. Slightly telegraphic, but nothing is wasted.

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?

An output schema exists, so return values need not be explained. For a no-required-parameter list tool the description covers filtering and paging, but omits the limit parameter and any guidance on default page size or result ordering.

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

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

Schema description coverage is 0%, so the description must carry the load. It fully documents the state parameter (ready default, processing, failed, all) and the cursor/pagination mechanism, but says nothing about limit, whose only hint is its schema default of 20. Partial compensation, not full.

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 noun phrase, "Forms in the user's Emboss library," which largely restates the title "List your forms" rather than stating a verb+resource action. It does add scope (the user's own library) but gives no differentiation from siblings like find_form or get_form, so an agent must infer from the name that this enumerates forms.

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 statement of when to use this tool versus find_form, get_form, or get_batch. The description implies filtering by state and paging, but never says when listing is the right choice or any prerequisite conditions.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false) describe the safety profile without contradiction, and the description adds genuinely new context: the operation is free, it returns a new artifact_id plus a download_url, and that link expires in about an hour. That expiry detail is the kind of operational trait annotations cannot convey. It stops short of covering size or source-count limits.

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 and otherwise efficient, but the core instruction is duplicated verbatim-ish ('Join whole PDFs into one file in the order given. Join whole PDFs in order:'), which wastes a full sentence. Removing the repetition would lose no 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 tool with an output schema, the description covers purpose, ordering semantics, parameter shape, return values, link lifetime, and sibling routing. What remains unstated are practical limits (maximum source count, size caps) that an agent might need before calling.

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% and the schema itself documents nothing about sources, so the description carries the load by defining it as 'a list of {artifact_id}' and stressing that order matters. The one gap is that the schema allows additionalProperties on each item, implying possible fields the description never mentions.

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 ('Join whole PDFs into one file') and explicitly scopes to whole-file merging rather than page-level work, naming the sibling compose_pdf as the alternative. An agent can distinguish this from compose_pdf and extract_pages without opening either 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?

Explicitly routes the agent: whole PDFs go here, and 'For page selections use compose_pdf' names both the when-not condition and the alternative tool. This is the exact when/when-not/alternative pattern the rubric rewards.

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 mark this as a non-readonly, non-destructive, non-idempotent write, and the description adds substantial context beyond them: nothing is written into the PDF, billing (one context fill, first 5 per month free), polling cadence (~20s via get_job), retention semantics including ephemeral deletion at 60-70 minutes, and exactly what dry_run does and does not verify. This is unusually complete behavioral disclosure.

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-loads purpose and the key distinction in the first clause, and each subsequent sentence carries non-redundant information (billing, retention, dry_run). It is dense and runs as a single block rather than being broken into scannable segments, which slightly hurts fast parsing of a 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?

An output schema exists, and the description still orients the agent on what comes back (job_id, proposal_id) and how to poll. Combined with billing, retention, and dry_run coverage, an agent has everything needed to call this correctly, including cost and side-effect expectations.

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% across 9 parameters, so the description carries the burden and largely meets it: it enumerates policy values (safe writes high+medium confidence, strict high only), retention values (ephemeral vs account_default, with the rule that it only applies when this call creates the form), dry_run semantics, and the input identifiers (form_id/library vs pdf_url/pdf_base64, context_text/context_urls). It stops short of individually defining context_urls or the base64 format, so not quite a 5.

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

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

States a specific verb and resource ('Prepare a form from documents') and immediately defines the distinguishing behavior: it produces a proposal of every answer with its source, gaps, and disagreements rather than writing. Contrasts explicitly with the sibling fill_form_from_context, so an agent can differentiate without opening either 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 workflow ('read the proposal, answer what is missing, then commit') and names the sibling that writes directly (fill_form_from_context) versus this one that doesn't. Also explains dry_run as a rehearsal path and how to use it before committing.

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?

Even with annotations present, the description adds substantial behavioral context: read-back does not store the file, the call is billed as one read with five free per month, and dry_run rehearses without storing, charging, sending, or using AI. It also explains what a dry run can and cannot verify, which is unusually complete for invocation safety.

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 purpose, inputs, returns, storage, billing, and dry-run semantics, and every sentence contributes useful information. It is slightly dense and repeats some return-value detail despite an output schema, but not enough to be 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?

Given four optional parameters, an output schema, and annotations, the description covers the essential invocation context: accepted PDF sources, optional form_id, no-storage behavior, billing implications, and dry-run behavior. There is no significant missing information for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: pdf_url is a public HTTPS link, pdf_base64 is an alternative PDF input, form_id is optional context when known, and dry_run=true rehearses the call with no side effects. This fully compensates for the sparse schema annotations.

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 gives a specific verb and resource: reading values out of a filled PDF form, labelled by field, with optional completeness verdict. This is clearly distinct from creation/filling tools, but it does not explicitly distinguish itself from closely related siblings like get_form, verify_form, or inspect_pdf.

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 explains that a filled PDF is required via pdf_url or pdf_base64 and that form_id should be supplied when known, which implies when this tool is appropriate. However, it gives no explicit guidance on when to use read_form instead of verify_form or get_form, leaving the alternative-selection decision implicit.

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 the safety profile (not read-only, not destructive, not idempotent), so the bar is lower, and the description adds genuinely useful context beyond them: it returns a NEW artifact_id plus a download_url that expires in about an hour, and that it is free. It does not state whether the source artifact is preserved, which is the main remaining gap.

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 and short, but noticeably redundant: 'every page exactly once' is stated twice in consecutive sentences, and 'put pages in a new order' is restated as 'reorder artifact_id's pages.' One sentence could be removed with no loss.

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?

An output schema exists, so the description is not obligated to explain return values, yet it usefully flags the new artifact_id and the ~1 hour download_url expiry. Combined with the ordering rule for the permutation, an agent has enough to call 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 coverage is 0%, so the description must carry the parameter burden. It does well for 'order' – every page number exactly once, in the new order – and ties artifact_id to the pages being reordered, though it never explains artifact_id's origin or format.

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 (reorder) and resource (a PDF's pages via artifact_id), and the constraint 'every page exactly once' meaningfully distinguishes it from sibling mutators like delete_pages, extract_pages, or rotate_pages. It does not name any sibling explicitly, so it falls just 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?

There is no when-to-use guidance and no alternative named among the many page-manipulation siblings (rotate_pages, delete_pages, extract_pages, merge_pdf). The permutation constraint hints at its use case but leaves the agent to infer when this is the right tool versus the others.

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 cover the safety profile (destructiveHint=false, idempotentHint=false), and the description adds value beyond them: it discloses that a new artifact_id is returned, that the download_url expires after about an hour, and critically that degrees are 'added clockwise to each page's current rotation' — explaining the non-idempotent accumulation. It does not state whether the source artifact is left intact.

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 short sentences, front-loaded with the operation and its constraints. There is mild redundancy — the degree values 90/180/270 are stated twice — but no filler or padding that would obscure the actionable content.

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 mutating tool with rich annotations and an output schema, the description covers what changes, the direction of rotation, the accumulator behavior, and the return shape and link lifetime. The remaining gap is the unspecified 'pages' selector syntax and whether the input artifact is preserved or replaced.

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% and the nested rotations objects are left as untyped additionalProperties, so the description is doing the heavy lifting: it defines rotations as a list of {pages, degrees}, enumerates the legal degree values, and clarifies the additive-clockwise semantics. It falls short on the format of the 'pages' selector (single page, range, or comma list).

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?

Names a specific verb and resource (rotate pages) plus the operation's scope: named pages only, by 90/180/270 degrees. An agent can immediately distinguish it from adjacent siblings like reorder_pages, delete_pages, and extract_pages, which perform different transformations on the same resource.

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 guidance, no when-not-to-use, and no named alternative. The only contextual hint is the leading 'Free.' cost note; the agent must infer that this is the tool for rotation rather than reordering or deletion from the verb alone.

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?

Although annotations cover safety traits (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description adds crucial context beyond them: billing is per transmitted page, failed faxes are not charged, a payment method is required, dry_run rehearses without storing/charging/sending, and the response indicates success, cost, and rehearsal limits. This is rich behavioral detail that helps an agent invoke the tool responsibly.

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 purpose and pricing, then covers parameters, returns, billing, and dry_run. It is dense and efficient, though some sentences are long and run together, which slightly reduces readability. Content is appropriate for 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?

Given that an output schema exists, the description need not explain return values in full. It still mentions the immediate job id and polling with get_fax. It covers prerequisites, billing, dry_run behavior, and all parameter sources, making it complete for an agent to call the tool correctly.

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

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

With 0% schema description coverage, the description fully compensates by explaining every parameter: `to` must be E.164 and limited to US/Canada/Mexico; PDF can come from artifact_id, job_id, form_id, pdf_url, pdf_base64, or a sources list with optional page ranges; and dry_run has explicit semantics. It also clarifies source mutual exclusivity implicitly via 'or one PDF by... or a sources list'.

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: 'Send a PDF to a fax number and track delivery, priced per transmitted page.' It distinguishes this tool from siblings by naming get_fax for polling, fill_form_from_context/commit_proposal/get_job as source providers, and get_usage for fax readiness. An agent can identify the tool's role without ambiguity.

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

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

The description gives clear context for use: send a PDF, poll get_fax for delivery, ensure payment method exists, and check get_usage for fax_ready. It details valid PDF sources and when to use dry_run. It does not explicitly state when not to use this tool or name a direct alternative for sending, but the usage conditions are otherwise 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=false, idempotentHint=true, and destructiveHint=false. The description adds substantive behavioral context beyond that: it discloses billing as one context fill with a free monthly quota, explains that dry_run stores/charges/sends nothing and uses no AI, and says the answer reports success, cost, and rehearsal limitations.

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 and mostly efficient, covering purpose, CSV input, billing, and dry_run rehearsal in a logical order. The first two sentences repeat the mapping idea, which is minor redundancy, but every sentence otherwise 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?

The tool has an output schema, so the description need not explain return values, and annotations cover safety profile. The description is complete enough for calling the tool, including cost and dry_run behavior, though it could better explain form_id and when to choose this tool over related form-preparation or fill tools.

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 for all four parameters. It clarifies that CSV input can come via csv_text or csv_url, that only the header row matters, and exactly what dry_run=true does. It does not explain form_id semantics, csv_url format expectations, or what happens if both CSV inputs are supplied.

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: propose which spreadsheet columns fill which PDF form fields. The use of 'propose' rather than 'fill' distinguishes it from sibling tools like fill_form and fill_form_from_context. An agent can identify the tool's purpose without opening the schema.

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

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

The description implies usage by saying 'Given a CSV (csv_text or csv_url)' and explains dry_run rehearsal. However, it does not explicitly say when to use this tool versus siblings such as prepare_form, fill_form, or fill_form_from_context, nor does it state prerequisites or exclusions.

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?

Goes well beyond annotations: discloses that a call is billed as one verify with the first 5 each month free, and precisely scopes dry_run (nothing stored, charged or sent, no AI used) plus what a rehearsal cannot check. The cost/credit and no-AI disclosure are things the annotations 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?

Front-loaded with the checks and the outcome states, then inputs, then billing and dry-run caveats — each sentence earns its place. The dry_run explanation is somewhat longer than needed but carries non-obvious 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?

An output schema exists, yet the description still names the three possible verdicts, which is helpful context. Remaining gaps are the URL/base64 exclusivity, PDF optionality, and invalid-input behavior, but for a 4-param validation tool this is largely complete.

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

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

Schema description coverage is 0%, so the description carries the load and does add meaning: pdf_url is a public https link, pdf_base64 is the alternative, and dry_run is a no-side-effect rehearsal. It stops short of clarifying whether the PDF is required (only form_id is in required) or what happens if both url and base64 are supplied.

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 ('Check a filled form') and enumerates exactly what is validated (required fields, allowed options, consistent choices, text fitting, empty signature boxes) plus the tri-state outcome. It does not explicitly distinguish itself from siblings like read_form or inspect_pdf, which keeps it 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 concrete input guidance (form_id plus PDF via pdf_url or pdf_base64) and an explicit conditional path for dry_run=true, but never says when to use this instead of read_form, inspect_pdf, or prepare_form. Usage is implied by the check list rather than by comparison to alternatives.

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