alt_card_search

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

With no annotations, the description carries the transparency burden and does substantive work: it identifies the data as 'credential-free public data from Alt's own search backend' and clarifies this is the reference catalog rather than live listings. It doesn't discuss pagination, rate limits, or result envelope, but the read-only search behavior and data provenance are clearly disclosed.

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 content is mostly earned, but the opening 'Search Alt's reference card-design catalog' is immediately restated by the second sentence, creating redundancy. The remaining context about canonical catalog, asset_id use, and credential-free access justifies its place.

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 simple search tool it is complete: it names the catalog scope, the key output (asset_id), the downstream use, and the auth requirement, while the schema covers all three parameters. It doesn't describe the full return structure or pagination behavior, but the clear asset_id use case partially offsets the lack of an 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?

Schema description coverage is 100%, so q, page, and per_page are already documented in the schema. The description adds the downstream purpose of the returned asset_id but no additional parameter format or constraint information, so the baseline 3 applies.

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: 'Search Alt's reference card-design catalog.' It sharpens this with 'canonical catalog of card designs (one entry per year/brand/subject/card-number/variety combination)' and explicitly states it is 'separate from live listings or sales,' distinguishing it from sibling listing/search 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?

It provides clear when-to-use guidance: 'Useful for finding a card design's asset_id... without already having a live listing or sale that references it.' It doesn't explicitly name an alternative search tool such as alt_search or tell the agent when to prefer live-listing tools, so it falls just short of fully explicit routing.

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