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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond that: by default it returns a PNG contact sheet, which is a potentially heavy payload, and preview=false suppresses it.

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 tight sentences, front-loaded with what is returned and the identity parameter's effect. Minor overlap with schema-declared defaults (preview, category) but no filler sentences.

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?

No output schema exists, yet the description tells the agent exactly what fields to expect (license, author, category counts, icon names) plus the default image payload. For a read-only, five-parameter tool this is sufficient to call it 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?

Schema coverage is 100%, so all five parameters are already documented including defaults. The description adds only a rationale for preview ("so you can see the style") and a hint about category paging; it does not explain limit/offset interplay beyond the schema.

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 and resource ("Get one Iconify collection") and enumerates what comes back: license, author, category counts, and a page of icon names. The singular "one" implicitly separates it from list_collections, but no sibling is named 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 options (set preview to false to skip the image; pass category to page inside one category), but never says when to choose this over list_collections, search_icons, or get_icon. Usage is implied rather than routed.

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 read-only, idempotent, non-destructive, open-world behavior, and the description adds genuinely new context: the payload includes a visible PNG, an alias parent is surfaced only when the name is an alias, and snippets default to currentColor. That goes beyond the annotation set without contradicting it.

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 identification rule and the returned-field inventory are front-loaded, and the closing sentence routes to the sibling. The middle snippet enumeration is list-like and slightly padded, but every sentence still carries actionable 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?

With no output schema and seven parameters, the description does the work of describing the response shape (dimensions, collection, license, alias parent, URL, snippets, PNG) and calls out the visible image. Nothing essential for a correct single call 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 description coverage is 100%, so the baseline is 3. The description restates the currentColor behavior and enumerates snippet formats that the schema enum already lists, adding little meaning the schema does not already carry.

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 starts with a specific verb and resource ('Get one icon') and pins down the identifier format ('by Iconify id (prefix:name)'), which immediately separates it from search_icons and list_collections. It also names the panel of returned fields, so an agent knows exactly what kind of result to expect.

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?

"Use preview_icons to compare several icons" gives an explicit alternative with the condition that selects it (multiple icons vs. one). It does not mention when to prefer search_icons or get_collection, so the routing is clear but not exhaustive.

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?

The annotations already establish read-only, idempotent, non-destructive, open-world behavior. The description adds meaningful context beyond that: it lists the metadata returned, states that icon images are not returned, and notes that each icon set keeps its own license.

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 short and front-loaded, with the core purpose in the first sentence and exclusions immediately after. There is minor redundancy around licensing because license is both listed as returned metadata and restated at the end.

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 simple list operation with no output schema, the description does enough: it explains the returned metadata, states what is not returned, and points to alternatives for icons. The only minor gap is that pagination and limit behavior are left entirely to the 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?

Schema description coverage is 100%, so all four parameters are already well documented in the schema. The description reinforces the query, prefix, and category filters but adds little beyond those schema descriptions and does not mention the limit 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 states a specific verb and resource: list Iconify collections available on Icônes. It also clarifies the returned fields and explicitly distinguishes itself from get_collection and preview_icons by saying it does not return icon images.

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 clear filtering guidance via query, prefix, or category, and routes image-viewing use cases to get_collection or preview_icons. It does not explicitly compare itself with search_icons, so the alternative guidance is useful but not fully exhaustive.

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 safety (readOnly, idempotent, non-destructive, openWorld), so the description's added value is the output shape: a PNG plus a text result carrying each icon's license, and a hard cap of 24 icons. That is useful context for a tool with no output schema, but rendering details such as sheet dimensions or failure behavior when no icons match are unstated.

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?

Four short sentences, front-loaded with what the tool produces before the invocation modes and limits. The 'Supports size, color, background, and columns' clause mildly duplicates the schema but still serves as a quick capability scan.

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?

With 10 optional parameters, no required fields, and no output schema, the description covers the essentials: what is returned (PNG sheet + text with licenses), how to select icons, and the 24-item cap. Remaining detail (title, labels, column defaults) is fully documented in the schema, so nothing critical 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 a 3 is the floor, but the description adds real meaning by framing 'icons' and 'query'+'prefix' as alternatives ('Pass Iconify ids, or a search query plus an optional prefix'), which the schema only hints at via 'Search text used when icons is omitted.' It also names the tunable knobs (size, color, background, columns) and restates the 24-icon ceiling.

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 and artifact: 'Render a labeled PNG contact sheet of several icons so you can compare them in one image.' This is clearly distinct from the sibling read tools (search_icons, get_icon, list_collections) because it produces a composite visual, though it never names those siblings 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 clear context for when to reach for it ('so you can compare them in one image') and explains the two input modes: explicit Iconify ids, or a search query plus optional prefix. It stops short of exclusions or pointing to siblings for single-icon or text-only lookups.

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), so the description's job is to add context, which it does: it discloses the return payload (icon ids, collection license, Icônes URL) and that a labeled PNG contact sheet is returned by default. It does not mention rate limits or result-count behavior, keeping it below 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 tightly packed sentences with the resource and matching semantics front-loaded, followed by return contents and the preview opt-out. No filler wording.

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?

With ten fully documented parameters, rich annotations, and no output schema, the description does the needed extra work of describing the return format and default PNG behavior. Minor gaps remain around result pagination and preview payload cost, but overall it is sufficient to call the tool 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?

Schema description coverage is 100%, so all ten parameters are already documented, and the description only reinforces the preview toggle and contact-sheet behavior. It adds little meaning beyond the schema, so the baseline 3 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?

The description states a specific verb and resource ('Search icons across Iconify') and names the underlying catalog. It also clarifies the matching semantics ('matches icon names and keywords, not arbitrary visual similarity'), which distinguishes this search tool from sibling lookup tools like get_icon and preview_icons.

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 gives clear usage context: search by name/keyword rather than visual similarity, and 'Set preview to false for text only' tells the agent how to opt out of the PNG payload. It stops short of explicitly routing between siblings such as list_collections or get_icon, so no exclusions are stated.

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