Emboss

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

The description discloses many behaviors beyond annotations: replacement semantics ('uploading a second document for the same requirement replaces the first'), ephemeral deletion ('source and output documents are deleted 60 to 70 minutes after the last activity'), cost implication ('attachments are part of the already-billed prepare'), and file type/limit constraints. This is rich, actionable context that annotations do not provide.

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

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

The description is long and includes a misleading first sentence that is tangential to the tool's purpose. While every subsequent sentence adds value (constraints, replacement, ephemeral, billing), the lack of front-loading of the core action and the confusing opener hurt structure. It could be tightened.

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

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

The description covers most operational details: file sources, types, limits, requirement behavior, retention, and billing. However, it does not explicitly state that at least one of file_url or file_base64 must be provided, which is a critical requirement given the schema makes both optional (default null). The presence of an output schema reduces the need to explain return values.

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 explain parameters, and it does thoroughly: file_url is a public https link, file_base64 is an alternative, proposal_id refers to a proposal from prepare_form, and requirement names an entry in the form's attachments_required list. This fully compensates for the schema's lack of descriptions.

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 core action is clearly stated: 'Attach one document ... to a proposal from prepare_form.' However, the description begins with a confusing preamble about 'Prepare a form from documents' which seems to belong to a different tool, muddying the primary purpose. The verb+resource is specific, but the opening reduces clarity.

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 (attach documents to a proposal) and gives constraints (file types, limit, requirement replacement), but it never explicitly contrasts with sibling tools like fill_form, commit_proposal, or prepare_form. No when-to-use vs. alternatives or when-not-to-use guidance is provided.

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

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

Annotations indicate no safety hints (readOnly=false, etc.), so the description must carry the burden. It does this well: it discloses that the operation is asynchronous (returns a job_id, polling every 20s), that it produces a report and receipt, that package=true bundles attachments and receipt, and that it is free up to 10 commits per proposal. This goes well beyond 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?

The description is dense but efficient, with each sentence adding critical information. It is front-loaded with the main action, then parameters, then billing/polling details. No redundant phrases.

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 is complex: asynchronous, with multiple outputs and billing nuances. The description covers usage, polling, and package behavior, and the output schema exists to explain return values. It lacks explicit explanation of 'confirm' parameter and does not detail error cases, but given the output schema and the richness of the description, it is nearly 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 must explain parameters. It explains proposal_id, values (field_id, value, note), policy (safe or strict), and package. It does not explain 'confirm' explicitly, though it can be inferred from 'Write or confirm the answers'. Given the schema has no descriptions, the description partially compensates but misses one 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 clearly states the tool's purpose: write/confirm answers, render the form, check it, and return a PDF with a report and receipt, or a submission package. It mentions the key resource (proposal_id) and distinguishes it from siblings like prepare_form (which is the prerequisite) and get_job (polling).

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 provides clear usage context: it requires a proposal_id from prepare_form, and it mentions when to use package=true. However, it does not explicitly say when NOT to use this tool or name alternative tools for different workflows (e.g., fill_form for simpler filling). Still, the context is strong 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 are sparse (all hints false), so the description carries some burden. It discloses that the tool is free, creates a new artifact, and returns the new artifact_id, plus page selection and rotation behavior. However, it does not mention side effects on source artifacts, permissions, limits, or error behavior.

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

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

The description is compact and parameter-focused, but it repeats 'Build one PDF' across the first two sentences and opens with 'Free.', which adds little functional value. The structure is not as tight as it could be.

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

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

The description covers the single complex parameter, return value, and links to documentation for page selections. With an output schema present and the parameter format well specified, it is largely complete for invocation. Minor gaps remain around examples and edge cases.

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 compensate. It explains that sources is a list of {artifact_id, pages, rotate}, gives page selection syntax like 1-3,7, states pages can be omitted for all pages, and specifies rotate values 90/180/270. It does not explicitly say artifact_id is required per item, but it is strongly implied.

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

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

The description clearly states it builds one PDF from pages of several artifacts, with order and rotation. This is a specific verb+resource combination that distinguishes it from siblings like merge_pdf, extract_pages, and rotate_pages by combining selection, ordering, and rotation into a single operation.

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 purpose sentence implies when to use the tool (composing selected pages from multiple artifacts into a new PDF), but it does not explicitly contrast it with sibling tools or state when not to use it. Usage is implied rather than directed.

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

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

Annotations provide no hints (all false), so the description carries the full burden. It discloses timing (returns when detection finishes, usually under two minutes), billing (first 5 free), and retention behavior (ephemeral deletion after 60–70 minutes). This goes beyond the annotations and gives useful side-effect context. It does not contradict annotations.

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

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

The description is a solid paragraph with every sentence adding value: conversion purpose, input options, timing, library hint, billing, and retention. It is not overly verbose, though the retention explanation could be tighter. Front-loads the core purpose.

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 details are not required. The description covers inputs, timing, billing, and retention, but leaves a critical ambiguity: it implies a PDF source is needed (pdf_url or pdf_base64) yet the schema marks both optional, and the title parameter is unmentioned. This could cause an agent to call it without a PDF. Completeness is adequate but has clear gaps.

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

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

Schema description coverage is 0%, so the description must explain parameters. It does explain pdf_url (public https link), pdf_base64, library (slug from find_form), and retention (ephemeral or account_default), adding meaning beyond the schema types. However, it omits the title parameter entirely, so it does not fully compensate for the schema's lack of documentation.

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

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

The description clearly states the tool converts a flat or scanned PDF into a fillable PDF with detected fields, using a specific verb and resource. However, it does not explicitly distinguish this from sibling tools like prepare_form or fill_form, so it misses the differentiation criterion for 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?

The description gives a clear context (turning a PDF fillable) and a usage hint about using library from find_form, but it never states when to use this tool versus alternatives or when not to use it. There is no explicit exclusion of other siblings, so guidance is implied rather than stated.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds the specific detail that PDFs are also removed, and uses 'permanently' to signal irreversibility. This enriches the annotation-provided profile without contradicting it. It could mention side effects like cascading deletions, but the added PDF detail is valuable.

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 a single, front-loaded sentence that states the core action without any filler. It is appropriately sized for a tool with one parameter and clear purpose.

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

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

The description covers the essential action and scope (form plus PDFs). Given the existence of an output schema and annotations that cover destructive and idempotent behavior, the description is largely complete. It doesn't mention prerequisites like the form existing, but that is minor for a delete operation. The only slight gap is not detailing the return value, but the output schema covers that.

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 the form_id parameter. It does not explain the parameter beyond the schema's title 'Form Id'. The tool name and context make it somewhat obvious, but the description adds no explicit guidance on what form_id refers to, its format, or any required validation. The description fails to compensate for the low schema coverage.

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

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

The description states a specific action ('removes'), a specific resource ('a form and its PDFs'), and a scope ('from the user's library'). It clearly distinguishes from sibling tools like delete_pages (which deletes only pages) and create_form (which creates 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?

The description implies usage: use this when you want to delete an entire form. However, it does not explicitly contrast with alternatives (e.g., delete_pages for partial deletion) or provide any when-not-to-use guidance. The purpose is clear but the usage context is only implied, not stated.

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 indicate readOnlyHint=false and destructiveHint=false, which the description complements by explaining that it returns a new artifact_id, implying a non-destructive operation that creates a new PDF. It adds the page numbering format and the fact that the rest are kept in order. No contradiction with annotations.

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

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

The description is compact and front-loaded: 'Free. Remove the pages you name from a PDF and keep the rest in order.' It then adds necessary details in a single sentence. No fluff; every sentence earns its place.

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

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

For a simple deletion tool with an output schema and annotations, the description covers the core operation, page syntax, and return value. It does not need to explain error cases or prerequisites for this simplicity. Complete for an agent to invoke 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 carries full responsibility. It explains the 'pages' parameter with the 1-based range syntax ('1-2,17') and clarifies that 'artifact_id' is the target PDF ID. Both parameters are fully explained beyond the schema.

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

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

The description clearly states the verb (remove) and the resource (pages from a PDF), and explicitly notes that 'every other page stays in order', which distinguishes it from extraction or reordering. It differentiates from siblings like extract_pages and reorder_pages by focusing on deletion while preserving order.

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 when to use it (when you want to delete specific pages from a PDF) but does not explicitly contrast with alternatives like extract_pages or provide exclusions. It says 'Remove the pages you name' which is clear, but there is no explicit 'use this instead of X' guidance. The 'Free' note might hint at cost, but that is not a usage alternative.

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 behavioral detail beyond the annotations: pages use 1-based indexing, supports ranges, repeats, and arbitrary order, and it returns a new artifact_id. This complements the annotations (readOnly=false, destructive=false) by implying a new artifact is created without destroying the source.

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 fairly short but has redundancy: the first and second sentences both repeat 'Keep only the pages...'. This slight repetition could be streamlined, though the action is still front-loaded.

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

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

The description is sufficiently complete for a two-parameter tool with an output schema. It covers page syntax, the operation, and the return value. Minor missing detail such as explicit statement about the original artifact being unchanged is implied by 'new artifact_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?

With 0% schema description coverage, the description compensates by fully explaining the `pages` parameter syntax (1-based, ranges, repeats, order) and contextualizing `artifact_id` as the source PDF. This is essential for correct invocation.

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

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

The description clearly states the action: keeping only named pages from a PDF in the specified order. It distinguishes itself from siblings like delete_pages and reorder_pages by noting that the order of pages can change and that it keeps only specified pages.

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 when to use the tool through its operation ('keep only pages you name, in order'), but does not explicitly state alternatives or when not to use it. It provides context but no exclusions or explicit guidance compared to sibling tools.

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

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

With sparse annotations (all hints false), the description carries the burden and does so thoroughly. It discloses billing per row and per context fill, synchronous vs asynchronous execution thresholds, retention modes, and ephemeral deletion timing. This adds substantial behavioral context well beyond the structured annotations, with 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?

The description is dense and front-loaded with the core purpose, and every sentence carries relevant operational detail. It is slightly repetitive in the opening two sentences and could benefit from bullet structuring, but it is not 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?

For a complex batch tool, the description covers the essentials: input methods, mapping behavior, row limits, async behavior, billing, retention, and cleanup. Since an output schema exists, return-value details are unnecessary. Minor omissions like error handling and exact csv_text formatting keep it just shy of 5.

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?

Given 0% schema description coverage, the description compensates well: it explains csv_url/csv_text as row sources, mapping as {column: field_id} with a default behavior, and retention values/default. It does not explicitly spell out form_id or the raw text format of csv_text, but those are reasonably inferable from context and sibling tools.

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: 'Fill one copy of a PDF form for every row of a spreadsheet.' It clearly distinguishes itself from single-fill siblings like fill_form by emphasizing per-row batch behavior, and the CSV input methods are named upfront.

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 clearly conveys the intended use case (filling a form for many spreadsheet rows), and it provides operational guidance such as polling get_batch for batches above 50 rows and letting suggest_mapping run when mapping is omitted. However, it does not explicitly contrast with fill_form or fill_form_from_context, so it stops short of full 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?

The description discloses significant behavior beyond the sparse annotations: billing and free quota, the unavailable flatten flag, unmatched-label reporting, retention modes, and ephemeral deletion timing. This is exactly the operational detail an agent needs to set expectations and ask the user about unmatched fields.

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

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

The description is dense but each sentence carries operational information. The core purpose is first, followed by value semantics, restrictions, return behavior, billing, retention, and deletion lifecycle, in a logical order 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 4-parameter tool with an output schema, the description covers required inputs, value format, return content, cost implications, and data lifecycle. Nothing essential is missing for an agent to invoke fill_form 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% parameter schema descriptions, the description compensates fully: values are structured by field id/label, checkboxes accept yes/no, choice fields require a valid option, flatten is reserved, and retention is ephemeral or account_default with the account setting as default. form_id is obvious from the 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 clearly identifies the action ('fill') and resource ('PDF form'), and adds that it works from structured values keyed by field id or label. It does not explicitly contrast this with the sibling fill_batch or fill_form_from_context tools, so it stops just short of full sibling differentiation.

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

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

It gives clear context for use: a ready form and structured data such as JSON or key-value answers. It lacks explicit exclusions or comparisons with sibling fill tools, so agents are not told when to prefer fill_batch or fill_form_from_context.

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, the description reveals load-bearing operational behavior: the tool is asynchronous (returns a job_id to poll every ~20 seconds), billed with a free tier, supports retention modes, and can delete source/output documents after 60-70 minutes. This is exactly the kind of context that annotations do not provide.

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

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

The core purpose is front-loaded, and every subsequent sentence earns its place by adding parameter semantics or operational details. For an 8-parameter tool with no schema descriptions, this length is justified and there is no filler or repetition.

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 though an output schema exists, the description still covers the essential workflow: context ingestion, form selection, policy choice, job polling, billing consequences, and retention behavior. An agent has enough information to invoke the tool correctly and interpret what happens 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?

The schema has 0% description coverage, yet the description compensates thoroughly: it defines policy values (safe vs strict confidence thresholds), accepted context_urls file types, form-source alternatives, and retention semantics. Each parameter name is given practical meaning beyond its raw schema definition.

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

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

The description opens with a specific action, 'Fill a PDF form using facts found in supporting documents,' and immediately names the context sources that distinguish this tool from siblings like fill_form or fill_batch. It also explains the different form-selection modes (form_id, pdf_url/pdf_base64, library), leaving no ambiguity about the tool's core purpose.

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 clearly establishes when to use this tool: when answers should be read from context_text and/or context_urls, and it gives concrete rules for choosing between form sources. It does not explicitly name fill_form or fill_batch as alternatives or state when not to use them, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the description adds meaningful non-obvious behavior: alias normalization, the rate-limit cost per search, and the instruction not to fire partial queries. This is exactly the kind of behavioral context annotations cannot convey.

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 core purpose and then adds return fields, rate-limit guidance, and downstream create_form usage in a logical order. The closing 'Free.' is the only sentence that does little to help an agent invoke the tool correctly, so it falls just short of a perfect conciseness score.

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

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

For a simple one-parameter search tool, the description is complete: it explains what to pass, how the query behaves, what fields are returned, how many rate-limit slots are consumed, and how the result feeds into create_form. The existence of an output schema reduces the need to document return values further, but the description already does so.

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 'query' parameter has no schema description, so the description carries the full burden. It compensates thoroughly by explaining that the query can be a name, number, or alias, and gives concrete examples like 'w9', 'W-9', 'form w 9', and 'taxpayer identification'.

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

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

The description uses a specific verb and resource: 'Find a blank government form in the Emboss library by name or number.' It clearly distinguishes this search-and-match behavior from siblings like get_form or list_forms by emphasizing lookup by name/number/alias and returning multiple match summaries.

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 operational guidance: send the whole query once, do not search as the user types, and be aware each search consumes a rate-limit slot. It also explains how to pass the returned slug to create_form, though it does not explicitly contrast this tool with other lookup siblings such as list_forms or get_form.

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, and non-destructive behavior. The description adds value by disclosing response behavior: it returns per-row download links for the first 100 finished rows and a zip link when the batch is complete. This reveals limits and conditional output, which goes beyond the annotations and is essential for an agent to understand the tool's runtime behavior.

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 a single, tightly packed sentence that front-loads the core purpose ('Progress of a fill_batch run') and immediately lists the key outputs. There is no wasted wording, and every phrase contributes meaning. It is an exemplar of concise, well-structured tool documentation.

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

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

Given the tool has an output schema and the annotations cover the safety profile, the description adequately covers the essential behavior: what the tool returns (progress, per-row links, zip link) and a key constraint (first 100 rows). It does not explain how to interpret the links or poll, but these are likely detailed in the output schema. For a simple read-only operation with one parameter, it is sufficiently 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?

With 0% schema description coverage, the description carries the burden of explaining parameters. However, the only parameter is batch_id, which is self-evident as the identifier of the batch fill. The description does not explicitly state where the ID comes from (e.g., from fill_batch's response) or its format, but the name and context make it clear. It adds minimal value over the schema's type definition, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: checking the progress of a fill_batch run and providing download links for finished rows. It names the specific operation it tracks (fill_batch) and the outcome (progress, links), which distinguishes it from generic job-status tools like get_job and from the batch-creation tool fill_batch.

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 after a fill_batch call by mentioning 'progress of a fill_batch run,' but it does not explicitly state when to use this tool versus alternatives like get_job or get_form. It provides context but no explicit exclusions or comparisons to other status/retrieval tools, leaving the agent to infer the appropriate scenario.

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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. It adds value beyond the annotations by disclosing the outcome vocabulary (working, delivered, failed), that failure includes a reason, and that refund state is tracked, which helps the agent anticipate the tool's observable behavior.

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 17-word sentence that front-loads the core purpose ('Delivery status and receipt') then packs the outcome states into the tail. Every word earns its place with no filler or redundancy.

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 low-complexity, single-parameter read tool with rich annotations and an output schema present, the description is nearly complete: it names the resource type, the outcome states, and refund context. The only notable gap is guidance on how this differs from the get_job sibling, which prevents a 5.

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

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

The schema has 0% description coverage on job_id, so the description carries the burden. It partially compensates by clarifying that job_id refers to a send_fax job, linking it to send_fax's output. But it does not specify the expected format, provenance, or how to obtain the ID, so compensation is incomplete.

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

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

The description clearly states the tool checks delivery status and receipt for a send_fax job, enumerating the specific states (working, delivered, failed) and the failure reason plus refund state. This is specific and actionable, but it does not explicitly differentiate itself from the get_job sibling, which likely covers generic job status, 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?

The phrase 'of a send_fax job' implies the usage context: call this after send_fax to check delivery. However, it does not explicitly state when to use this instead of get_job or get_batch, nor does it mention any exclusions or alternatives among the 26 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?

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds a readiness nuance and states that a PDF download link is returned, but it does not explain what happens before the form is ready or describe failure modes.

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

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

The description is concise, front-loaded with 'Status of one form', and each clause adds useful information without filler or repetition.

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

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

For a simple read-only tool with rich annotations and an output schema, the description provides enough core information: status, field contents, and download link. Minor ambiguity about the readiness behavior remains, but the structured metadata covers safety and return shape.

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

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

The schema has one required form_id string with 0% description coverage, and the description does not compensate by explaining the parameter's format, source, or constraints. It only ties the parameter to 'one form', which is minimal additional meaning.

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

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

The description clearly states the tool returns the status of one form, lists the returned field types, and mentions a PDF download link. It is specific about the verb and resource, but it does not explicitly differentiate from sibling tools like read_form or find_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?

No guidance is given about when to choose this tool over alternatives such as read_form, find_form, or list_forms. The phrase 'When ready' gives a timing nuance, but there are no exclusions or selection criteria.

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 read-only/idempotent safety; the description adds behavioral detail about readiness and the returned payload: download link, filled-field count, and commit-specific receipt_url/package_url. It doesn't describe the not-ready state, but 'when ready' implies polling and the output schema covers the rest.

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 compact, front-loaded sentences with no filler. The job type scope appears first, followed by the actionable return details.

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 and read-only/idempotent annotations, the description is nearly complete. The only notable gap is not explicitly stating that job_id should come from the response of the creating tool, though this is inferable from context.

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 must compensate. It implies job_id references one of the listed async job types, but it never explicitly says the ID is supplied by fill_form_from_context/prepare_form/commit_proposal or how to obtain it. Some meaning is added, but the parameter remains under-specified.

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

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

Description uses a specific resource ('fill_form_from_context, prepare_form, or commit_proposal job') and a clear status-checking verb. It distinguishes get_job from sibling get_form/get_batch/get_fax/get_proposal by naming the exact job-producing operations.

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 context: use for checking jobs created by fill_form_from_context, prepare_form, or commit_proposal. It doesn't explicitly list sibling tools to avoid or state when not to use them, but the job-type scoping is enough to infer appropriate use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral details: reading is free ('No charge to read it') and the response contains field states, candidate values with evidence, and open questions. However, the off-topic first sentence adds noise and undermines the overall behavioral contract.

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 not concise: the first sentence is entirely extraneous and misdirects the agent. The relevant content appears in the second and third sentences, violating the front-loading principle. A short, focused description would be much more effective.

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

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

For a one-parameter read operation with an output schema and supportive annotations, the core information is present: what the proposal contains and that reading is free. However, the contradictory opening sentence and lack of any differentiation from sibling tools leave the definition incomplete and potentially misleading.

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

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

Schema description coverage is 0%, so the description must compensate. It explicitly says 'Read a proposal by its proposal_id', clarifying that the sole parameter is the identifier used to fetch the proposal. This is sufficient for a single string 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 title and second sentence state a clear read operation ('Read a proposal'), but the first sentence describes a completely different workflow ('Prepare a form from documents'), likely copy-pasted from another tool. This conflicts with the tool's actual purpose and forces an agent to disambiguate contradictory instructions.

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 no guidance on when to use get_proposal versus alternative tools like get_form, read_form, or prepare_form Ś the wrong first sentence even suggests this tool is for preparing forms. No when-to-use or when-not-to-use conditions are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it includes a billing page link, which is a small behavioral detail. It doesn't disclose return format or pagination, but for a zero-parameter read-only tool, the annotations carry most of the burden.

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 a single sentence that front-loads the core purpose ('This month's usage and how many free operations remain') and appends the billing link detail. Every word earns its place; no fluff or redundancy.

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

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

For a zero-parameter, read-only tool with an output schema present, the description is nearly complete. It tells the agent what data to expect (usage, free operations, billing link). It could mention whether the billing link is a URL string or a clickable action, but the output schema likely covers that. Overall, adequate for an agent to invoke 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?

There are zero parameters, so the schema has nothing to document. The description compensates by explaining what the tool returns (usage, free operations remaining, billing link). With no parameters, a baseline of 4 is appropriate, and the description adds meaningful context about the output.

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

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

The description clearly states the tool reports this month's usage and remaining free operations, and includes a billing page link. It uses a specific verb ('Check') and resource ('usage'), and is distinguishable from siblings like get_batch or get_job, though it doesn't explicitly name a sibling alternative.

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

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

The description implies this is for checking usage/free tier status, which is a clear context. However, it doesn't explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The context is implied rather than explicit.

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 and idempotentHint, so the description adds value by specifying exactly which structural facts are reported (encryption, outlines, embedded files, JavaScript, etc.) and explicitly stating that text and field values are not extracted. This goes beyond the annotations, though it doesn't describe side effects or error behavior.

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 somewhat redundant, repeating the list of structural facts in two sentences, and starts with an unexplained 'Free.' which appears to be a typo or leftover fragment. It could be tightened to a single concise sentence without losing information.

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

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

Given the presence of an output schema, the description need not detail return values. It covers the tool's purpose, the scope of reported facts, and explicitly excludes text and field values. It lacks usage guidance and has the confusing 'Free.' prefix, but overall it's adequate for a simple read-only inspection 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?

The schema has only one parameter (artifact_id) with 0% description coverage, so the description must clarify its meaning. It does by stating 'Structural facts about artifact_id', indicating artifact_id identifies the PDF to inspect. However, it doesn't specify the format or origin of artifact_id, but it's sufficient for a single-param tool.

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

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

The description states a specific action (report/inspect) on a specific resource (PDF structure) and enumerates exact facts (page count, sizes, rotations, encryption, form fields, annotations, etc.). It explicitly excludes text and field values, which differentiates it from content-extraction tools like read_form or fill_form, even without naming them.

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

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

The description implies usage for structural inspection but does not explicitly state when to use this tool over alternatives. It notes what it does not do (no text, no field values), giving some guidance, but lacks explicit exclusions or alternative tool names, leaving the agent to infer the appropriate context.

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, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the allowed state values ('ready', 'processing', 'failed', 'all') and the pagination mechanism (cursor), which go beyond annotations. It does not contradict the annotations.

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

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

The description is two short sentences that front-load the resource ('Forms in the user's Emboss library') and then detail state and pagination. There is no fluff or redundant wording, making it efficient and easy to scan. It could be slightly clearer by adding 'List' at the start, but it is concise.

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

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

For a simple listing tool, the description covers the state filter and pagination, while the output schema documents the return format and annotations cover safety. However, the limit parameter is not explained, and there is no mention of default behavior beyond the schema defaults. This is adequate but leaves a minor gap in understanding all parameters.

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

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

With schema description coverage at 0%, the description must explain parameters. It explicitly lists the state values and mentions cursor for pagination, but does not explain the limit parameter, leaving its meaning to common sense. This partial coverage compensates somewhat but is not complete for all three parameters.

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 that the tool returns forms in the user's Emboss library, which implies a listing operation. It adds state filtering and pagination details, distinguishing it from single-form tools like get_form or find_form, though not explicitly naming them. The purpose is clear and specific enough for an agent to understand it lists 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?

The description gives no guidance on when to use this tool versus alternatives such as find_form or get_form. It only mentions filtering by state and pagination, but does not state when listing is appropriate or when to prefer another sibling. This is implied but not explicit, leaving the agent to infer usage.

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?

Without meaningful annotation support, the description carries the burden and does state key behavioral facts: it is free, creates a merged PDF, preserves the given order, and returns a new artifact_id. It does not discuss limits, source immutability, or sync behavior, but for a simple merge operation it is substantially transparent.

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 short and front-loaded with the core action. It earns points for including the alternative tool and return value, but it loses a point for near-duplicate phrasing: 'Join whole PDFs into one file in the order given' and 'Join whole PDFs in order' say essentially the same thing.

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 tool with a simple result, the description covers the source list, ordering semantics, output artifact_id, and the key alternative for finer-grained selection. It omits things like file count limits or source existence checks, but these are not necessary for basic correct invocation.

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

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

Schema coverage is 0%, and the description compensates by explaining that sources is a list of artifact identifiers and that the order of items matters. The phrasing 'list of {artifact_id}' is slightly ambiguous against the schema's object item type, but it still adds essential meaning beyond the empty `additionalProperties` schema.

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

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

The description states a clear verb and resource: 'Join whole PDFs into one file in the order given.' It also distinguishes the tool from compose_pdf by explicitly limiting the operation to whole PDFs rather than page selections.

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

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

The description gives explicit guidance on when to use this tool ('whole PDFs', 'in order') and when not to, directing the agent to compose_pdf for page selections. This is more than enough to route an agent correctly among the PDF-manipulation 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?

Annotations declare readOnlyHint=false, but the description adds critical behavioral context: it creates a proposal (job_id/proposal_id), does not modify the PDF, discloses billing ('first 5 each month are free'), and specifies ephemeral retention with deletion timing (60-70 minutes after last activity). No contradiction with annotations.

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

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

The description is dense but not wasteful; each sentence contributes (purpose, inputs, behavior, billing, retention). It front-loads the core purpose and usage distinction. Slightly long but appropriate given 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?

It covers the essential operational details: inputs, proposal contents, policy, output (job_id/proposal_id), polling interval, billing, and retention. The only gap is the unexplained 'library' parameter. Given the output schema exists and other details are thorough, it is nearly 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?

With schema description coverage at 0%, the description carries the burden. It explains form_id vs pdf_url/pdf_base64, context_text/context_urls, policy (safe/strict), and retention (ephemeral/account_default). However, it does not explain the 'library' parameter, leaving one parameter undocumented. Still, it adds substantial meaning beyond raw schema.

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

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

The description states a specific verb+resource: 'Prepare a form from documents' and clarifies it produces a proposal (answers with sources, missing items, disagreements) before writing. It explicitly distinguishes itself from fill_form_from_context (which writes) and commit_proposal (which commits), making its purpose 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?

It directly says 'Same inputs as fill_form_from_context ... but nothing is written into the PDF: read the proposal, answer what is missing, then commit.' This names the alternative tool and provides a clear when-to-use condition. It also explains policy options and the follow-up action.

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 discloses meaningful behavior beyond annotations: nothing is stored, read-back never keeps the file, usage is billed as one read, and the first five per month are free. It also explains return semantics (every form box with value and filled status, plus labels/completeness when recognized). The annotations show idempotentHint=true, which is consistent with 'nothing is stored', and readOnlyHint=false is reasonably explained by billing.

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 tightly packed sentences front-load the core purpose, then input requirements, then returns, then retention/billing. Every sentence carries essential information and there is no filler or repetition.

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 read-style tool with 3 optional parameters, the description covers input format, output shape, optional-parameter purpose, data retention, and pricing. With an output schema available to define return types, nothing essential is missing for an agent to decide and invoke this 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?

Schema description coverage is 0%, so the description carries the full burden. It covers all three parameters: pdf_url as a public https link, pdf_base64 as an alternative, and form_id as an optional contextual input that upgrades the output with labels and completeness. This adds substantial meaning beyond the bare schema.

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

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

The description opens with a specific verb and resource: 'Read the values out of a filled PDF form', and immediately adds distinctive outcomes: labeling by field, required-status, and a completeness verdict. This separates it clearly from 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?

The description gives clear input instructions ('Give the filled PDF... and, when you know it, form_id') and explains when the optional form_id matters for richer output. However, it never explicitly contrasts this tool with alternatives or states when to prefer it over sibling tools such as verify_form or inspect_pdf, leaving usage selection partly implied.

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 useful context beyond the annotations by noting the operation is free, requiring order to list every page exactly once, and returning a new artifact_id. It does not clarify whether the original artifact is left unchanged or modified beyond the implication of a new artifact_id, but it does not contradict the annotations.

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

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

The description is compact and front-loaded, with 'Free.' giving an immediate cost signal followed by two focused sentences. There is mild redundancy because the 'every page exactly once' constraint appears twice, but no meaningful information is buried.

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

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

For a simple two-parameter tool with an output schema and annotations, the description covers the core operation contract, validation constraint, and result. The main gaps are the lack of explicit sibling-tool guidance and the unspecified page-indexing convention.

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 parameter burden and does give real meaning for order: it is the list of page numbers in the new order, requiring every page exactly once. It names artifact_id as the target, though it does not explicitly mention whether page numbers are zero- or one-based.

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

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

The description states a specific action and resource: reorder a PDF's pages into a new order supplied by the caller. It clearly communicates the full-permutation contract (every page exactly once), which semantically distinguishes it from sibling tools like rotate_pages or extract_pages, though it does not explicitly name an alternative.

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

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

Usage is implied rather than stated explicitly: use this when a PDF's pages need to be placed in a new custom order with every page included exactly once. It does not state when not to use it or point to alternatives such as compose_pdf, rotate_pages, extract_pages, or delete_pages.

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

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

Annotations already indicate it is not read-only and not destructive, but the description adds key behavioral detail: rotations are added clockwise to the current rotation (cumulative effect) and it returns a new artifact_id. However, it does not clarify whether the artifact is modified in place or a new artifact is created, and the phrase 'new artifact_id' is ambiguous. The description adds value beyond annotations but leaves some behavioral aspects unclear.

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 two sentences, with the core purpose front-loaded. The phrase 'Free.' is an extraneous cost note that does not aid tool invocation, but the overall structure is efficient. No redundant 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 tool with two parameters, one being a list of objects, and with no schema descriptions, the description should thoroughly explain the parameter structure. It explains the degrees and the general structure but leaves the 'pages' field ambiguous. It does not mention error handling, empty rotations, or behavior when pages are out of range. Given an output schema exists, return value is covered, but the input semantics are incomplete.

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 explain parameters. It does describe the rotations parameter as a list of {pages, degrees} with degrees limited to 90, 180, or 270, which is helpful. However, it does not specify the format of 'pages' (e.g., individual page numbers, ranges, or arrays) and the schema allows additional properties, so ambiguity remains. artifact_id is self-evident. The description partially compensates for the schema gap but not fully.

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

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

The description clearly states the action ('Rotate the pages') with a specific resource (pages of artifact_id) and the degree options (90, 180, 270). It distinguishes from siblings like delete_pages, reorder_pages, and extract_pages by naming a distinct operation. The purpose is 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?

The description implies when to use it (when you need to rotate pages) but does not explicitly state alternatives or exclusion criteria. It provides usage details like the rotation list structure, but lacks guidance on when not to use it or how it compares to other page manipulation tools. Usage is implied rather than explicit.

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 discloses meaningful behavior beyond the annotations: sending returns a job id immediately, delivery must be polled via get_fax, billing occurs per page at delivery, and failed faxes are not charged. These details tell the agent what to expect from an asynchronous, externally visible action and add value beyond the flat annotation flags.

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 carry the entire definition with no filler. Purpose, pricing, all input alternatives, return behavior, and failure semantics are packed efficiently, and the most important facts are front-loaded.

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

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

For a tool with 7 parameters, no schema descriptions, and only flat annotations, this description is complete: it covers the required format, all source alternatives, the asynchronous job flow, and cost implications. The presence of an output schema is not even needed because the description already states the job id return and the polling step.

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 every parameter is explained in the description: to must be E.164, artifact_id comes from any earlier result, job_id has a readiness precondition, form_id refers to a fillable form, pdf_url and pdf_base64 each supply one PDF, and sources lists artifact IDs with optional page ranges. The 'or' structure also conveys that these are mutually exclusive ways to provide the PDF.

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

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

The description opens with a specific verb and resource—'Send a PDF to a fax number'—and immediately adds 'track delivery' and 'priced per transmitted page,' making the action unmistakable. It clearly distinguishes send_fax from siblings like get_fax or compose_pdf by stating the tool is the fax-sending action.

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 strong contextual routing: it tells the agent to poll get_fax for delivery, and explains that job_id should come from fill_form_from_context or commit_proposal only after get_job reports ready. It does not explicitly say when not to use send_fax or when to prefer another PDF-producing tool, so it lacks the explicit exclusion clause of 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?

The description adds meaningful behavioral context beyond annotations: it discloses billing cost ('Billed as one context fill'), which is a non-obvious side effect, and clarifies that only the CSV header row is considered. The idempotentHint and destructiveHint annotations are not contradicted, and the description does not over-promise write or read behavior.

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

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

The description is concise and front-loaded with the core purpose. Each sentence adds useful information: purpose, input behavior, and billing. There is slight redundancy between 'Propose which spreadsheet columns fill which PDF form fields' and 'proposes which column fills which field,' but overall it is well-structured and efficient.

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

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

The description captures the essential invocation context: what input is needed, which CSV parameter forms are accepted, what portion of the CSV is used, and the billing cost. Since an output schema exists, not describing return shape is acceptable. The main remaining gap is dependency on the schema title for understanding form_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?

With 0% schema description coverage, the description must compensate for parameter meaning. It explicitly identifies csv_text and csv_url as CSV input alternatives and adds that only the header row matters Bolt. However, it does not describe form_id at all, nor does it clarify that one CSV source must be provided despite both being optional in the schema.

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

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

The description clearly states that the tool proposes a mapping from spreadsheet columns to PDF form fields, which is a specific verb and resource. It distinguishes conceptually from fill/compose siblings by emphasizing 'propose' rather than executing a fill, though it does not explicitly name any sibling tool.

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

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

The description gives clear context: it is used when you have a CSV (csv_text or csv_url) and a form_id, and the goal is to get a proposed mapping. It also narrows input expectations with 'Only the header row matters.' However, it does not explicitly state when not to use it or mention alternatives such as fill_form or fill_batch.

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 are all false, so the description carries the burden of behavioral disclosure. It discloses billing behavior ('Billed as one verify; the first 5 each month are free') and the return outcome set, which is useful. However, it does not explicitly state whether the operation is non-mutating (readOnlyHint is false, but 'Check' implies no mutation) or describe error conditions, rate limits, or side effects. It adds some value but lacks completeness.

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 a single sentence that packs a lot of information: purpose, checks, return values, input requirements, and billing. It is front-loaded with the core purpose ('Check a filled form') followed by specifics. While dense, it is not verbose and every clause adds value. The structure is logical: purpose, checks, returns, input, billing.

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 3 parameters and an output schema (not shown but implied). The description explains the input (form_id + PDF) and output statuses, and adds billing context. It does not describe the output schema structure, but that is covered by the output schema itself. It lacks details on error handling or edge cases, but for a verification tool this is fairly 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?

The schema has no descriptions for parameters (coverage 0%), but the description compensates by explaining how to provide the PDF: 'pdf_url: public https link, or pdf_base64' and that form_id is required. This clarifies the two optional PDF inputs and the required form identifier. It does not mention what happens if both pdf_url and pdf_base64 are provided, but it provides sufficient semantics for basic usage.

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 ('Check') and resource ('a filled form'), enumerates the exact checks performed (required fields, allowed options, consistent choices, text that fits, empty signature boxes), and lists the return statuses (complete, review required, incomplete, failed). This clearly distinguishes it from siblings like fill_form (which creates a filled form) and read_form (which extracts data) without needing to open their 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?

The description explains how to call the tool ('Give a form_id and the filled PDF') but does not explicitly state when to use it over alternatives. The purpose implies usage (when you need to validate a completed form), and the billing note ('Billed as one verify; the first 5 each month are free') gives cost context, but there are no explicit when/when-not conditions or references to sibling tools.

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