pageguard-mcp

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

With no annotations provided, the description carries the full burden. It successfully discloses critical behavioral traits: pricing for each document type ($29/$49/etc.), credit consumption requirement, and AI-authored nature of outputs. It lacks details on error states (e.g., insufficient credits) or output format, but covers the essential cost and auth behaviors.

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 efficiently packed with no wasted words, front-loading the core purpose before listing prerequisites and pricing details. The document type list is dense but necessary. A 5 would require better visual separation between prerequisites and pricing, but it earns high marks for information density.

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 comprehensively covers inputs, costs, and prerequisites, but omits what the tool returns (e.g., download URL, raw text, file ID) despite having no output schema. For a paid document generation tool, this output gap is a significant omission, though the input documentation is thorough.

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?

Despite 100% schema coverage (baseline 3), the description adds substantial semantic value by explaining what each documentType actually contains and costs—information absent from the schema. For example, it clarifies 'single' means '$29 — privacy + terms + cookie' while 'bundle' means '$49 — everything', which is crucial for correct invocation.

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 'Generate[s] AI-written legal compliance documents' with specific examples (privacy policy, terms of service) and context (for a previously scanned site). It uses a specific verb+resource combination and implicitly distinguishes from sibling scan tools by noting the 'previously scanned site' requirement.

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 provides clear prerequisites: 'Requires a scanId from a prior URL scan' and 'PAGEGUARD_API_KEY with available credits'. This effectively signals when to use the tool (after scanning) and what is needed. It could explicitly name the sibling tool (pageguard_scan_url) to use first, but the guidance is sufficiently clear.

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