cards_find

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

No annotations were provided, so the description carries the full burden of behavioral disclosure. It thoroughly discloses input format constraints, error behavior ('repeated and bracketed parameters return an unable-to-parse error'), output fields ('player, uid, card_detail_id, xp, gold, edition, card_set, collection_power, market and rental fields'), and limits ('100-row and 256 KB limits'). It also clarifies semantic nuances: 'player is current-owner attribution, not donor provenance.' This is far beyond typical descriptions, though it doesn't mention auth requirements or rate limits, which are minor given the detail provided.

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 quite long but dense with essential information. It is front-loaded with the primary purpose and input format, followed by constraints and output fields. However, some sentences are wordy and could be tightened; for instance, the phrase 'real 2-ID and 3-ID requests returned exactly the requested UIDs in order' is a test result, not a specification, and could be a separate note. Still, every sentence adds value for correct usage, though the length may dilute impact.

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 (one parameter, no output schema) and the complete absence of annotations, the description covers everything necessary for correct invocation: input format, error cases, output fields, semantics of the player field, and server limits. No output schema exists, so the explicit field list is crucial and provided. The description is fully sufficient for an agent to call this tool correctly and interpret the response.

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 schema has only one parameter 'ids' with just minLength: 1 and no description (schema description coverage 0%). The description compensates fully by explaining the expected format: 'a comma-separated string of full per-instance card UIDs' and explicitly listing invalid encodings. This gives the agent the exact meaning of the parameter beyond the schema. It does not specify a maximum length or example, but the format is clear enough for correct invocation.

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 states exactly what the tool does: 'Look up per-instance card records through GET /cards/find.' It specifies the resource (card records) and the endpoint, and distinguishes itself from definition routes ('BCX is therefore promised for this per-instance route only; it is not a claim about definition routes'). It also implies a lookup, contrasting with many sibling market/land/player tools, making its purpose unmistakable.

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 tells the agent how to supply ids: 'one comma-separated string of full per-instance card UIDs' and states what is not valid: 'Repeated ids=, ids[]= and JSON-array encodings are not valid.' This is a clear usage guideline that prevents common errors. It also qualifies the scope ('per-instance route only') and explains the result is bounded by limits, giving context for when to use it. It does not explicitly name an alternative, but the distinction from definition routes and the presence of sibling cards_get_details etc. implies exclusion.

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