verified-codes

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

No annotations are present, so the description must disclose behavioral traits. It describes the return content but omits side effects, authentication needs, or error handling, leaving a minimal behavioral profile.

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?

Two sentences efficiently convey purpose and usage with no redundancy. Each sentence earns its place.

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 no output schema, the description lists all return fields fairly completely. However, it lacks information on error cases or prerequisites, which would be expected for a single-brand retrieval tool.

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 100%, giving a baseline of 3. The description repeats the schema's parameter description without adding new semantics or contextual guidance beyond examples.

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 states it returns the full verified-code record for one brand, specifies what fields are included, and distinguishes from siblings like list_brands and search_codes by focusing on a single brand lookup.

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 provides clear context for when to use the tool by specifying matching via brand name or slug, but does not explicitly contrast with siblings or give exclusion criteria.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns brands with specific fields (category, offer, code) but does not mention pagination, rate limits, or whether the list is exhaustive. This is acceptable but lacks depth.

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 concise (two sentences) and well-structured. The first sentence states the main purpose, and the second adds the optional filtering. Every sentence contributes meaning without redundancy.

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 one parameter with full schema coverage and no output schema, the description adequately covers the essential: what the tool returns and the filtering option. It could be improved by describing the return format (e.g., array of objects), but overall it is complete enough for this simple tool.

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?

There is one parameter 'category' with 100% schema coverage. The description provides the same information as the schema ('Optional category filter, e.g. 'crypto-exchange''). Thus it adds no new meaning beyond what the schema already offers, earning a baseline 3.

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 'Returns every brand on find.codes with its category, current offer and code (if any).' This is a specific verb-resource pair and clearly distinguishes from siblings like get_code and search_codes by indicating it returns all brands with associated data.

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 mentions optional filtering by category, which gives context for usage. It does not explicitly state when not to use or name alternatives, but the sibling tool names imply when to use this listing tool vs. getting a specific code or searching.

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

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

No annotations provided, so description carries full burden. It discloses that the tool performs a search and returns verified-code records. However, it doesn't describe potential limitations like pagination, case sensitivity, or exact matching behavior. No contradictions.

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 two sentences: the first states the action and gives examples, the second states the return type. No wasted words. Front-loaded with key action, making it easy for an agent to quickly understand.

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 no output schema, the description mentions returns are 'matching verified-code records', which is somewhat vague. It doesn't specify result format, limits, or pagination. Sibling tools are mentioned but not leveraged to clarify boundaries. Adequate but missing details that would fully inform an agent.

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 100% with one parameter 'query' described as 'Search terms'. The description adds value by providing concrete examples of search terms (e.g., 'stock perps discount', 'esim') and clarifies the scope of search across brands, categories, and offers, which helps the agent understand what kind of input to provide.

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 states it performs free-text search across brands, categories, and offers, with specific examples, and returns matching verified-code records. This distinguishes it from sibling tools get_code (single code retrieval) and list_brands (listing brands).

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 for broad free-text queries but does not explicitly state when to use this tool over siblings, nor does it mention when not to use it or any alternatives. Examples imply context but lack explicit guidance.

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