PDFShift

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

With no annotations supplied, the description carries the full behavioral burden, and it does disclose one important trait: the result is a temporary download URL valid ~2 days. However, it says nothing about credit consumption (only the `sandbox` schema field hints at credits), authentication, rate limits, or whether failures still consume credits.

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, zero waste, with the conversion capability front-loaded and the return value immediately after. Nothing could be removed 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?

For an eight-parameter, mutation-free but credit-bearing tool with no annotations and no output schema, the description covers purpose and the return artifact well. It leaves the cost model and the sandbox-versus-paid decision unexplained, which is a meaningful gap an agent would need when choosing call settings.

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 every one of the eight parameters is already documented, including the format enum and the sandbox/credit tradeoff. The description merely repeats the format list, adding no new meaning such as default behavior or interactions between `wait_for`, `delay`, and `css`; baseline 3 applies.

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

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

States a specific verb ('Convert') and both the accepted inputs (HTML document or URL) and all four output formats, so the agent knows exactly what the tool produces. It stops short of naming siblings only because none of them overlap (create_template, list_logs, pricing, etc.), so the tool is still unambiguously identifiable.

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 on when to prefer this over alternatives, when to use a URL versus raw HTML, or when the sandbox mode is appropriate. The agent must infer everything from the schema property descriptions rather than from the description itself.

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

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

No annotations are supplied, so the description carries the full behavioral burden, yet it discloses nothing about permissions, whether the slug must be globally unique or what happens on collision, or whether creation is reversible. For a mutation tool with zero annotation coverage, this is a substantial gap; only the word 'reusable' hints at intended semantics.

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 efficient sentence with the action front-loaded and no filler. It is concise to the point of under-specification, but nothing in it is wasted.

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

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

This is a create/mutation tool with no annotations and no output schema, so the description should explain uniqueness handling, required permissions, and what is returned (e.g., the created template or its id). None of that is present, leaving the agent underprepared to call it correctly in 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 description coverage is 100%, so name, slug, and content are already documented, and the baseline of 3 applies. The description adds no format detail (e.g., slug character rules, HTML constraints) beyond what the schema states.

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 ('Create a new reusable HTML template'), which is unambiguous for an agent. It does not differentiate from siblings like update_template (modify existing) or generate_from_template (render output), 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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as update_template or generate_from_template. The agent must infer from the name alone that this creates rather than modifies.

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 supplied, so the description carries the full disclosure burden; 'Get' implies a read-only operation, which is the main behavioral signal. It usefully discloses the three return values in the absence of an output schema, but says nothing about authentication requirements, rate limits, or the scope/granularity of the account balance.

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 sentence with zero filler, front-loaded with the verb and resource, and the parenthetical return-field list is compact and useful. Nothing could be removed 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?

For a zero-parameter read tool with no output schema, the description covers purpose and enumerates the return fields, which is most of what an agent needs. Minor gaps remain around freshness of the 'current' value and account scoping, but the definition is adequate for a tool this simple.

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 tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema already conveys. Baseline for a parameterless tool is 4, but the parenthetical field list is the only added meaning, so a 3 reflects genuinely minimal semantic contribution.

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

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

The description names a specific verb and resource ('Get the current credit usage for the account') and enumerates the returned fields (remaining, total, used). It is clearly distinct from sibling tools like list_templates or convert, though it does not explicitly contrast with 'pricing', the nearest neighbor.

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

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

There is no statement of when to use this tool versus alternatives such as 'pricing'. The word 'current' hints at a live snapshot, but the agent must infer whether this is a real-time balance check or a billing-plan lookup, and no prerequisites or exclusions are given.

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

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

No annotations are supplied, so the description carries the full behavioral burden for a destructive operation, and it discloses almost nothing. It does not say whether deletion is permanent/irreversible, whether templates in use by generated documents are protected, what permissions are required, or what the response contains on success or failure.

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?

One short sentence with the resource and key front-loaded and no filler. There is no wasted wording, though the terseness comes at the cost of the behavioral detail noted above rather than being a model of efficient completeness.

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 structurally simple (one required string), which lowers the bar, but it is a destructive, irreversible-class operation with zero annotations and no output schema. An agent needs to know about permanence, permission requirements, and failure modes before invoking it, and none of that is present.

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% and the single slug parameter is documented in the schema itself as "The template slug to delete." The description's "by its slug" restates rather than extends that, so the baseline of 3 applies — no format examples (e.g., where to find the slug) are added.

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?

"Delete a template by its slug" gives a specific verb (delete) and resource (template) plus the identifying key. It's clearly distinguishable from siblings like create_template, update_template, and get_template via the verb, though the description itself doesn't explicitly name or route to those alternatives.

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

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

There is no guidance on when to use this versus update_template or get_template, no prerequisites, and no note about what happens if the slug doesn't exist. The agent must infer that this is the removal path purely from the verb.

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 exist, so the description carries the full burden. It does disclose the important behavioral split: document formats return a temporary download URL while HTML returns markup, which tells the agent what it will receive. It says nothing about permissions, URL expiry duration, failure modes, or rate limits, leaving real gaps for a no-annotation tool.

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

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

Three short sentences, front-loaded with what the tool does, followed by the return-value distinction and the variable-passing convention. No filler or repetition of the schema.

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

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

With no output schema, the description usefully explains the two return shapes (download URL vs markup), which is the most important thing an agent needs. Missing pieces are preconditions such as authentication and whether a slug must exist, but the core call semantics are covered for a two-parameter tool.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description explains something the schema cannot: the meaning of additionalProperties=true, namely that template variables and conversion options are passed as extra top-level properties. That is genuine semantic value beyond the structured fields.

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

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

States a specific verb and resource (render a saved template) and enumerates every supported output format. It does not differentiate from the sibling 'convert' tool, which an agent might reasonably pick instead, so it stops short of a 5.

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

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

There is no explicit when-to-use guidance and no mention of the closely related 'convert' or 'get_template' siblings. The only guidance offered is procedural ('pass template variables ... as extra properties'), which is invocation mechanics rather than tool selection.

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 disclosure burden, and it only conveys that the operation returns one log. It says nothing about not-found behavior (error vs. empty), permission/auth requirements, or whether the record is a snapshot versus live data — all things an agent would want before calling a bare lookup with no safety hints.

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 front-loaded sentence with no filler; the key qualifier 'single' appears early. Its brevity is clean rather than padded, though the terseness is part of why other dimensions have gaps.

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 lookup with no output schema and no annotations, the description covers the essential contract: what it fetches and by what key. It remains silent on failure modes and return shape, which is a real but modest gap at this complexity level.

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

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

There is only one parameter and schema coverage is 100%, with the schema already documenting request_id as 'The request id of the conversion.' The description's 'by its request id' adds no format, source, or disambiguation detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a single conversion log') and narrows scope with the qualifier 'single', which implicitly separates it from the sibling list_logs. It stops short of naming that sibling, so the differentiation is inferable rather than explicit.

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 'by its request id' hints that a known request id is the precondition, but there is no explicit when-to-use statement, no when-not, and no routing to list_logs for the case where the agent lacks an id or wants more than one record. For a lookup tool whose main alternative is a sibling list, that omission matters.

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 supplied, so the description carries the full behavioral burden, and it discloses only that the return value is raw HTML. It says nothing about behavior for an unknown slug, permissions or authentication requirements, response size limits, or whether the template must be published.

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 front-loaded sentence with verb, resource, return type, and lookup key, and no wasted words. Nothing in it could be trimmed 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?

For a one-parameter read tool with no output schema, the description gives the essential shape (raw HTML keyed by slug), which is the minimum viable amount. It is still thin on error behavior and on how an agent should discover valid slugs, which matters given the many sibling template tools.

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

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

Schema coverage is 100% and the single slug parameter is already documented in the schema, so the baseline is 3. The phrase 'by its slug' confirms the slug is the lookup identifier but adds no format or constraint detail 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 states a specific verb (get) and resource (raw HTML content of a template) plus the lookup key (slug), which clearly separates it from list_templates and generate_from_template. It does not explicitly name which sibling to use instead for generated/rendered output, so it falls just short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. An agent must infer from the word 'raw' that this is for source HTML rather than generated or converted output, and nothing says how to obtain a valid slug (e.g., via list_templates).

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, the description carries the full behavioral burden and does little: it does not state that the tool is read-only, that results are paginated via cursor, what 'recent' means in time or count, or in what order logs are returned. Only the account-level scoping is disclosed.

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 front-loaded sentence with no redundant wording. It is efficient, though the brevity edges into under-specification rather than disciplined concision.

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 four-parameter, paginated listing tool with no annotations and no output schema, the description should explain the recency window, pagination behavior, and relationship to get_log. None of this is present, leaving meaningful gaps an agent must guess at.

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 every parameter (key, limit, cursor, status) is already documented with defaults and ranges. The description adds nothing beyond implying filtering and recency, so baseline 3 applies.

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

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

States a specific verb ('List') and resource ('conversion logs') scoped to the account, so an agent understands the operation. However, it does not distinguish itself from the sibling get_log (singular), leaving the agent to infer that this is the multi-record variant.

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

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

There is no explicit when-to-use guidance, no mention of when to prefer get_log over this tool, and no explanation of how the filters (status, key) should drive selection. The word 'recent' implies a bounded window but that boundary is never defined.

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 supplied, so the description carries the full behavioral burden. "List all" usefully discloses that no filtering or pagination is applied, but it says nothing about required permissions, whether archived/deleted templates are included, or what identifying fields come back.

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 front-loaded sentence with no redundant or filler wording. The scope qualifier is placed where the agent will read it first.

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 list tool with no output schema, this is close to complete: the agent knows it enumerates every template on the account. The remaining gap is that with no output schema present, the description could have hinted at the shape of the returned template objects.

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 tool takes zero parameters, so there is no parameter meaning to convey and the baseline of 4 applies. Nothing in the description misrepresents the empty input schema.

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

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

States a specific verb and resource ("List all saved HTML templates") plus the scope ("for the account"). It is clearly distinguished from mutation siblings like create_template or delete_template, though it does not explicitly separate itself from get_template, which presumably returns one template.

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 word "all" implies this is the enumeration path when no specific template is known, which is adequate implied guidance. However, there is no explicit instruction such as using get_template for a single template's full contents, so the agent must infer the choice.

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 at all, the description carries the full behavioral burden fairly well: it discloses the returned fields, states that account-specific custom plans appear only when the caller is authenticated, and implies a safe, side-effect-free read. It does not address rate limits, error behavior when unauthenticated, or whether results are paginated, which keeps it short of a 5.

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

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

Two sentences, zero filler, with the core purpose leading and the authentication caveat following. Every clause conveys information an agent would otherwise lack.

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?

There is no output schema, so the description must convey the return contents itself, and it does by enumerating credits, price, overage, and billing period. With no parameters and no annotations, the remaining behavioral surface is the auth-dependent inclusion of custom plans, which is stated.

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 tool takes zero parameters, so the parameter-semantics baseline is 4. The description correctly implies no input is required and adds nothing that could conflict with the empty 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?

"List the available PDFShift plans and their pricing" names a specific verb and resource, and the parenthetical enumerates the fields returned (credits, price, overage, monthly/yearly). It does not distinguish itself from the nearby credit-related sibling credits_usage, so an agent must infer the boundary, but the purpose itself 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?

Usage is only implied: an agent can infer this is the way to answer "what does it cost / what plans exist." The only explicit condition given is "when authenticated" for custom plans, and no alternative tool (e.g. credits_usage for consumed credits) is named or excluded.

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 supplied, so the description carries the full burden of behavioral disclosure and largely drops it. It does not say whether existing content is overwritten or lost, whether the update is partial or full-replacement, whether permissions are required, or whether prior versions are recoverable. The only behavioral hint is 'and/or', which suggests field-level optionality but conflicts with the schema making content required.

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 front-loaded sentence with the verb, resource, and mutable fields in order. There is no redundant filler and nothing 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?

This is a mutation tool with no annotations and no output schema, so the description is the only place to learn about overwrite semantics and required permissions, and it covers neither. An agent could call it correctly by shape but not confidently predict the side effects of replacing HTML content.

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 100% with per-parameter descriptions ('New name.', 'The template slug to update.', 'New HTML content.'), so the baseline of 3 applies. The description's 'name and/or HTML content' phrasing adds a small optionality nuance but actually blurs the fact that content is a required parameter, so it does not add reliable meaning 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 gives a specific verb and resource ('Update ... an existing template') and names the mutable fields (name, HTML content), which distinguishes it from create_template and delete_template in the sibling list. It stops short of explicitly naming those siblings as alternatives, so it is clear but not fully differentiated.

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

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

Usage is only implied: the word 'existing' plus the verb 'update' signals this is for modifying a template that already exists rather than creating one. There is no explicit statement of when to choose this over create_template or generate_from_template, and no prerequisites or caveats are given.

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