APITemplate.io MCP by usefulapi

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

Adds substantial behavior beyond the annotations: the per-call cost (1 generation of plan quota), the anti-retry policy, the fact that responses contain hosted URLs rather than file bytes, and the underlying POST /v2/create-image endpoint. None of that is derivable from the readOnly/openWorld/idempotent 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?

Front-loads the action, then cost, then caution, then endpoint in labeled segments. Four dense sentences, no filler, and the most decision-relevant facts (what it renders, what it costs) come 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?

With six parameters, no output schema, and a clear mutation profile, the description covers the missing pieces: return shape (URLs, not bytes), quota impact, and retry guidance. An agent has everything needed to invoke it correctly and safely.

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 is 3, but the description supplies a concrete overrides payload example ([{"name":"text_1","text":"Hello"},{"name":"image_1","src":"https://..."}]) that documents the free-form layer properties the schema leaves as additionalProperties with no enumeration.

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 ('renders one image') with the required template source ('from a saved image template'), and names the output formats (JPEG and PNG). The word 'image' cleanly separates it from the apitemplate_create_pdf family of siblings without needing to name them.

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

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

Gives a clear when-not rule ('Do not retry or repeat it unless needed; every call is counted') and points to apitemplate_get_account for quota context. It does not explicitly contrast itself against the PDF-rendering siblings, so the choice between this and create_pdf_from_html is left to inference.

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

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

Annotations only cover the safety profile (not read-only, non-idempotent, open-world). The description adds material facts they don't: it is synchronous, it returns a hosted URL rather than bytes, each call burns one plan generation, and calls should not be retried casually. That is exactly the extra context an agent needs for a metered, non-idempotent write.

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?

Front-loads 'WRITE:' and then 'COST:' so the two most decision-relevant facts come first, and the closing endpoint line is useful deployment context. The sentences are heavily parenthetical and dense, which slightly hurts scanability, but there is no filler content.

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 7-parameter, non-idempotent, metered write with full schema coverage, the description covers purpose, return shape (download_url), billing impact, and sync behavior. With no output schema, the explicit note that bytes are never returned fills the remaining gap.

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 (data, meta, filename, expiration, template_id, output_html, generation_delay) is already documented in the schema. The description only restates the data-key idea with an example (invoice_number, items), adding no syntax or constraints beyond the schema, 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 and resource ('renders one PDF from a saved PDF template and your JSON data') and pins down the output ('returns the hosted download_url, never the file bytes'). The phrase 'saved PDF template' implicitly separates it from the create_pdf_from_html/markdown/url siblings that build a PDF from other sources.

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?

Gives clear context for use: it consumes a saved template plus matching JSON keys, is synchronous, and points to apitemplate_get_account for quota. It also warns against unnecessary retries. It stops short of explicitly naming the alternative tools (create_pdf_from_html, create_pdf_from_url) and the conditions that would select them, so it falls short of a 5.

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

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

Annotations already declare readOnly=false, idempotent=false and openWorld=true, and the description adds genuinely new behavioral context on top: it discloses the return contract ("returns the hosted download_url (never the file bytes)"), the per-call quota cost, and an explicit non-idempotency warning against retrying. That is exactly the kind of cost/side-effect detail annotations cannot convey.

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

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

Three sentences with explicit WRITE and COST prefixes front-load the operation type, the return contract, and the quota impact before the endpoint reference. Every clause carries information an agent needs; there is no filler.

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

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

With 8 parameters, a nested settings object and no output schema, the description compensates by stating the return value (hosted URL, not bytes), the quota cost, and the non-idempotency caveat. Combined with full schema coverage on all parameters, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: it explains that Jinja2 placeholders in body are resolved from data, tying two separate fields together semantically. It adds nothing about css, settings, naming, or expiration beyond what the schema documents.

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

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

The description opens with a specific verb and resource ("renders one PDF from HTML") and immediately scopes it against siblings by stating "without a saved template", which separates it from apitemplate_create_pdf and apitemplate_create_pdf_from_markdown. It also names the exact endpoint (POST /v2/create-pdf-from-html), so an agent can distinguish it from create_pdf_from_url without opening any schema.

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

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

It gives clear usage context: this is a WRITE operation costing one quota generation, and it directs the agent to apitemplate_get_account for quota checks and warns against retrying. It does not name the sibling alternatives explicitly (e.g. when to prefer create_pdf_from_url over raw HTML), so the routing guidance is implied through "without a saved template" rather than stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, but the description adds materially more: the return is a hosted download_url and never the raw bytes, the call consumes one plan generation (pointing to apitemplate_get_account), and repeats are counted. This is exactly the non-obvious behavior an agent needs before invoking a billed write.

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 front-loaded, labeled sentences (WRITE, COST, endpoint) with no filler; the operation, cost model, and API path each earn their place. Nothing is restated from the schema or annotations.

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?

No output schema exists, so the description correctly fills that gap by naming the return (hosted download_url, not bytes). Combined with cost, retry, and endpoint disclosure for a tool with a deep nested settings object, an agent has everything needed to call it correctly and safely.

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 is 3, but the description adds a meaningful semantic link: Jinja2 placeholders in 'body' such as {{lang}} are resolved from 'data', clarifying how two separate parameters interoperate. It doesn't add detail on the settings/expiration knobs, which the schema already covers.

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 ('renders one PDF') and resource ('from Markdown'), with the 'from Markdown' scope inherently distinguishing it from the sibling create_pdf_from_html and create_pdf_from_url. It also names the mechanism (Jinja2 placeholders) so an agent knows exactly what input style is expected.

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?

Gives clear operational context: it's a WRITE, it costs 1 generation of quota, and it should not be retried or repeated unless needed. It does not explicitly route the agent to alternatives (e.g. use create_pdf_from_html for HTML), so sibling selection is left to the name rather than spelled out.

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?

Goes well beyond the annotations: discloses that APITemplate.io (not this server) fetches the page, that only a hosted download_url is returned rather than file bytes, that login-gated pages fail, and that each call consumes one plan-quota generation and should not be retried. This is exactly the kind of cost/idempotency context an agent needs for a non-idempotent billable write.

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?

Front-loads the operation (WRITE:), then limitations, then cost, then the underlying endpoint. Every sentence carries distinct information with no padding.

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?

Though there is no output schema, the description states the return value (hosted download_url, not bytes), the cost model, the auth/prerequisite limitation, and a non-idempotency warning. Nothing material for correct invocation is missing.

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 url, meta, filename and the nested settings. The description adds only the 'public http(s)' constraint on url, which is minor; baseline 3 is appropriate when the schema carries the parameter burden.

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 ('opens one public web page URL and prints it to a PDF') and clearly distinguishes itself from the from_html/from_markdown siblings by naming its input type. An agent can route to it without opening any schema.

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?

Gives clear use conditions and exclusions ('pages that need a login cannot be printed', 'Do not retry or repeat it unless needed'). It does not explicitly name the sibling to use when the source is HTML instead of a URL, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description goes further by naming the exact fields returned and mapping to the underlying 'GET /v2/account-information' endpoint, which is useful because no output schema exists. It stops short of noting rate limits or auth-error behavior.

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

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

Purpose is front-loaded, the returned fields are listed compactly, and the actionable directive is placed before the endpoint reference. Every clause earns its place with no filler.

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

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

With no output schema, the description compensates by enumerating the return fields, which is the key information an agent needs. It is nearly complete for this simple zero-param read; only edge-case behavior (auth failure, plan limits semantics) is unaddressed.

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 schema has nothing to document and the baseline is 4. The description correctly implies key-scoped invocation with no arguments.

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 the APITemplate.io account behind this key') and enumerates exactly what the response contains: plan, subscription status/period, and quota counters. This is unmistakably distinct from the create_*/list_* siblings.

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?

Gives an explicit usage trigger: 'Check api_remaining before generating,' which tells the agent when to call it in a workflow. No alternatives or exclusions are named, but no sibling overlaps this read-only account-information role.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the description's restatement of 'Read-only' earns little. What it does add is genuinely useful: the experimental status and the specific failure mode (errors for some accounts and image templates), which annotations cannot express.

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 tight sentences: the returned resource is front-loaded, the operational caveat follows, and the endpoint is appended. No filler.

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

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

There is no output schema, so the description carries the return-value burden itself and does so by naming HTML body, CSS and print settings, plus the failure condition. For a single-parameter read tool this is complete.

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

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

With one parameter at 100% schema description coverage, the schema already documents template_id's pattern and shows where to obtain it. The description adds no parameter-level 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 ('One PDF template's HTML body, CSS and print settings') and pins the exact endpoint (GET /v2/get-template), so the agent knows it retrieves a single template's source rather than a list. This cleanly separates it from the sibling apitemplate_list_templates.

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?

Gives clear context for use plus an important caveat: the endpoint is experimental and can return an error for some accounts or for image templates. It does not explicitly name a fallback sibling, but the warning tells the agent when to expect failure.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the description's 'Read-only' is redundant. However it adds genuine context beyond the annotations: results are ordered newest-first and records for deleted/expired files carry deletion_status, which tells the agent how to interpret and filter output.

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 dense, front-loaded sentence that leads with the verb and resource, followed by two short clarifiers. Given there is no output schema, enumerating the returned fields earns its space and nothing here is filler.

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

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

With no output schema, the description usefully compensates by listing return fields, ordering and deletion semantics, and the input schema covers all four filters. What is missing is account scoping, auth/rate-limit context, and a pointer that this is the lookup step after create_pdf/create_image.

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 limit, offset, template_id and transaction_type are already fully documented (including the 'offset + limit' pagination rule). The description's 'type (PDF, JPEG or MERGE)' describes a response field rather than adding meaning to the transaction_type parameter, so it does not go 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?

States a specific verb (List) and resource (PDFs and images generated so far) and even enumerates the returned fields, so an agent knows exactly what comes back. It never names a sibling or says how it differs from apitemplate_list_templates, so the differentiation is left to inference rather than stated.

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 mention of returning hosted file URLs hints that this is how you retrieve links after a generation call, but there is no explicit when-to-use, no statement that IDs/URLs from here feed other tools, and no guidance on choosing filters. The note about deletion_status is a small hint on how to interpret results rather than a usage rule.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the 'Read-only; templates are never changed' sentence largely repeats structured data. It does add modest value by naming the HTTP endpoint and listing which attributes come back, but says nothing about pagination behavior or result ordering.

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?

Front-loaded with the core action and scope, then the returned-field list, the downstream usage tip, the safety note, and the endpoint. Efficient overall, though the terse field enumeration reads like schema spillover rather than decision-relevant 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?

With no output schema, the description usefully enumerates the returned fields and notes the endpoint, and annotations cover the safety profile. It is nearly complete, missing only pagination/ordering expectations for a paged list endpoint.

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 every parameter (limit, offset, format, group_name, template_id) is documented in the schema, so the baseline of 3 applies. The description adds no filter syntax or pagination detail beyond what the schema already 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?

States a specific verb and resource ('List the templates of the account') plus scope ('PDF and image') and enumerates the returned fields, so an agent can distinguish it from apitemplate_get_template and the create_* siblings without opening a schema.

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?

Provides an implied workflow hint ('Use the template_id with the create tools'), which tells the agent why it would list templates. However, it never explicitly contrasts with the sibling apitemplate_get_template (fetch one template) or states when not to use it, so the routing guidance is only implied.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description adds the substantive facts an agent needs: it is a WRITE, source files are untouched, the result is a hosted primary_url rather than bytes, and each call consumes one plan generation (non-idempotent in practice). This is exactly the value-add structured fields cannot convey.

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

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

Dense and front-loaded with WRITE/COST labels, so the highest-value facts read first. The cost warning is slightly duplicated ('1 generation per call' followed by 'every call is counted'), which costs a little efficiency but nothing is truly 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?

With no output schema, the description correctly carries the return contract (hosted primary_url, never bytes), plus side effects, cost, and input constraints. An agent has everything needed to call it correctly and avoid wasteful repeats.

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 meta, urls, and expiration are already documented in the schema, and the description largely restates the urls ordering constraint. It does add the useful 'public http(s) URLs' requirement beyond the schema, but says nothing extra about meta or expiration, 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?

Specific verb (joins/merges) and resource (2-20 PDFs into one PDF), with the ordering constraint and the endpoint made explicit. An agent can distinguish this from the create_pdf* siblings immediately since those generate documents rather than combine existing ones.

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?

Gives clear context for correct invocation: PDFs must be public http(s) URLs, typically prior download_url values, passed in the required order, and it warns against gratuitous retries because each call bills quota. It does not, however, name an alternative tool or state when a different sibling (e.g., create_pdf_from_url) would be the right choice.

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