form fill-mcp

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about the return format (dict mapping) and pricing ('Price: $0.001 USDC per call'), but lacks details on permissions, rate limits, error handling, or whether the operation is read-only (implied but not explicit).

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 appropriately sized with three sentences: purpose, output, and pricing. It's front-loaded with the core functionality, though the pricing detail might be less critical upfront. No wasted words, but minor structural improvement could prioritize usage context over pricing.

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

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

Given the tool's moderate complexity (extraction from PDFs), 100% schema coverage, and the presence of an output schema (implied by 'Returns a dict'), the description is mostly complete. It covers purpose and output format well, but lacks usage guidelines and some behavioral details like error cases, making it slightly incomplete for optimal agent use.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (pdf_path, api_key, payment_proof) with their purposes. The description adds no additional parameter semantics beyond what the schema provides, maintaining the baseline score of 3.

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

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

The description clearly states the specific action ('Extract all form field values'), target resource ('from a filled PDF form'), and output format ('Returns a dict mapping field names to their current values'). It distinguishes itself from siblings like fill_form or list_form_fields by focusing on extraction rather than modification or listing.

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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like list_form_fields (which might list fields without values) or flatten_form (which might modify the PDF), nor does it specify prerequisites such as requiring a pre-filled PDF 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?

With no annotations provided, the description carries the full burden. It discloses that the tool saves to disk (a behavioral trait) and has a page limit constraint. However, it doesn't mention authentication requirements (api_key/payment_proof), potential rate limits, error conditions, or what happens if field values don't match form fields. The description adds some context but leaves significant behavioral aspects uncovered.

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 perfectly concise with two sentences that each earn their place. The first sentence states the core functionality, and the second provides important usage constraints. No wasted words, and the most critical information is 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?

Given that there's an output schema (which handles return values), 100% schema coverage, and no annotations, the description provides good context about the tool's scope and limitations. However, for a tool with 5 parameters including authentication options and a complex field_values object, the description could better address the authentication mechanism and error scenarios to be fully 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 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal value beyond the schema - it mentions 'field values' but doesn't provide additional semantic context. The baseline of 3 is appropriate when the schema does the heavy lifting, though the description could have explained the relationship between api_key and payment_proof.

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 specific action ('Fill a PDF form'), the resource ('PDF form'), and the outcome ('save the result to disk'). It distinguishes from siblings by specifying it's for 'standard single-page or short forms (under 5 pages)', which differentiates it from 'fill_form_multipage'.

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 context about when to use this tool ('for standard single-page or short forms under 5 pages'), which implicitly suggests using 'fill_form_multipage' for longer forms. It also references 'list_form_fields' for discovering field names. However, it doesn't explicitly state when NOT to use it or mention all alternatives like 'extract_form_data' or 'flatten_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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the iterative page-by-page approach for reliability, which is a key behavioral trait not evident from the schema. However, it doesn't mention authentication requirements (api_key/payment_proof), rate limits, or error handling, leaving some behavioral aspects uncovered.

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 perfectly concise with two sentences that each serve a clear purpose: first states the tool's function and approach, second provides usage guidelines with specific criteria. No wasted words, front-loaded with the core functionality.

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

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

Given the tool's complexity (multi-page PDF processing with 5 parameters) and the presence of an output schema, the description provides good context about when to use it and its iterative approach. However, with no annotations and a mutation operation (filling forms), it could better address authentication needs or potential side effects. The output schema existence means return values don't need explanation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions using 'list_form_fields' to discover field names, but this is already stated in the schema's field_values description.

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 specific action ('Fill a multi-page PDF form') and distinguishes it from the sibling tool 'fill_form' by specifying it's for multi-page documents with page-by-page iteration. It explicitly mentions the resource type (PDF forms) and the iterative approach.

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 explicit guidance on when to use this tool ('when the PDF has more than 5 pages or fields spanning multiple pages') and when not to use it (prefer over fill_form for complex/long documents). It gives concrete examples (rental applications, tax packets, HR forms) and names the alternative tool ('fill_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?

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it specifies the transformation (making fields non-editable), mentions the return format ('success status and output path'), and includes critical cost information ('Price: $0.001 USDC per call'). However, it doesn't cover error conditions or performance characteristics.

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 perfectly front-loaded with the core purpose in the first sentence, followed by return values and pricing in subsequent sentences. Every sentence earns its place with zero wasted words, making it highly efficient and scannable.

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

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

Given the tool's moderate complexity (PDF transformation with payment), no annotations, 100% schema coverage, and presence of an output schema, the description provides excellent contextual completeness. It covers what the tool does, what it returns, and critical cost information, making it fully adequate for agent understanding.

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

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

Schema description coverage is 100%, so the schema already documents all 4 parameters thoroughly. The description adds no additional parameter information beyond what's in the schema, maintaining the baseline score of 3 for adequate but no extra value.

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 specific action ('Flatten a filled PDF form') and the transformation effect ('so form fields become non-editable static content'), distinguishing it from sibling tools like extract_form_data or fill_form which handle form data extraction or population rather than making forms non-editable.

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 when needing to make PDF form fields non-editable, but provides no explicit guidance on when to use this tool versus alternatives like fill_form (which modifies fields) or list_form_fields (which inspects them). No prerequisites or exclusions are mentioned.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the tool's function (inspect PDF and return field details) but lacks information on permissions, rate limits, error handling, or output format specifics. The mention of 'api_key' and 'payment_proof' in the schema hints at authentication needs, but the description doesn't elaborate on this, leaving gaps in behavioral context.

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, front-loaded with the core purpose and followed by a clear usage guideline. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding by an AI agent.

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

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

Given the tool's moderate complexity (3 parameters, 1 required), 100% schema coverage, and the presence of an output schema, the description is reasonably complete. It explains the tool's purpose and usage context but could improve by addressing authentication details hinted in the schema or potential limitations. The output schema likely covers return values, so the description doesn't need to explain those.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters (pdf_path, api_key, payment_proof). The description does not add any parameter-specific details beyond what's in the schema, such as explaining the relationship between api_key and payment_proof or providing examples. Thus, it meets the baseline of 3 without compensating for any schema gaps.

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 specific action ('Inspect a PDF'), the resource ('fillable field'), and the output ('return every fillable field name, type, and current value'). It explicitly distinguishes from sibling tools by mentioning 'Use this before fill_form to discover available fields,' which differentiates it from other form-related tools like extract_form_data or flatten_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?

The description provides explicit guidance on when to use this tool ('Use this before fill_form to discover available fields'), which clearly positions it as a preparatory step for fill_form. It implies an alternative workflow (using this tool first) and sets context for its role among siblings, though it doesn't explicitly list all alternatives like extract_form_data.

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