Server Quality Checklist

Tool Scores

• update_template_metadataB
  3.2/5.0
  Behavior2/5

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

  The description is transparent about side effects, disclosing that expireAt 'can trigger immediate deletion' and that deployedAt affects which version Carbone renders. That said, these disclosures conflict with the annotations: destructiveHint=false, while the tool describes how to trigger immediate, permanent deletion of a template. The annotations signal 'safe, non-destructive update' while the description openly exercises a destructive path, forcing an agent to distrust one signal or the other.

  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?

  Three tight sentences with zero filler. The first sentence front-loads the metadata list and the next two highlight the two behaviorally significant fields. It earns a 4 rather than 5 because the 'deployment/expiration' phrasing under-sells the genuinely surprising bits (re-parenting, immediate deletion) that the description itself later references.

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

  Completeness3/5

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

  Given the medium complexity of an 8-parameter, 1-required tool with no output schema and no enums, the definition feels mostly complete: units, sentinels, and replace-vs-merge semantics are all covered. However, the description never surfaces the 'id' re-parenting parameter, and the capacity to delete or permanently alter version history is easy to miss. It's adequate for an agent that reads the schema—but that's the schema doing heavy lifting, not the description.

  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 parameter descriptions are rich: they document the special 'NOW' value (42000000000), time units (Unix seconds), and the difference between Template ID and Version ID. The tool description adds only marginal cross-cutting value, reminding the reader that deployedAt 'activates' and expireAt schedules deletion, but most of this is restated in the schema. With the schema carrying the load, this is a solid baseline 3.

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

  Purpose4/5

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

  The description states a clear verb+resource ('Update the metadata of a stored template') and enumerates the exact fields involved (name, comment, category, tags, deployment timestamp, expiration). The two follow-up imperative sentences about deployedAt and expireAt add behavior the field list alone wouldn't convey. It stops short of 5 because it doesn't explicitly distinguish itself from the sibling tools (e.g., upload_template, delete_template) and omits the re-parenting behavior of 'id' entirely.

  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 gives explicit parameter-level directives ('Use deployedAt to activate a specific version for rendering. Use expireAt to schedule or trigger immediate deletion.') which guide one aspect of usage well. However, there is no guidance on when this tool should be preferred over template- or document-level alternatives, no exclusions, and no prerequisites mentioned.

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

• upload_templateA
  4.2/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint false and idempotentHint false, indicating a mutating, non-idempotent operation. The description adds behavioral context by explaining versioning behavior (multiple versions under a single ID, deployedAt controls active version) and the accepted formats. This goes beyond the schema's parameter descriptions and adds value for invocation.

  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 two concise sentences that front-load the core purpose and workflow, then add versioning and format details without redundancy. Every sentence adds distinct information, making it efficient and well-structured.

  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 the rich schema with 100% coverage and an output schema, the description covers the essential workflow and versioning concept. It could mention the three accepted input forms (file path, URL, base64) but those are detailed in the schema's template parameter. Overall, nothing critical is missing for an agent to use the tool correctly.

  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 baseline is 3. The description itself does not elaborate on parameters beyond what the schema provides; it mentions versioning and formats already covered in schema property descriptions. No extra semantic details are provided in the description itself.

  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 clearly states the tool uploads and stores a reusable Carbone template, and distinguishes it from render_document by specifying that the returned Template ID is used for rendering. It also mentions versioning, which sets it apart from metadata-only tools like update_template_metadata. The verb and resource are specific and unambiguous.

  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 provides explicit workflow guidance: 'Once uploaded, use render_document with the returned Template ID.' It also hints at versioning usage with deployedAt controlling active version. However, it does not explicitly contrast with alternatives like list_templates or update_template_metadata, so it lacks 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.

• download_templateA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds valuable behavioral context beyond that: the distinction between template and version IDs, the side effect of outputPath writing to disk, the asAttachment behavior, and the behavior when sample:true is set (errors if no sample exists). This exceeds what annotations provide and helps the agent anticipate outcomes.

  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 two sentences. The first sentence names the purpose and file types, the second covers the version/sample options. Every clause earns its place—no fluff, no repetition of schema fields. The core purpose is front-loaded.

  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 tool with 4 parameters, no output schema, and rich annotations, the description covers all key behavioral variations: template vs version selection, sample download, outputPath side effects, and asAttachment fallback. Nothing an agent needs to correctly invoke this tool is missing—including error conditions for missing samples.

  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 documents all four parameters thoroughly. The description adds marginal value by restating the template/version distinction in prose, but it does not introduce new semantics beyond the schema. Per the rubric, a baseline of 3 is appropriate when the schema carries the full parameter documentation.

  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 states a specific verb and resource: 'Download the original source file of a stored Carbone template' and lists the file types (DOCX, XLSX, PPTX, HTML). It clearly distinguishes from siblings like render_document (which generates outputs) and upload_template (which creates templates). 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.

  Usage Guidelines4/5

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

  The description gives clear context for use: 'Use this to inspect, edit, or back up a template.' It differentiates between downloading the deployed version vs a specific version, and explains the sample option. However, it does not explicitly name alternative tools or state when NOT to use this tool, leaving some inference to the agent. Still, the guidance is specific and actionable.

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

• list_templatesA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely valuable behavioral context beyond that: cursor-based pagination mechanics, the tags API limitation, and the critical edge case that templates uploaded with versioning disabled appear with id = null and must be addressed via versionId in tools like delete_template and download_template. 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.

  Conciseness4/5

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

  Six sentences, front-loaded with the core purpose before any caveats. Each sentence carries a distinct fact—scope, filter dimensions, includeVersions behavior, pagination, tags limitation, and the null-id edge case—so there is no filler. Slightly long, but the two 'Note:' caveats convey non-obvious API behavior and earn their space.

  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 an 8-parameter tool with zero required params, the description covers the essential decisions: which filters exist, how to paginate large collections, when to include versions, what the API cannot do (tag filtering), and how to identify versioning-disabled templates, including cross-tool remediation. An output schema exists, so return-value shape is covered elsewhere. The only minor gap is filter-combination semantics (e.g., whether search and category compose), which is left to inference.

  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%, setting a baseline of 3. The description rises above that by aggregating the filter dimensions ('Filter by Template ID, Version ID, category, or upload origin'), giving usage guidance for includeVersions ('full version history of each template'), and framing limit/cursor as a strategy for large collections. It adds selection and combination context the schema's individual parameter docs do not.

  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 'List stored Carbone templates with filtering, search, and pagination' — a specific verb, resource, and capability set. It clearly distinguishes itself from siblings like list_categories and list_tags by targeting templates specifically, and it elaborates the title's bare 'List Templates' with scope ('stored') and operations.

  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?

  Gives clear operational context: filters (Template ID, Version ID, category, origin), cursor pagination for large collections, and when to use includeVersions. It also provides an explicit exclusion—'filtering by tags is not supported by the Carbone API — use list_tags to discover tags, then filter results manually'—which routes the agent to the correct sibling. It doesn't systematically address all sibling alternatives, but the guidance is strong and actionable.

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

• delete_templateA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds valuable context: it is a soft delete (marked for garbage collection), default delay of 24 hours, and the ability to use update_template_metadata for immediate deletion. This goes beyond annotations but could provide more detail on the garbage collection process.

  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 concise with only three sentences. The primary action is stated first, followed by key behavioral details and an alternative. No unnecessary words, well-structured.

  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 one parameter and no output schema, the description covers the core behavior (soft delete, two ID types) and provides an alternative tool. It is complete enough for an agent to select and use the tool correctly, though it could mention return behavior or error handling.

  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?

  The schema already has a detailed description of the templateId parameter (64-bit or SHA-256, effects of each type). The description adds the context of soft delete but does not introduce new parameter semantics beyond what the schema provides. With 100% schema coverage, the description does not need to repeat, but also does not add extra clarity.

  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 clearly states the primary action ('Delete a stored Carbone template') and specifies it is a soft delete. It distinguishes between deleting by Template ID (all versions) and Version ID (specific version), and contrasts with the sibling tool update_template_metadata for immediate deletion.

  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?

  The description provides explicit guidance on when to use this tool versus alternatives, including when to use update_template_metadata for immediate or scheduled deletion. It also explains the two deletion modes (by Template ID or Version ID), helping the agent choose correctly.

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

• get_api_statusA
  4.5/5.0
  Behavior4/5

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

  Annotations already convey readOnly, openWorld, and idempotent hints. The description adds that it returns the version and status message, which is consistent and provides additional context beyond annotations.

  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 concise with two sentences that are front-loaded with the main action. No unnecessary information, every sentence adds value.

  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?

  Given the simplicity (no parameters, output schema exists), the description covers the return values and use case adequately. No gaps for an effective health check tool.

  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?

  The tool has no parameters, and schema coverage is 100%. The description does not need to add parameter details; it appropriately focuses on the tool's purpose.

  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 clearly states it checks Carbone API health and version, with a specific verb and resource. It distinguishes itself from sibling tools which are document/template operations.

  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 explicitly says 'Useful for verifying connectivity and confirming which Carbone version is active,' providing clear context for when to use it. No exclusion is necessary as it is a unique tool.

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

• get_capabilitiesA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds valuable context: details on what is returned (formats, features, examples, links) and that it provides a summary. 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.

  Conciseness5/5

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

  Two sentences, front-loaded with core purpose and content summary. Every sentence adds value; no wasted words. Efficient and clear.

  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 discovery tool with no input parameters and no output schema, the description fully covers what the agent needs to know: what it does, what it returns, and when to call it. No missing information.

  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?

  No parameters required, and schema coverage is 100%. Baseline score of 4 is appropriate since no parameter info is needed, and description adds no extra burden.

  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?

  Description clearly states it returns a summary of Carbone capabilities, listing specific content (formats, features, examples, links). Verb 'Returns' and resource 'capabilities' are specific. Strongly distinguishes from sibling tools which are all action-oriented (convert, delete, render).

  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?

  Explicitly advises calling this first if unsure about Carbone capabilities. Provides clear context for initial discovery. Lacks explicit when-not-to-use or alternative tools, but the guidance is sufficient for an agent.

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

• list_categoriesA
  4.5/5.0
  Behavior3/5

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

  Annotations already provide readOnlyHint, openWorldHint, and idempotentHint, covering safety and behavior. The description adds context about categories being like folders but does not disclose additional behavioral traits beyond what annotations convey.

  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 consists of two concise sentences. The first states the action and scope; the second explains usage and context. Every sentence earns its place with no redundancy or fluff.

  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?

  With no parameters, comprehensive annotations, and an output schema (indicated), the description is fully sufficient. It explains the concept of categories, the list scope, and how to apply the results.

  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 no parameters, so the input schema fully defines the interface. The description does not add parameter-level detail, but the baseline for zero parameters is 4 per rubric.

  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 ('List') and resource ('all template categories'), and explains the purpose with examples. It clearly distinguishes from sibling tools like 'list_tags' by specifying 'categories' as organizational folders, not tags.

  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?

  The description explicitly states how to use the output: 'Use the returned names as the category filter in list_templates or upload_template.' This provides clear, actionable guidance for the agent.

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

• render_documentA
  4.5/5.0
  Behavior5/5

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

  Annotations only indicate read-only, open-world, and idempotent behavior, but the description adds substantial behavioral context: one-shot template upload stores nothing, async rendering POSTs renderId to a webhook, batch generation is always asynchronous, and returnLink is short-lived and one-time. It also discloses side effects like local file writing via outputPath and silent password-ignoring behavior of the ICE converter, all without contradicting 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.

  Conciseness5/5

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

  The description is five sentences long, front-loaded with the core purpose and two modes, then lists capabilities and the async requirement. Every sentence adds distinct information with no redundancy or filler.

  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?

  Given 26 parameters and no output schema, the description covers the essential selection and invocation criteria: two modes, the async/batch relationship, and the main capability set. The exhaustive parameter descriptions in the schema fill in all remaining details, so nothing critical is missing for an agent to invoke the tool correctly.

  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 baseline is 3; the description doesn't add per-parameter specifics beyond the schema. It summarizes capability areas like conversion, multilingual rendering, currency conversion, and PDF options, but those are already elaborated in each parameter's description. No additional parameter semantics are needed.

  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 states a specific action ('Generate a document') with an exact mechanism ('merging a Carbone template with JSON data'). It clearly distinguishes two operation modes (templateId vs template) and differentiates from upload_template by noting the one-shot mode stores no template. The title 'Generate Document' aligns perfectly with the described behavior.

  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 explicitly says when to use templateId ('previously uploaded template') versus template ('without storing a template'), and names upload_template + templateId as the alternative for reusable templates. It also states that async mode is required for batch generation. However, it doesn't explicitly contrast with the sibling convert_document for pure format-conversion use cases.

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

• list_tagsA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, openWorldHint=true. The description adds the key limitation about no filter support, which is behavioral context beyond annotations. No contradictions.

  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, front-loaded with main action, each sentence adds value. No fluff.

  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 zero-parameter tool with output schema present, the description covers purpose, definition, usage guidance, and a critical limitation, making it complete.

  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?

  No parameters exist, so baseline is 4. The description does not need to add parameter info as schema coverage is 100%.

  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 clearly states the tool lists all tags across templates, defines tags as free-form labels, and implicitly distinguishes from list_categories and list_templates by explaining the API limitation and manual filtering approach.

  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 specifies when to use: 'discover available tags' then 'call list_templates and filter manually', and notes that Carbone API does not support filtering by tag, providing clear alternatives.

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

• convert_documentA
  5/5.0
  Behavior5/5

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

  Annotations already set readOnlyHint, openWorldHint, and idempotentHint. The description adds significant behavioral detail: it clarifies that tags are NOT resolved, describes the ICE engine's limitations (e.g., silently ignoring password options), explains returnLink's short-lived one-time nature, and notes outputPath behavior. This goes well beyond the annotations and is transparent about side effects and caveats.

  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?

  Although lengthy, every sentence carries unique value. The structure is logical: general purpose → input forms → format lists → converter details → parameter walkthrough. It front-loads the core intent and uses bullet-like formatting within prose to keep information scannable. No redundancy or filler is present.

  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?

  Given the tool's complexity (9 parameters including nested objects and enums), the description covers all necessary aspects: supported input/output formats, converter engine trade-offs, security warnings, edge cases (like ICE ignoring PDF options), and delivery mechanisms. It even points to a full conversion matrix URL. There is no missing information a user would need to call the tool correctly.

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

  Parameters5/5

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

  Schema coverage is 100% with each parameter having a detailed description. The description adds depth: it explains the three input forms for 'file' (path, URL, base64), the meaning of each converter enum value, the formatOptions examples for PDF and images, and the reportName extension pitfall. This substantially enriches the schema's basic field descriptions.

  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 clearly states the tool's function: 'Convert any document to another format without storing a template.' It specifies the verb (convert), the resource (document), and the scope (format transformation). It also distinguishes itself from the sibling render_document by noting that Carbone tags are preserved, not resolved, which makes the purpose unmistakable.

  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?

  The description explicitly contrasts with render_document: 'Use render_document instead when you need data injection, translations, or batch generation.' It also provides guidance on converter engine selection (L, O, C, I) and notes when hardRefresh is needed (PDF→PDF with formatOptions). This leaves no ambiguity about when to choose this tool versus alternatives.

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