Digche Icons

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

No annotations are present, so the description must carry the full burden of behavioral disclosure. It states the purpose (find and rank) but does not mention whether the operation is read-only, how results are ranked, or any side effects—though the tone implies a read-only action.

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, front-loaded with the main action, and no wasted words. The description is concise and immediately communicates the core purpose.

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 has 5 parameters and no output schema or annotations. The description tells what the tool does but not what a 'replacement' consists of, how ranking works, or the structure of the returned candidates. It is adequate for a simple tool but leaves gaps.

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 roughly 60% (sourceLibrary lacks a description). The description adds meaning to the context parameter ('Include the UI context for a more useful match') and clarifies that sourceLibrary is optional ('or another library'), but it doesn't significantly elaborate on other 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 uses specific verbs 'Find and rank' and identifies the resource 'Digche replacements', along with supported libraries (Lucide, Heroicons, Material Symbols, Font Awesome, or another). This clearly distinguishes the tool from broader search/recommendation 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?

The description provides a practical tip about including UI context but gives no guidance on when to choose this tool over siblings like search_icons or recommend_icons. There are no exclusions or alternative scenarios, leaving the decision to the agent.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'validated' but doesn't explain what validation entails, what happens when an invalid slug is passed, or how allowFallback influences behavior. No side effects, permissions, or error handling are disclosed.

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, with the first stating the core purpose and the second offering practical style guidance. It is front-loaded, avoids redundancy, and every sentence contributes useful information.

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 has three parameters, no output schema, and no annotations. The description explains the core action but omits behavior around fallback, validation errors, return format, and relationship to sibling tools. Given the available schema detail, a more complete description of edge cases and expected outcomes is needed.

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%, and the description only indirectly references the 'slug' and the 'Linear' style. It does not explain the slug pattern, the meaning of each style option, or the allowFallback parameter. The schema itself provides some structure (enum, default), but the description adds minimal semantic value beyond that.

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 the action: 'Retrieve a validated SVG variant after selecting a Digche slug.' It specifies a resource (SVG variant) and a prerequisite (slug), making the tool's role distinct from search or replacement siblings. However, it doesn't explicitly contrast with sibling tools, so it falls short of a 5.

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 gives a style recommendation ('Prefer Linear for functional product UI unless the project uses another Digche style'), which is useful for choosing the style parameter. However, it does not explicitly state when to use this tool versus the sibling alternatives (search_icons, find_replacement), only implying it should be used once a slug is known.

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?

With no annotations, the description carries the burden of disclosing behavior. It adds meaningful context by stating it lists 'every published' category (scope) and includes 'icon count and available styles' (content). The phrase 'Call this once' also hints at low cost, which is helpful. It does not explicitly say it is read-only, but 'list' strongly implies that.

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 with no fluff. The first sentence delivers the core functionality, and the second sentence provides usage guidance. Every part earns its place, and it is front-loaded with the key action.

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 (0 params, no output schema). The description covers what it returns (categories with counts and styles) and when to use it. It could explicitly state that it returns a list/array, but 'List every...' implicitly conveys that. It is complete enough for an agent to invoke correctly.

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 has zero parameters, so the description cannot add parameter-level meaning. The schema already covers everything (empty properties). The baseline for 0 parameters is 4, and the description appropriately does not invent unnecessary parameter details.

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 the tool lists every published Digche category, including icon count and available styles. It uses a specific verb ('List') and resource ('Digche category'), and it distinguishes itself from sibling tools like search_icons by focusing on catalog vocabulary rather than searching.

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 gives a clear 'when to use': 'Call this once to learn the catalog vocabulary before filtering searches by category.' It implies this is a one-time setup step and not for ongoing filtering, though it does not explicitly name alternatives or state when not to use it.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It states that the tool renders a single image for comparison, but it does not mention read-only nature, output format details, or how conflicting inputs (slugs + query) are handled. Some behavior is implied (e.g., search+preview) but not fully elaborated.

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 compact sentences, front-loaded with purpose and then usage. Every word contributes, with no redundant restating of the tool name or schema details.

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 tool with 5 optional params and no output schema, the description covers core behavior and both usage modes. It omits some details like default handling when neither slugs nor query are supplied, and it doesn't explicitly describe the returned image format, but the schema fills some gaps (defaults, limits).

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 covers 60% of parameters (limit, query, slugs), and the description adds relational meaning: slugs come from a previous tool call, query is an alternative for one-step search+preview. However, style and theme have no description and are left only as enum labels, relying on implicit understanding.

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 uses the specific verb 'Render' with a clear resource ('candidate Digche icons') and the intended outcome ('compare them before choosing'). It distinguishes the tool from siblings like search_icons (which searches/returns metadata) and get_icon_svg (which returns a single SVG) by emphasizing a single composite image for comparison.

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 defines two usage modes: pass slugs from an earlier tool call, or use a query to search and preview in one step. This clearly indicates when to use the tool, though it does not name alternative tools or state exclusions (e.g., not for fetching SVGs).

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 itself must disclose behavior. It reveals that the tool recommends a coherent set, supports up to 20 slots in one call, and uses the task context to resolve ambiguity. However, it doesn't disclose the output format (e.g., slugs vs. SVG) or any side effects, though the responseMode parameter covers the format.

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 three sentences with no filler. It front-loads the main action, then provides guidance on the task parameter, and ends with the usage comparison to search_icons.

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 the tool's moderate complexity (5 params, no output schema, no annotations), the description covers the core use case and distinguishes it from siblings. The main omission is explicit mention of responseMode (plan vs assets), but the parameter description in the schema covers that. Overall, it's sufficiently complete for an agent to invoke correctly.

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 schema already documents most parameters (80% coverage), but the description adds a critical constraint: 'up to 20 named UI slots' which is absent from the schema. It also explains the purpose of 'task' as resolving ambiguous slot names, adding meaning beyond the schema's example.

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 opens with 'Pick a coherent Digche icon set for up to 20 named UI slots in one call', clearly stating the verb, resource, and scope. It explicitly contrasts with per-icon search ('Use this instead of one search per icon'), distinguishing it from the search_icons sibling.

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?

It says to use this tool when laying out a screen and instead of one search per icon, providing a clear alternative. It also instructs users to 'Give the overall task so ambiguous slot names resolve correctly', which guides effective use. It doesn't enumerate other sibling tools, but the primary alternative is named.

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 searches only 'published' icons and returns 'a paste-ready summary and a preview image', which are useful behavioral traits. However, it does not state whether the operation is read-only, or describe pagination or error behavior, so it's partial transparency.

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, no filler. The first sentence states function, the second gives usage timing and return value. Efficient and front-loaded.

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 description covers purpose, timing, return format, and scope. It lacks detailed parameter semantics for style/category and doesn't explain the output schema, but these are partially covered by the input schema. The combination is adequate for a search tool with 4 simple parameters.

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 schema already documents query and limit. The description adds that query can include 'functional meaning' and other dimensions, enriching the query concept. However, the style and category parameters receive no description in either schema or text, even though the schema description coverage is only 50%. The description mentions 'category' as a search dimension but not as a filter parameter.

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 identifies the verb 'Search' and the resource 'published Digche icons', and enumerates search dimensions (name, alias, use case, tag, category, functional meaning). This distinguishes it from sibling tools like find_replacement or preview_icons, and the phrase 'Use this before choosing a UI icon' reinforces its purpose.

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 a clear usage context: 'Use this before choosing a UI icon.' However, it does not explicitly mention when not to use it or how it differs from sibling tools like find_replacement, so it lacks exclusions or alternative pointers.

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