makespdf

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

With no annotations, the description carries full behavioral burden. It adds meaningful context: the ownership requirement, the library-row restriction, and the HTTP endpoint mirror ('Mirrors DELETE /api/v1/templates/:id'). It stops short of stating that deletion is permanent/irreversible or what error occurs for a library/unknown ID.

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 the core action, followed by the key exception and endpoint reference. No filler or redundant restatement.

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 delete operation with no output schema, the description covers target, ownership, library exclusion, and API semantics. It lacks explicit failure/response behavior and permanence wording, but those are partially implied by 'DELETE'. Slightly more detail would make it fully complete.

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

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

Schema coverage is 0%, so the description must compensate. It does: 'by ID' ties the single parameter to the resource identity, and 'caller-owned' plus 'Library rows cannot be deleted' adds constraints on what that ID can represent. The schema only defines templateId as a string, so this is real added meaning.

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?

Description uses a specific verb and resource: 'Delete a caller-owned template by ID.' It also draws a clear boundary with 'Library rows cannot be deleted,' which distinguishes this deletion operation from other template operations and tells the agent exactly what kind of template is in scope.

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 intended use is clear: delete a template that the caller owns, and do not attempt to delete library templates. It does not name an alternative tool, but deletion is unique among the siblings so an explicit alternative is unnecessary. A small gap is that it never states what to do instead for library rows.

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?

The description uses 'Fetch' and 'Mirrors GET', which strongly implies a read-only operation with no side effects. However, since no annotations are provided, the description carries the burden, and it does not explicitly mention error behavior, permissions, or lack of mutation. Overall it is fairly transparent but not exhaustive.

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

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

The description is concise—two sentences—and front-loads the core action. Every word adds value: the resource, the scope, the return payload, and a useful API reference. No filler or redundancy.

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 simple fetch tool with a single parameter, the description covers the essential context: what is fetched, what is included in the response, and how the parameter is interpreted. It does not need to explain return schemas or error codes for this level of complexity.

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 parameter description goes beyond the schema's type string by explaining the two possible formats (slug for library rows, UUID for user rows) and provides a concrete example. This gives the agent clear, actionable guidance for constructing valid calls.

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

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

The description clearly states the action ('Fetch') and the resource ('a single template'), and specifies that it returns the full DSL source and sampleData. The phrase 'library or caller-owned' and the focal 'by ID' effectively distinguish it from list_templates, making the purpose 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?

The description implies usage for retrieving a specific template by ID, but it does not explicitly state when to prefer this over alternatives. It references the REST endpoint but provides no direct guidance on when not to use it or when to use list_templates instead. This leaves some room for interpretation.

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

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

With no annotations provided, the description carries the full burden and does so well. It discloses that the operation is a read-only list, returns metadata only, is paginated, and has specific owner-filter semantics including the default 'all' behavior. The note 'Mirrors GET /api/v1/templates' reinforces the non-mutating, list-oriented 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?

The description is compact but information-dense: three sentences cover purpose, scope, return nature, pagination, owner modes, filters, and the equivalent API endpoint. Every clause contributes useful guidance, with the most important behavioral constraint ('Metadata only') placed early.

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 read-only list tool with no annotations and no output schema, the description covers what an agent needs to invoke it correctly: what is listed, who can see it, what is returned, how filtering works, the default owner mode, and pagination. The only minor omission is explicit guidance about when to switch to get_template for full DSL bodies, but the metadata-only statement and sibling list make this reasonably inferable.

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?

Since schema description coverage is 0%, the description must compensate for missing parameter semantics. It adds meaning for q (free-text over name and description), tags (comma-separated and ANDed), owner (all three enum values with default behavior), and category. It mentions pagination but does not explicitly describe how limit and offset behave beyond what the schema already shows via defaults and constraints.

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

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

The description clearly states a specific verb and resource: 'List templates visible to the caller', and further defines the two included scopes (library templates and the caller's saved templates). It distinguishes itself from siblings by explicitly noting 'Metadata only (no DSL bodies)', so an agent can tell it apart from get_template, delete_template, and render tools without needing to open their schemas.

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

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

The description provides clear context on how to use the tool: listing visible templates, filtering by owner, category, tags, and free-text q, with pagination. It does not explicitly name an alternative like 'use get_template when you need the DSL body,' but the 'Metadata only (no DSL bodies)' note implicitly communicates when this tool is not appropriate, and sibling names help fill the gap.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the cost model (free/no credits), the always-on watermark, and the return format (JSON metadata plus PDF bytes as base64). It stops short of stating side-effect behavior or error conditions, but 'preview' and the endpoint reference imply a non-destructive render.

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, each earning its place: the action, the constraints/cost, and the output format/endpoint. There is no filler, repetition, or unnecessary detail, and the key preview semantics are front-loaded.

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

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

The description covers the essential context: what the tool does, cost, watermarking, and return value shape. Since there is no output schema, the explicit statement of 'JSON metadata plus the PDF bytes as an embedded base64 resource' is important and present. It does not address error cases or prerequisites, but those are minor for a simple preview 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%, so the baseline is 3. The description mentions 'DSL template + data' in prose but adds no parameter-specific meaning beyond what the schema already documents; the schema itself covers dsl, the data fallback to sampleData, and title metadata.

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 ('Render') and resource ('a DSL template + data to a preview PDF'), making the core action unambiguous. It also distinguishes itself from the sibling render_template by emphasizing 'preview', the watermark, and the explicit endpoint reference 'POST /api/v1/preview'.

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

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

The description gives clear usage context: it is free, consumes no credits, always watermarked, and explicitly marked 'PREVIEW — NOT FOR USE', which implies it should not be used for production output. However, it does not explicitly name the alternative render_template or state the condition that should select the production render, so the guidance is contextual rather than fully explicit.

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

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

With no annotations provided, the description carries full behavioral disclosure. It flags that this tool is 'BILLED', explains the credit rate, mentions free-plan watermarks, describes the JSON metadata returned, and notes the PDF bytes are embedded as base64. This is unusually transparent for a mutation/billing operation.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose and the critical billing warning, then covers return format, watermarking, API shape, and the recommended alternative workflow without wasted words.

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, yet the description explicitly lists the return metadata fields (pageCount, creditsDeducted, creditsRemaining, artifactId) and the embedded base64 PDF. It also covers billing consequences, free-plan behavior, and the recommended preview workflow, making this fully complete for an agent deciding whether and how to invoke the 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?

The schema already documents all three parameters at 100% coverage, so the high-coverage baseline of 3 applies. The description adds little beyond the schema for parameters, aside from noting the API body shape mirrors '{ templateId, data }', which is marginal. It does not introduce missing parameter details, but it also doesn't need to given the schema's completeness.

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 uses a specific verb ('Render') and resource ('any readable template — curated library row or caller-owned') and clearly states the output: 'a real PDF'. It distinguishes this from sibling tools by emphasizing the paid rendering path versus the free 'render_dsl_preview', so an agent can immediately tell what this tool does.

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 explicitly instructs the agent to use 'render_dsl_preview' first for free, watermarked layout confirmation, and says to call this tool only 'once you're confident the template is right.' It also names the alternative directly and provides a clear selection criterion between paid rendering and free preview.

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

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

With no annotations provided, the description carries full burden. It discloses validation-before-persist, free (no credits), and the return shape { templateId, name, createdAt }. It also explains the sampleData round-trip behavior. Does not mention permissions or reversibility, but these are less critical for a save operation.

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 no filler. Purpose is front-loaded, and each sentence adds value: what it does, validation+free, and return shape. Efficient and well-structured.

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

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

Given no output schema, it explains the return object. It covers validation, cost, and the sampleData purpose. It does not mention error handling (e.g., what happens if validation fails) or idempotency, but those are minor for a save tool. Overall complete enough for an agent to call it 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 coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains sampleData's role in preserving binding shape and its round-trip on /ai/chat, and it clarifies that description is surfaced on /templates. These go beyond the schema descriptions.

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+resource ('save a user-owned DSL template') and its purpose (reuse via /api/v1/render), clearly distinguishing it from siblings like get_template, update_template, and delete_template. The mention of validation and free usage adds specific scope.

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?

Implies when to use (saving a new template for later render) and provides context about the modify-template flow on /ai/chat that uses sampleData, but does not explicitly name alternatives or state when not to use it (e.g., vs update_template). Lacks explicit exclusions, so not 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?

With no annotations provided, the description carries the full burden of disclosing behavior. It does disclose helpful side effects like DSL revalidation and null-clearing behavior, but it does not mention authentication requirements, idempotency, or other potential side effects of an update operation.

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

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

The description is concise and well-structured, using two sentences to convey the core action, field semantics, and key behavioral notes. There is no redundancy or unnecessary detail.

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 description is contextually complete for an update operation with no output schema: it specifies what can be updated, how to clear fields, and a key validation behavior. It could mention return values or error cases, but these are not required given the absence of an output schema.

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 only 40%, but the description adds meaningful semantics for dsl by noting revalidation, and for description and sampleData by explaining null-to-clear versus omit-to-keep behavior. It does not add detail beyond the schema for templateId or name, though those are relatively self-explanatory.

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

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

The description clearly states the verb 'update' and the resource 'saved template,' naming the specific fields affected: DSL, name, description, and sampleData. It distinguishes itself from sibling tools like save_template by focusing on updating an existing saved template rather than creating or retrieving one.

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

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

The description explains important usage semantics such as passing null to clear fields and omitting fields to leave them unchanged, and it notes that DSL is revalidated when provided. However, it does not explicitly state when to use this tool versus save_template or other sibling tools, leaving some inference required.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It usefully discloses that the tool runs catalog validation plus alt-text checks and that it performs no rendering, which is a meaningful behavioral trait. It does not explicitly state side effects or return behavior, but validation implies a non-mutating, read-only operation.

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

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

The description is four tight sentences with no filler. The main purpose is front-loaded, and each sentence adds value: validation scope, checks performed, cost/rendering behavior, and API mirror. This is an efficient, well-structured description.

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 description covers the tool's purpose, validation scope, performance characteristics, and API relation. With complete parameter schema and one required parameter, an agent can likely invoke it correctly. However, the description does not state what the validation result looks like (e.g., issues list, pass/fail), which is a minor gap given there is no output schema.

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%, with clear descriptions for dsl and data. The tool description adds general context about validation categories but does not add parameter-specific meaning beyond the schema's own descriptions. Baseline 3 is appropriate because the schema already documents the parameters.

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: 'Validate a PDF template DSL script.' It names exact validation dimensions (structure, tag/style correctness, accessibility) and distinguishes itself from preview/rendering tools with 'Cheap — no rendering.' This clearly differentiates it from sibling tools like render_dsl_preview and validate_markdown.

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

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

The description gives clear usage context by stating 'Cheap — no rendering,' which implies this is the lightweight validation path versus render_dsl_preview. It also signals API parity with 'Mirrors POST /api/v1/preview/validate.' However, it does not explicitly mention when to prefer this over validate_markdown or name alternative tools.

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 burden. The term 'Validate' and the phrase 'Cheap — no rendering' strongly imply a read-only analysis with no side effects, though it does not explicitly state that no data is modified. This is sufficient for a validation 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?

The description is concise and well-structured, covering the action, target, specific checks, a cost/behavior hint, and an API mirror reference in two sentences. No redundant information is present.

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 validation tool with a single parameter and no output schema, the description is complete. It mentions the API endpoint for traceability and gives a hint about performance, which is sufficient context for an agent to decide to call it.

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 schema description coverage is 100% for the single parameter, and it already specifies 'GitHub-flavored markdown source.' The tool description does not need to add further parameter details, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb (Validate), the resource (a markdown document), and the specific checks performed (PDF/UA-1 accessibility issues: heading hierarchy, missing alt text). It also distinguishes the tool by noting it is cheap and does not render, which helps differentiate from sibling template-management tools.

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

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

The description gives usage guidance by explicitly stating it is cheap and does no rendering, implying it should be used for quick validation without rendering overhead. While it does not name alternative tools for when not to use it, the context of siblings (template operations) makes the intended use clear.

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