find_credit_card_offers

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 a concrete result limit ('up to 10') and the probabilistic nature ('likely') of the matches, which is useful. However, it does not disclose whether the operation is read-only (though 'Find' implies it), how results are ordered, what happens with no filters, or any error conditions. Given these gaps, the description is minimally transparent but not comprehensive.

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, tight sentence that front-loads the main action and includes all relevant filter information. There is no verbose or redundant content; every phrase earns its place. It is efficiently structured for quick parsing.

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?

The tool is simple with three optional parameters and an existing output schema, so the description need not explain return values. It covers the primary behavior and the filter constraints, making it sufficient for basic invocation. However, it lacks explicit usage exclusions or alternative tool references, which would enhance completeness. Given the low complexity, the description is largely adequate.

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 for parameter meaning. It does rephrase each parameter into human-readable filter concepts: 'issuer', 'card-name', and 'minimum source-unit bonus' map to issuer, card, and bonus_min respectively. This adds meaning beyond the raw parameter names, but it does not specify formats, matching rules, or units beyond 'source-unit bonus'. The mapping is present but shallow.

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 clearly specifies the tool's purpose: finding up to 10 credit-card offer source articles, with a specific verb ('Find') and resource ('credit-card offer source articles'). It differentiates from siblings like find_bank_bonuses by targeting credit-card offers, and its scope is distinct from generic search_posts. Though it doesn't explicitly name alternatives, the domain specificity makes its purpose unambiguous.

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 implies usage through its domain-specific phrasing and filter list, but it does not provide explicit guidance on when to use this tool versus alternatives like search_posts or compare_offers. There is no 'use this when...' or 'instead of...' guidance, so the agent must infer from the title and context. The optional filters are mentioned, but no exclusions or prerequisites are stated.

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