ordinals_marketSales

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the tool 'retrieves recent sales data' and 'provides insights into market activity,' which implies a read-only operation, but doesn't explicitly state this is a query tool with no side effects. It also doesn't disclose rate limits, authentication requirements, data freshness, or pagination behavior (though pagination parameters exist in the schema). The description adds some behavioral context about what data is returned but leaves significant gaps.

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 appropriately sized with three sentences that each add value: first states core purpose, second explains what insights are provided, third describes filtering capabilities and use cases. It's front-loaded with the main purpose and avoids unnecessary repetition. Some minor wordiness exists ('to help analyze market trends and track specific token sales' could be tighter).

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 moderate complexity (8 parameters in a nested structure, no output schema, no annotations), the description provides basic purpose and filtering context but is incomplete. It doesn't explain the return format, pagination behavior, default tokenType, or what 'recent' means temporally. For a sales data retrieval tool with rich filtering options, more contextual information would be helpful despite the lack of output schema.

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 description mentions filtering 'by token ID, ticker symbol, or seller address' which maps to three of the eight parameters (id, tick, address). However, with 0% schema description coverage, the description doesn't compensate for the undocumented parameters (dir, limit, offset, pending, tokenType). The description adds some semantic value for three parameters but leaves five completely undocumented beyond the schema structure.

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 'retrieves recent sales data for BSV-20 and BSV-21 tokens on the ordinals marketplace' with specific verbs ('retrieves', 'provides insights') and resources ('sales data', 'BSV-20 and BSV-21 tokens'). It distinguishes from siblings like ordinals_marketListings (which likely shows current listings rather than completed sales) and ordinals_getTokenByIdOrTicker (which retrieves token metadata rather than sales data), though the differentiation could be more explicit.

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 implies usage context by stating it 'helps analyze market trends and track specific token sales' and mentions filtering capabilities, but doesn't explicitly state when to use this tool versus alternatives like ordinals_marketListings or bsv_getPrice. It provides some guidance through the filtering mention but lacks explicit when/when-not instructions or named alternatives.

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