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

With no annotations provided, the description carries the full burden. It discloses the billed nature, credit consumption rate, watermark on free plans, PDF output format, JSON metadata return, base64 PDF resource, and API endpoint mirror. This is comprehensive and leaves no critical behavior unstated.

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 information-dense and well structured, leading with the core function, then billing, then output, then validation guidance. It is slightly repetitive in places (mentions credits and validation more than once) but every sentence adds useful information for an agent deciding whether and how to call the tool.

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 has a nested options object, no output schema, and no annotations, the description provides all essential context: what it produces, how it bills, how to validate first, what metadata is returned, and how it relates to sibling tools. An agent has enough information to call it correctly and interpret the result.

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 covers markdown and options with descriptions, and the description adds valuable context such as the 200-character limit, optional metadata usage, and fallback to YAML frontmatter for omitted options. It does not need to repeat every field because the input schema is already well-described, but the added context raises it above the baseline.

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 renders GitHub-flavored markdown to a tagged PDF/A-2A + PDF/UA-1, and explicitly distinguishes itself from preview/template tools by noting there is no free preview and that it is the only markdown render tool. This gives an agent a precise understanding of when to use it.

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 direct usage guidance: run validate_markdown first to catch issues before paying, notes the billing/credit model, explains watermark behavior on free plans, and contrasts with render_dsl_preview/render_template. The agent knows exactly how to proceed and when to avoid this tool.

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