alt_asset

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses a key limitation ('recent_sales has no per-transaction grade breakdown -- Alt's own API does not expose one'), clarifies the data source ('Credential-free public data from Alt's own GraphQL API'), and explains the aggregation scope ('across every grading company and grade Alt tracks'). It does not mention pagination or time ranges, but the disclosed limitations and provenance add meaningful context.

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 moderately long but every sentence earns its place: main purpose, return contents, parameter provenance, limitation, and alternative. There is minor redundancy ('one card design's' appears twice, 'recent sales' and 'recent raw sales feed' overlap), but the structure front-loads the core purpose and then layers context. It is efficient for the amount of information conveyed.

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?

There is no output schema, so the description must explain what the tool returns. It does: identity, full population report, and recent raw sales feed. It also covers a key limitation and the source of the required parameter. It does not specify the format or time range of the sales feed, but for a single-parameter tool with no output schema, this is a relatively complete and usable definition.

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% and the asset_id parameter already has a description in the schema, so the baseline is 3. The description adds value by explaining the provenance of asset_id ('comes from a prior alt-search/alt-sold-listings/alt-card-search result's asset_id field'), which helps the agent understand how to obtain a valid value. This goes beyond the schema's bare description.

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 opens with a specific verb and resource: 'Get one card design's population report and recent sales.' It clearly distinguishes itself from the sibling alt-sold-listings by noting that recent_sales lacks per-transaction grade breakdown and directing users there for that data. The scope ('independent of any single listing') further differentiates it from listing-level tools.

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 states where the required asset_id comes from ('a prior alt-search/alt-sold-listings/alt-card-search result's asset_id field'), giving a clear prerequisite. It also provides an explicit alternative: 'see alt-sold-listings for per-grade sold prices on specific listings.' This tells the agent when to choose a different tool, which is exactly what usage guidelines should do.

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