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

With no annotations, the description carries the full burden. It discloses what data is returned (constraints like leverage, decimals, etc.) and scope (asset classes, 24/7 trading), which is useful. However, it does not mention tool-level behavior such as response format, pagination, rate limits, or whether it's read-only (implied but not explicit). It also doesn't state any potential errors or edge cases. Adequate but not thorough.

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 a single dense paragraph with a run-on structure, packing a lot of information (constraints, asset classes, examples, trading hours). It front-loads the core purpose but is not well segmented. It could be broken into clearer points without losing information. It's not excessively long, but its structure hampers quick 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?

Given there is no output schema, the description should explain what the response looks like, but it doesn't. It mentions the content (constraints) but not the structure (e.g., list of objects, fields). It also doesn't explain how to use the 'limit' and 'category' parameters to filter or paginate. The description provides good context on available markets but is incomplete for calling the tool effectively.

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% but the parameter descriptions are vague ('Limit to process' and 'Category to process'). The tool description does not elaborate on how 'limit' or 'category' affect results, nor does it define valid values. The mention of asset classes (equities, crypto, indices, commodities) hints at possible 'category' values but never explicitly maps them. The description adds minimal value beyond the schema's weak descriptions.

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 lists every market tradable on Polymarket Perps along with trading constraints. It specifies the resource (markets) and the action (retrieving definitions), and distinguishes itself from the sibling x402-polyperp-quotes for live prices. The purpose is unambiguous and specific.

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 explicitly directs users to x402-polyperp-quotes for live prices, providing a clear alternative. It also frames the tool as necessary before sending an order, implying when to use it. However, it doesn't explicitly state when not to use it or mention other sibling tools (e.g., x402-polyperp-book, x402-polyperp-trades) that might be alternatives for different data needs.

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