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 adds important behavioral context: each requested format costs 1 render credit, and the tool returns hosted URLs (pdfUrl, pngUrl, shareUrl, expiresAt). This goes beyond the annotations and helps agents understand side effects and cost implications.

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 three sentences, front-loaded with the primary use case, followed by an exclusion and the return value summary. Every sentence adds value, and there is no repetition of schema details. It is concise yet comprehensive for orientation.

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 the tool's complexity (11 parameters, nested pageSetup object) but a fully documented schema, the description provides enough context for initial selection: it defines the core output (PDF + PNG + share page), mentions branding options, and states the return format and credits. It does not cover every nuance (e.g., Mustache templating, pageSetup defaults), but the schema fills those gaps, making this a complete high-level description.

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 input schema already documents all 11 parameters and nested objects in detail. The description adds minimal parameter info beyond naming logo, accentColor, font, header, and footer as branding fields, which is helpful but not substantial. It does not explain the Mustache templating in the 'data' parameter, but that is covered by 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 clearly states the tool's purpose: converting Markdown or HTML into branded PDF/PNG artifacts with logo, accent color, font, header, and footer. It uses specific verbs ('turns', 'create') and explicitly distinguishes itself from rendex_screenshot, preventing confusion with sibling 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 opens with 'Use this when...' and gives concrete triggers (user asks for a branded report, invoice, summary, or to convert Markdown/HTML to PDF/PNG). It also states a clear exclusion: 'Do NOT use to screenshot an existing URL (use rendex_screenshot)', naming the alternative tool.

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