Paid research outline (0.01 USDC Base · first pay). Free first: x402_sample_outline. Body {topic}. Without paymentHeader returns 402 + accepts[].
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Topic or https URL | |
| paymentHeader | No | Optional X-PAYMENT proof after settling USDC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool requires payment, that omitting paymentHeader results in a 402 error with an accepts array, and that the topic should be in the body. With no annotations, it carries the transparency burden but does not mention the output format or any other side effects.
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, using a single sentence with key points separated by periods. It is front-loaded with the core purpose. However, the structure is slightly cryptic (e.g., 'Body {topic}' could be misinterpreted).
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 (payment flow) and lack of output schema, the description is insufficient. It does not describe what a successful response contains, any rate limits, or detailed payment process, leaving the agent with significant uncertainty about the tool's behavior.
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 describes both parameters (topic and paymentHeader) with 100% coverage, so the baseline is 3. The description adds value by explaining that topic should be placed in the request body and that paymentHeader is used for payment proof, clarifying usage beyond 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 it is a paid research outline tool, mentions the cost (0.01 USDC), and distinguishes itself from the free alternative x402_sample_outline. However, it could be more explicit about the exact resource being created.
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 suggests using the free sibling tool first and explains the error response when paymentHeader is missing. However, it does not specify when to use this tool over other paid siblings like x402_research_brief, leaving the agent without complete guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a distinct primary purpose (discovery, health, free sample, paid outline, paid brief, alternative scrub), but the conversion ladder is mentioned in multiple tools, which could cause slight confusion for an agent about which free tool leads where.
All tools consistently use the 'x402_' prefix followed by a descriptive compound noun (e.g., discovery, health, research_brief, sample_outline), creating a predictable and clear naming pattern.
With 6 tools, the set is well-scoped for a research API with a free-to-paid conversion ladder, covering all necessary stages without superfluous or missing tools.
The tools cover the complete research generation flow (discovery, health check, free sample, paid outline, paid brief), with an alternative scrub demo. A minor gap is the absence of a history or status tool for previously generated research.
