TCGplayer product search (BYO key)

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds genuinely new context: it requires caller-supplied credentials via TCGPLAYER_CLIENT_ID/TCGPLAYER_CLIENT_SECRET and warns that key issuance is currently restricted, which materially changes whether an agent should attempt the call. It does not cover rate limits or result shape, keeping it below a 5.

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?

Four short sentences, front-loaded with purpose, then constraints. No filler, though the "Read-only" clause duplicates readOnlyHint and the key-availability warning could be folded into the credentials sentence.

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 3-parameter search with no output schema, the description covers auth and one enum-like value but leaves the success shape unknown — it never hints that results are product entries with IDs that downstream price-guide tools consume. Adequate to attempt the call, not enough to plan a multi-tool workflow.

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 0%, so the description carries the full documentation burden, yet it only annotates one parameter (categoryId 1 = Magic). It never clarifies whether productName is exact-match or substring, what limit actually caps, or what categoryId values exist beyond Magic.

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?

States a specific verb and resource ("Search TCGplayer catalog products by name") and scopes it to a named marketplace, which inherently distinguishes it from the scryfall_* and cardmarket_* siblings. An agent can tell which catalog it targets without opening the schema.

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?

Gives prerequisites (own API keys in env) and an availability caveat, plus one concrete usage hint (Magic is categoryId 1). However, it never says when to prefer this over scryfall_search_cards or cardmarket_product_search, nor what happens when a search is too broad or returns nothing.

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