directory

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine context by enumerating the returned payload (commission, cookie, network, payment model, requirements, sources, verification date, modelled value), which is the main thing the annotations do not convey given there is no output schema.

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?

One sentence, front-loaded with the action and lookup key, with the field list in a compact parenthetical. No wasted words.

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 single-record lookup with only one required param and full annotation coverage, the description supplies what the missing output schema would otherwise provide by listing the returned fields. It stops short of noting not-found behavior or exact response shape, but nothing critical to invoking it correctly is absent.

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 100%, so the slug parameter is already fully documented in the schema, including the format example 'nom-nom' and its provenance from search_affiliate_programs. The description adds nothing beyond that, matching the 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?

States a specific verb+resource ('Get the full record for one affiliate program') and the lookup key (slug). It does not explicitly name the sibling it complements, search_affiliate_programs, in the description itself, so an agent must infer the list-vs-single split from the schema text.

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?

Usage is only implied: 'by its slug' signals a single-record lookup, and the schema note references slugs 'as returned by search_affiliate_programs'. There is no explicit when-to-use statement or exclusion against the sibling search/list tools.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds valuable context beyond annotations: that it reports verification against source and that it surfaces entries these tools exclude with reasons. No return format detail, but no output schema exists, so some burden is on the description.

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?

A single dense sentence that front-loads 'Headline coverage' and then lists the metrics. It's efficient, though the parenthetical '(with why)' is slightly ambiguous phrasing.

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 zero-param, read-only stats tool with annotations covering safety, the description is essentially complete: it tells the agent what metrics come back, including the verification and exclusion reporting that distinguishes it. Missing only explicit return structure, which is acceptable without an output schema.

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?

Zero parameters, so baseline is 4. Nothing to specify, and the description correctly doesn't waste words on parameters.

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 names a specific reporting/aggregation purpose and enumerates the metrics returned: total programs, categories, networks, verified counts, and excluded entries with reasons. It distinguishes itself from sibling tools that fetch individual programs, list categories/networks, or search, though it doesn't explicitly name those siblings.

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?

Usage is implied by 'headline coverage' – an agent can infer this is a summary/overview tool rather than a search tool, but no explicit when-to-use, when-not-to-use, or alternative routing is stated. Siblings like search_affiliate_programs are not referenced.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds what annotations cannot: that each entry includes a count, which is the only return-value disclosure given there is no output schema.

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?

A single sentence that front-loads the verb and resource, then qualifies it with the one detail that matters (what the categories are for). No filler.

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 zero-parameter, closed-world enumeration tool with a fully covered schema and safety annotations, the description supplies everything needed: what is returned (categories plus per-category counts) and why the agent should care.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline of 4 applies.

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?

Specific verb ('List') plus resource ('program categories'), and the parenthetical 'the keys search_affiliate_programs accepts' defines exactly what the resource is and distinguishes it from siblings like list_networks and get_directory_stats.

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 parenthetical makes the usage context clear: this is how an agent discovers the valid category values to pass to search_affiliate_programs. It stops short of explicitly stating when not to use it or naming a fallback, but the purpose-driven routing is unambiguous.

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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds the one behavioral trait not in structured data: the result includes per-network program counts, telling the agent what payload to expect.

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?

A single sentence with zero filler; the resource, the key relationship, and the count detail are all front-loaded and every clause 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?

For a zero-parameter listing tool with no output schema, the description supplies what is missing: what is returned (networks plus program counts) and why it matters (keys for search_affiliate_programs). Annotations cover the safety profile, so nothing essential is absent.

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?

Zero parameters, so there is nothing to mis-specify; baseline 4 applies. The description correctly implies no filtering arguments are needed.

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?

States a specific verb (List) and resource (affiliate networks) and disambiguates from siblings by naming search_affiliate_programs and explaining the returned values are that tool's accepted keys. An agent can tell what this does versus list_categories or search_affiliate_programs without opening a schema.

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 parenthetical establishes the call context: use this to discover valid network keys before calling search_affiliate_programs. It gives clear intended usage but no explicit exclusions or when-not-to-use guidance.

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?

Annotations already declare the safe-read profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add behavioral context beyond that. It does: flagging the headline metric as a MODELLED value per referral is a meaningful caveat, and it discloses that results are ranked best-first and paginated. Permission or rate-limit behavior is not discussed, keeping it short of a 5.

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?

Three sentences, zero filler: purpose and scope first, then concrete usage triggers, then return shape. Every clause carries information and nothing is repeated from the schema.

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 nine-parameter search tool with no output schema, the description covers what matters: what is searched, how results are ranked and paginated, and what a 'value' actually represents. Safety profile is fully carried by the annotations, so nothing an agent needs before calling is missing.

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%, so the schema already documents every parameter and the baseline is 3. The description adds only marginal meaning ('compared by network, commission, cookie window, and a modelled value') to explain what the default 'value' sort measures. It does not resolve the one ambiguity the schema leaves open, namely what the 'network' value in the confidence enum means.

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?

Names a specific verb and resource ('Search and filter the directory of affiliate programs') and even states the comparison axes and return shape ('ranked, paginated list of full program records'). The plural directory scope implicitly contrasts with the single-record get_affiliate_program sibling, but no sibling is named in the description itself, so it falls short of explicit differentiation.

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 trigger questions ('best/highest-paying affiliate programs for X') and enumerates the supported filter modes: category, network, recurring vs one-time, minimum value. There are no explicit when-not conditions or routing to list_networks/list_categories inside the description (those only appear in the parameter schema), so it is clear context without exclusions.

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