Find card ids

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 adds useful ordering behavior ('Verified cards first') and a disclosure that unverified cards are 'flagged, never hidden', which is valuable. However, it doesn't mention whether the operation is read-only, potential side effects, pagination behavior, or error handling. The added detail is helpful but not exhaustive.

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 a single, concise sentence that front-loads the core purpose ('Search ... to get the ids') and appends the key behavioral detail. There is zero fluff, and every word contributes to understanding. It exemplifies appropriate conciseness.

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 search tool with 3 parameters and no output schema, the description is somewhat complete: it states what it returns (ids), the search criteria, and a sorting rule. However, it omits any mention of the limit parameter's effect, result size, or pagination, and doesn't describe the exact return structure (e.g., is it an array of id objects?). Given the minimal schema and annotations, the description leaves some gaps the agent might need to infer.

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 0%, so the description must compensate. It tells you that you can search 'by card or issuer name', which gives some meaning to the 'query' parameter and possibly the 'issuer' parameter, but it doesn't clarify the distinction between them. The 'limit' parameter is not mentioned at all. This ambiguity leaves the agent uncertain about how to use the issuer parameter separately from query.

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 a specific verb ('Search'), a clear resource ('RightCard's catalog'), and a precise outcome ('get the ids to pass into best_card'). This immediately differentiates it from the sibling 'best_card' (which consumes ids) and others like 'lookup_merchant' or 'card'. It's not a tautology and the intent is 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 says the ids are meant to be passed into best_card, giving a strong usage context. It tells the agent 'use this to find ids for best_card', but it does not explicitly state when NOT to use it or mention alternatives like lookup_merchant for merchant lookups. It provides a clear use case but lacks explicit exclusions.

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