clean_markdown_for_llm

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 does reveal the core transformation (stripping trackers/ads) and explicitly discloses the paid nature (0.005 USDC on Base L2), which is valuable. However, for a tool that processes potentially untrusted HTML, it omits security-relevant behavior (script execution, sanitization guarantees, aggressiveness of stripping) and leaves the input/output contract ambiguous.

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?

A single sentence delivers the full value: main action front-loaded ('Strips trackers and ads'), transformation target second, and the cost note appended last. There is zero waste and every clause earns its place. Excellent structure for quick agent scanning.

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 paid, security-sensitive HTML-processing tool with no annotations, no output schema, and no return-value description, this is thin. It fails to explain the payment flow behind the required-style paymentSignature param, leaves the payload format ambiguous (raw HTML string vs. JSON wrapper), and never says what the output looks like. More context is needed than a one-line transformation statement.

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. The schema's payload description ('Input parameters or JSON string payload') is generic, and the description's 'raw HTML' claim adds meaning by suggesting the payload carries HTML content. However, this creates a genuine mismatch: the description says raw HTML is the input while the schema frames payload as a JSON parameter string, leaving the actual expected format unresolved. The description does add the cost context relevant to paymentSignature.

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 states a specific transformation: strips trackers/ads and converts raw HTML into token-optimized Markdown. It names the input (raw HTML), the verb (strips/converts), and the output format (Markdown for LLM ingestion), which clearly differentiates it from sibling sanitizers like strip_prompt_injection and sanitize_sql_query, and even from the nearest HTML-focused sibling html_clean_boilerpipe_extractor by specifying the Markdown output target.

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 use case is implied through the purpose ('for dense LLM ingestion' signals when to reach for it), but the description gives no explicit exclusions, prerequisites, or named alternatives. With a near-competitor sibling (html_clean_boilerpipe_extractor) available, explicit routing guidance would materially help an agent, so this is implied usage at best, not clear-context-with-alternatives (4).

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