Generative Icons

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description adds real context beyond that by noting the icon is website-generated, public and marked unreviewed, which tells the agent something about data provenance and quality. It also discloses that the payload includes a dotLottie file URL and a runtime descriptor, which is information no annotation supplies.

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?

It is a single compact sentence with no filler, but it is structured as a colon-separated field dump rather than front-loading the action, and phrases like 'what its motion shows' are vague. It is dense without being efficiently organized.

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, the description usefully enumerates what comes back (label, originating request, motion summary, dotLottie URL, page, runtime descriptor), which is exactly what an agent needs to decide whether to call it. What is missing is the operation verb and any notion of behavior for a nonexistent or unreviewed id.

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% and the id property already documents its pattern and its source (search_icons), so the description need not compensate. The description adds nothing about the id's format or resolution behavior beyond the schema, making the baseline 3 appropriate.

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 identifies the resource (a community icon) and enumerates its returned fields, but it is a noun phrase with no explicit verb such as 'fetch' or 'retrieve', so the operation must be inferred from the tool name. It also never contrasts itself with the sibling get_icon, leaving the community-vs-standard distinction implicit in the parenthetical alone.

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?

There is no statement of when to use this tool versus get_icon or search_icons, and no note on prerequisites or failure modes for an unknown id. The only usage hint, that the id comes from search_icons, lives in the input schema rather than the description.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description then adds genuine value on the dimension annotations cannot cover: with no output schema, it enumerates what comes back (states, styles, weights, motions, dotLottie URL and hash, install commands, and platform snippets). It omits error behavior (e.g. unknown id), which keeps it below 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?

A single front-loaded sentence with zero padding, leading with the payoff ('everything needed to use one icon') before the itemized contents. Slightly list-like rather than explanatory, but nothing is wasted.

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 one-parameter read tool with strong annotations, the main missing pieces are how it relates to search_icons and get_community_icon and what happens when an id is not found. The absence of an output schema is partly compensated by the returned-content enumeration, so it is adequate but not complete.

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?

Only one parameter, and schema coverage is 100% with format and example ('trash', from search_icons) already documented in the schema. The description adds no additional meaning about the id beyond what the schema provides, 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 makes clear this retrieves full detail for a single icon ('Everything needed to use one icon') and enumerates exactly what that detail includes. It does not differentiate from the sibling get_community_icon, which an agent could plausibly confuse it with, 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?

Usage is only implied: the 'everything needed to use' framing suggests this is the follow-up step once an icon has been chosen, and the schema hints at coming 'from search_icons'. No explicit when-to-use, when-not-to-use, or sibling routing (search_icons vs get_community_icon) is given.

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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description contributes only that ids and icon counts are returned, and says nothing about ordering, volume, or whether categories can be empty — modest added value against an already-rich annotation set.

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 short sentence with no filler, and the most useful detail (ids and icon counts) is placed immediately. It is terse enough that it reads as a label rather than a sentence, which costs a little clarity but nothing in economy.

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 parameters and no output schema, the description does the right thing by naming the returned fields, which partially compensates for the absent return contract. However, for a catalog-listing tool it should say more about what a category entry looks like and how many to expect, leaving it merely adequate.

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 and the schema is fully covered, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless tool.

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 is a noun phrase ("The library's categories with their ids and icon counts") that identifies the resource and hints at returned fields, but supplies no verb, so the list operation is only inferred from the tool name. It is distinguishable from the icon-focused siblings by resource, but the statement of purpose is vague rather than specific.

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?

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as search_icons or get_icon. The obvious use case — discovering category ids before filtering a search — is left entirely to inference.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description contributes beyond that by stating the payload is Markdown, which matters for rendering; it says nothing about size, failure modes, or whether guides are static.

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 compact sentence that front-loads the return format before the enumeration. No filler, though it opens as a fragment without a verb, which reads slightly clipped.

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 one-parameter lookup with no output schema, the description covers the format and the full option space, which is what an agent needs to call it correctly. Missing only the explicit-purpose sentence and any note on guide size or staticness.

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 0%, but the enum values carry no self-explanatory meaning on their own, and the description supplies a human label for each of the seven slugs. That is real added meaning beyond the raw enum, though it stops short of saying when to prefer one guide over another.

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 fragment 'A guide as Markdown' names the resource and the return format, and the enumerated slugs make the topical scope concrete. The verb is only implied by the name/title rather than stated, and no sibling is named, but the guide-versus-icon distinction against the sibling set is obvious from the content list.

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?

There is no explicit when-to-use or when-not-to-use statement, and no alternative tools are referenced. Implicitly, the per-slug labels tell the agent which guide answers which kind of question, which is a usable but indirect selection aid.

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?

Rich context beyond the annotations: generation is done by a signed-in person on the website, takes about three minutes, and the resulting icon appears in search_icons later as a community icon. 'Nothing is generated by this call' reinforces readOnlyHint/idempotentHint rather than contradicting them. Minor omission: nothing about link expiry, reuse, or what the caller needs to supply beyond 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?

Front-loaded with the triggering condition, then the mechanism, then the handoff instruction, then the clarifying 'Nothing is generated by this call.' Slightly dense in the first sentence but no sentence is wasted.

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, and the description covers what it is (a link, not a generated icon), who can use it (signed-in LottieFiles user), expected latency, and the downstream effect. It also forestalls the main misconception an agent might have, that this call itself generates artwork.

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% and the single 'description' parameter is already documented with examples ('a kite flying', 'piggy bank for a savings app'). The tool description implies the request describes the desired icon but adds no format, tone, or style guidance for that field 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?

The description names the concrete action and the concrete artifact: it produces 'a link where a person signed in with LottieFiles generates the icon on the website.' It explicitly separates itself from search_icons by framing the condition ('when search_icons finds nothing that fits') and adds the outcome (icon later appears as a community icon). An agent knows exactly what this returns without opening the 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?

It gives the precise triggering condition (search_icons returns nothing suitable), names the sibling to use first, and tells the agent what to do with the result ('Give the link to the person you are helping'). No alternative is left unmentioned for this niche.

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), so the description is free to add real behavioral detail — fuzzy/typo-tolerant matching, semantic embedding search, and result ordering with best matches first. It doesn't state what happens on zero results or whether matching is scored, but it adds genuine context beyond the annotations.

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 action, then the matching mechanisms, then the result ordering. No filler, and every clause carries information an agent would otherwise have to guess.

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 three-parameter read-only search with full schema coverage and no output schema, the description covers input semantics and result ordering adequately. The remaining gap is navigational: it never relates itself to get_icon, get_community_icon, or list_categories, which matters given five siblings in this space.

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 baseline is 3. The description does enrich the query parameter by explaining what kinds of input match (labels, synonyms, slang, abbreviations, plain-language needs) and that typos are tolerated, which goes beyond the schema's example-based wording, but it says nothing about limit or category behavior.

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?

Opens with a specific verb+resource ("Find icons") and then qualifies the matching strategy (labels, synonyms, UI slang, abbreviations, embeddings, typo tolerance). This clearly separates it from a direct-fetch sibling like get_icon, though 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?

Usage is only implied: the description tells you it searches by name or meaning, so an agent can infer this is the discovery entry point. There is no explicit when-to-use/when-not, no mention of preferring get_icon once an identifier is known, and no pointer to list_categories for browsing by category (that hint lives only in the schema).

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