Server Quality Checklist

Tool Scores

• pdf_mergeA
  3.8/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses that merging preserves the given order and that the result is saved, but it does not mention whether the output file is overwritten, whether input files are affected, or how errors are handled. These are notable gaps for a file-writing tool.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the action and includes the key ordering constraint. There is no wasted text or redundancy.

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

  Completeness4/5

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

  For a simple two-parameter merge tool, the description covers the core behavior and the schema documents the parameters. However, with no annotations and no output schema, a few behavioral details such as overwrite behavior and error handling are missing, though they are relatively minor for this operation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds no new parameter-specific detail beyond restating what the schema says ('in order' and 'save the result'), so the baseline 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb ('Merge') with a clear resource ('PDFs') and explains the outcome ('save the result'). It also specifies the order-sensitive nature, which helps distinguish it from sibling tools like pdf_inspect or pdf_fill that operate on PDFs differently.

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

  Usage Guidelines3/5

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

  The description implies usage when combining multiple PDFs, but it provides no explicit when-to-use guidance or comparison with alternatives. Since sibling tools cover different PDF operations, a note on when to choose merge over others would have been helpful.

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

• pdf_invoiceA
  4/5.0
  Behavior4/5

  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 meaningfully reveals that output is deterministic and byte-identical (safe to re-run) and that unpaid usage adds a footer line. These are valuable, non-obvious behaviors beyond simply 'generate a PDF'.

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

  Conciseness5/5

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

  The description is tight, front-loaded with the core purpose, and every sentence adds value: the no-template qualifier, the deterministic guarantee, and the key-dependent footer caveat. No filler or redundant restatement of the schema.

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

  Completeness4/5

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

  Given that the schema fully documents the two parameters and the description covers determinism and licensing side effects, this is quite complete for selecting and invoking the tool. It could add a note about overwrite behavior or return value, but the core invocation context is well covered.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the invoice and output_path parameters are already documented structurally. The description adds no additional parameter-level meaning beyond the schema, matching the baseline for high schema coverage.

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

  Purpose5/5

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

  The description uses a specific verb ('Generate'), a clear resource ('invoice PDF'), and a defining characteristic ('from structured data — no template needed'). This cleanly distinguishes pdf_invoice from siblings like pdf_fill and pdf_merge, which serve different purposes.

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

  Usage Guidelines3/5

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

  The description clearly implies when to use this tool: when an invoice PDF needs to be generated from structured data. However, it does not explicitly mention alternatives or when-not-to-use conditions, leaving the routing decision mostly to inference rather than direct guidance.

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

• pdf_fillA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full behavioral burden and delivers: it discloses validation behavior (field names must exist), value semantics per field type (checkbox 'true'/'false', option-list membership for dropdown/radio, maxLength for text), and a specific failure mode with remediation advice (encrypted PDFs rejected). It does not explicitly state that the source PDF is left unmodified, a minor omission given output_path implies a separate write.

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

  Conciseness5/5

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

  Three sentences with no filler: purpose front-loaded in sentence one, input constraints in sentence two, failure mode in sentence three. Each clause carries operational weight and nothing is repeated from the schema.

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

  Completeness4/5

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

  The tool is moderately complex — nested fields object, conditional value semantics, a failure mode — and has neither annotations nor an output schema, yet the description covers purpose, prerequisites, parameter semantics, and error behavior. The only gap is the return value, which is not described anywhere since no output schema exists.

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

  Parameters4/5

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

  Schema description coverage is 100%, so the baseline is 3, and the description adds genuine value on top: it specifies the value formats for the fields object ('true'/'false' for checkboxes, option-list membership for dropdown/radio, maxLength for text), which the schema only vaguely describes as 'Field name → string value'. This materially improves an agent's ability to construct valid input.

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

  Purpose5/5

  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 — 'Fill AcroForm form fields in a PDF and save the result' — which unambiguously distinguishes it from siblings pdf_merge, pdf_inspect, pdf_invoice, and pdfops_usage. The write-to-output behavior is also stated upfront, leaving no ambiguity about what the tool accomplishes.

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

  Usage Guidelines4/5

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

  It explicitly names the prerequisite workflow — 'use pdf_inspect first' — and warns when the tool will refuse input (encrypted PDFs, with decrypt advice). It does not enumerate when-not-to-use scenarios relative to the other siblings (e.g., merge or invoice), so it stops just 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.

• pdfops_usageA
  4.5/5.0
  Behavior4/5

  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 conveys a read-only check ('Check the current... quota') and discloses the authentication requirement ('Requires PDFOPS_API_KEY'). It also previews the response fields, giving the agent useful expectations without relying on an output schema.

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

  Conciseness5/5

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

  The description is a single sentence with no filler. It front-loads the core action and resource, adds the returned fields, and ends with the essential prerequisite. Every part earns its place.

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

  Completeness5/5

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

  This is a simple no-parameter tool with no annotations or output schema. The description fully covers what the tool does, what it returns, and the required environment variable. Nothing essential is missing for an agent to select and invoke it correctly.

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

  Parameters4/5

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

  There are zero parameters, so the schema provides no meaningful semantics to augment. The description correctly focuses on the configured key and the quota values returned, which is the relevant context for a parameterless tool.

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

  Purpose5/5

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

  The description names a specific verb and resource: 'Check the current PDFops API quota for the configured key.' It also enumerates the exact data returned (tier, limit, used, remaining, reset date), which clearly distinguishes this quota-checking tool from the sibling PDF-processing tools like pdf_fill and pdf_merge.

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

  Usage Guidelines4/5

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

  The description clearly states that this tool is for checking API quota, which is a distinct purpose among the siblings. It does not explicitly name alternative tools or state when not to use it, but the 'quota' concept makes the intended usage unambiguous.

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

• pdf_inspectA
  4.6/5.0
  Behavior5/5

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

  With no annotations, the description carries full behavioral burden. It discloses the no-form result ('count 0'), the hybrid XFA/AcroForm consequence, the fillTemplate generation, and the rejection behavior for over-maxLength values — none of which is visible in the schema or annotations. This is above and beyond what an annotations block would provide.

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

  Conciseness4/5

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

  The description is dense but organized: the core output list, the important XFA caveat, the no-form behavior, and the usage directive. A little redundancy appears ('you cannot fill fields whose names you do not know' restates the need for the field list), but each clause contributes useful operational context.

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

  Completeness5/5

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

  For a one-parameter tool with no output schema, the description covers the returned data, the edge case of a formless PDF, and the critical consequence for pdf_fill. It gives an agent everything needed to decide when to call this tool and what to expect from it.

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

  Parameters3/5

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

  Schema coverage is 100% and the only parameter, pdf_path, already has a clear description ('Absolute path to the PDF to inspect'). The tool description adds no extra parameter-level meaning beyond reinforcing that the path targets the PDF to inspect, so the baseline 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb and resource: 'List a PDF's AcroForm form fields' and enumerates the exact outputs (names, types, options, current values, maxLength, fillTemplate, hasXFA). It clearly distinguishes this as the inspection sibling that feeds pdf_fill, rather than merging, invoicing, or usage meta-tools.

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

  Usage Guidelines5/5

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

  Explicitly states when to use it: 'Call this FIRST when filling an unfamiliar PDF' and gives the rationale: field names must be known and over-maxLength values are rejected. This makes the sequencing against pdf_fill unambiguous, while the sibling list reinforces that it is the pre-fill step.

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