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

Annotations cover the read-only, idempotent, open-world profile, and the description adds meaningful behavior the annotations do not: pagination is per bank via next_offset, limit is per bank, and the benefit text is unparsed bank prose from which the percent, cap, and conditions must be read. That last point is a genuinely useful disclosure that prevents an agent from expecting structured numbers.

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 opening sentence is well front-loaded and the long code lists are necessary, but "benefit is the text of the bank" is stated twice and "Compare the banks by reading it" is vague filler. The card code catalogue also consumes a large share of the text for what is essentially lookup data.

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 an 11-parameter search tool with an output schema and full annotation coverage, the description covers filters, pagination, semantics of obscure codes, and the critical caveat about parsing benefit text. Only minor things are absent, such as what an empty result looks like or how per-bank limits interact with offset advancement.

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 already 100%, but the description goes well beyond it: the bank code list, the per-bank card code list, the tier definitions (standard/premium incl. SOLO at BOG, private incl. Wealth Management at BOG, youth), and the note that "other" means the bank states no kind. These resolve the code enumerations that the schema itself defers to the description for.

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?

"Finds the current offers that Georgian banks give to card holders at partners: discounts, cashback, and points" states a specific verb (finds), resource (card offers), and scope (partner offers from Georgian banks). It is clearly distinguishable from offers_get_offer by being a search, though it never names that sibling explicitly.

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 concrete operating guidance: "For 'this month', give the first and the last date of the month", and "When a bank has a next_offset, call again with that offset to read more", plus "Give the person the url of each offer that you name". It lacks an explicit statement of when to use this versus offers_get_offer, which is the main remaining gap.

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