Glyfiq Medical & Health Icons

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

Beyond the read-only and non-destructive annotations, it discloses random sampling from the full free-icon pool, varying results across repeated calls, the returned fields, and the absence of a license-key requirement. These details set useful expectations about both results and access.

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 front-loaded with the tool's purpose and remains compact despite covering randomness, output fields, the parameter, the search alternative, and authentication. The limit sentence duplicates schema information, but the wording is still efficient and easy to 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?

For a simple read-only sampler with one optional parameter, the description supplies everything needed to select and invoke it appropriately. Although there is no output schema, naming the returned fields and explaining sampling behavior adequately sets result expectations.

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 description's explanation of limit, including its range and default, substantially repeats the schema. It adds no parameter syntax or interaction details beyond that structured documentation.

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 exactly what is returned: a random sample of free Glyfiq icons containing names and tags, intended to show library coverage. It also clearly distinguishes the tool from search_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 a clear use case—exploring what the library covers—and an explicit exclusion: this is not a search. For topic-specific requests, it directs the agent to search_icons.

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 only declare the read-only/idempotent safety profile; the description adds licensing rules (free icons need no key, premium require a server license key via connector URL/headers or license_key), per-icon partial-failure semantics (ok / premium_locked / not_found), and that the batch does not fail as a unit. That is exactly the kind of context annotations cannot carry.

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?

Five tight sentences, front-loaded with what the tool returns, then limits, then licensing, then result semantics, then the sibling comparison. No restatement of the title and 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?

With no output schema, the description compensates by describing the per-icon response shape and status values; licensing and input sourcing are covered. An agent has everything needed to call it correctly on the first attempt.

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 already 100%, so baseline is 3; the description adds real meaning by tying names to search_icons output and by clarifying that license_key is normally configured once via connector URL or headers rather than passed per call.

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 ('Returns the full SVG source of multiple Glyfiq icons') plus the batch scope ('in a single call'), which cleanly separates it from the singular get_icon_svg and from search_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?

Explicitly routes the agent: 'Prefer this over repeated get_icon_svg calls when inserting several icons,' and states the input dependency ('exact icon names returned by search_icons'). The alternative and the condition that selects it are both 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?

Beyond the readOnly/idempotent annotations, it discloses licensing behavior (free icons need no key; PRO icons require a license), the server-side key fallback when license_key is omitted, and two distinct error paths with what each message says. This is exactly the operational context annotations cannot express.

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 primary behavior, then prerequisites, then licensing, then failure modes, in five tight sentences with no filler. Each sentence carries distinct operational 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, the description compensates by stating the return is one text content block of SVG source, and it covers the only real complexity in this tool: premium licensing and error recovery. Nothing an agent needs to call it correctly 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 baseline is 3, but the description earns more by explaining the license_key resolution order (explicit parameter overrides server-configured key from connector URL or Authorization header) and by reinforcing that name must be an exact search_icons result. That is meaning the schema alone does not convey.

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 ("Returns the full SVG source of one Glyfiq icon") and specifies the return shape ("a single text content block"). The singular "one icon" implicitly separates it from the plural sibling get_icons_svg, so an agent can route correctly 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?

Gives a clear prerequisite chain: the name must be the exact one returned by search_icons, and if the icon is not found the error tells you to call search_icons again. It also explains free vs. premium access conditions. It stops short of naming get_icons_svg as the batch alternative, which is the one remaining routing gap.

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, and non-destructive behavior, so safety is covered. The description adds substantive behavior beyond them: a hard cap of 50 results, descending frequency ordering, inclusion of counts and total icon count, and the explicit exclusion of rare tags. Only minor gaps remain, such as the exact response field names.

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 with no filler: result content and ordering first, then usage guidance, then the no-parameter fact, then the coverage limitation. Every sentence carries distinct 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?

There is no output schema, yet the description fully characterizes the return value (top 50 tags, counts, total icon count, sort order) and warns about omitted rare tags. Nothing an agent needs before calling this no-argument tool 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?

With zero parameters the baseline is 4, and the description confirms 'Takes no parameters', removing any doubt about whether filtering arguments exist. No additional parameter meaning is possible here.

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 plus the exact result shape: '50 most common tags ... with counts, plus the total icon count', sorted by frequency. That is far more precise than the name alone and lets an agent distinguish it from search_icons at a glance.

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?

Explicitly routes usage: 'Use it to pick effective search terms before calling search_icons' names the downstream tool and the reason. It also states a when-not condition — 'Rare tags are not listed; use search_icons for those' — so the agent knows the boundary of this tool's coverage.

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, closed-world and non-destructive, so safety is covered. The description adds genuinely new behavior: synonym/fuzzy/full-text matching, relevance-ranked ordering, metadata-only results with no SVG code, and the free/PRO distinction via is_free: false.

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 purpose and examples, then behavior, then workflow. Every sentence carries information, though the parenthetical 'limit parameter (1 to 50, default 20)' mildly duplicates the schema constraints already available to the agent.

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?

There is no output schema, and the description compensates by naming the returned fields (name, tags, is_free) and explicitly ruling out SVG code. For a three-parameter search tool with full annotation coverage, an agent has everything needed to call it and interpret results.

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 query and limit are already documented in detail, including the 5–10/20/50 guidance. The description restates the limit range (1 to 50, default 20) without adding new meaning, and says nothing about license_key, which the schema handles. Baseline 3 applies when the schema does the heavy lifting.

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 ('Search the Glyfiq medical and health icon library') and immediately disambiguates with concrete query examples ('cardiology', 'MRI', 'fracture', 'stethoscope'). It also distinguishes itself from siblings by naming get_icon_svg as the follow-up step and list_tags as the fallback.

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?

Explicit sequencing guidance: 'Call this first, then call get_icon_svg with an exact name from the results.' It also gives failure guidance — retry with a broader or alternative term, or call list_tags — so the agent knows both the happy path and the fallback.

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