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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond them: the exact payload contents and the fallback rule that 'Unknown slugs return close matches', which prevents an agent from treating a near-miss response as an exact hit.

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 the resource and key scoping clause first. The field enumeration is long but earns its place because there is no output schema; it is dense rather than redundant.

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 supplies the returned field set, the slug provenance, and the unknown-slug fallback behavior — everything an agent needs to call it and interpret the result.

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 parameter already carries a description with examples, so the baseline is 3. The description still adds meaning the schema does not: it states where valid slug values originate (search_directory results), which is the main failure mode for this input.

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 and resource: 'Get the full Swarmnest directory record for one tool by its slug', followed by an enumeration of exactly which fields come back. It also distinguishes itself from the sibling search_directory by naming it as the source of valid slugs, so an agent can tell retrieval apart from search 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?

The parenthetical '(from search_directory results)' tells the agent this is the follow-up call after a search and where the input comes from, which is real routing guidance. It stops short of an explicit exclusion ('do not use for skills — use get_skill'), so it is clear context rather than a full when/when-not statement.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the returned field set and an install-safety caveat for third-party skills ('review the source before installing'). It does not say what happens on an unknown slug, which keeps it out of the top band.

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, verb and resource front-loaded, with the enumeration packed into a single clause and the third-party warning isolated at the end. The field list is dense but each item tells the agent what to expect back in the absence of an output schema, so it earns its space.

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 compensates by enumerating the returned fields plus both URL forms (source and canonical swarmnest.ai). Safety and idempotency are carried by annotations. Only the not-found/error behavior is unaddressed.

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 a single parameter at 100% schema coverage the baseline is 3, and the description earns an extra point by clarifying the slug's provenance ('from search_skills') — the schema only gives a maxLength and an example, not how to obtain the value.

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 Agent Skill by slug') and then enumerates exactly what the result contains (summary, format, platforms, install steps, labels, license, author, URLs). It also names the sibling that produces the input (search_skills), so an agent can distinguish it from search_skills/search_directory 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 '(from search_skills)' tells the agent this is the follow-up detail call after a search, which is clear usable context. There are no explicit exclusions (e.g., when to prefer get_entry or list_categories), so it stops short of full alternative routing.

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 covered. The description adds value on top: "List every" signals a complete enumeration with no pagination, and the field list tells the agent what payload to expect. Return-shape and pagination caveats are the only remaining gaps.

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 short sentences, no filler. The field inventory comes first, the cross-tool routing second, the optional filter last — a sensible front-loaded order for a listing tool.

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 enumerating every returned field. With one optional parameter fully documented in the schema and annotations covering the safety profile, an agent has everything needed to call this 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% and the group parameter is already documented as an optional slug with an example, so baseline is 3. The description adds a usage cue ("Optionally limit to one group") but its parenthetical example list — "Agent Building, AI Models, Data & Search" — reads as human group names while the schema requires slugs, introducing mild ambiguity rather than resolving it.

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 plus resource ("List every Swarmnest directory category") with the exact returned fields enumerated: slug, name, short description, entry count, group. The final sentence routes the agent away from search_directory, so the tool is distinguishable from its siblings without opening any 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?

Explicitly tells the agent how the output feeds a downstream call: "Use the slugs as the category filter in search_directory." That is a concrete when-to-use signal and names the alternative. It stops short of an explicit exclusion (e.g. don't call this when you already know the category), so it lands at 4 rather than 5.

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 behavior, so the description does not need to restate safety. It adds useful context beyond annotations: US-only coverage, USD pricing, bundle contents, product and checkout URLs. It does not mention pagination, rate limits, or auth requirements.

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 definition is a single well-structured sentence that front-loads the action and resource, then enumerates what the caller gets. There is no wasted text, and it is appropriately sized for a zero-required-parameter listing tool.

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 compensates by naming the return fields, including name, type, summary, price, bundle contents, product page URL, and checkout URL. Combined with annotations covering safety and a fully described single enum parameter, this is nearly complete, though it omits pagination or result count behavior.

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 sole type parameter is fully documented as an enum with all/products/bundles and a default. The description does not add meaning beyond the schema, so the baseline of 3 is 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 gives a specific verb and resource: listing agent skill packs, workflows, and bundles in the Swarmnest Marketplace, with the exact fields returned. It is clear about scope, including the US-only limitation, but does not explicitly distinguish itself from siblings such as search_skills or list_categories.

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 the scope: browsing marketplace inventory of products and bundles, with a US-only constraint. There is no explicit guidance on when to choose this over search_skills, search_directory, or list_categories, and no when-not guidance beyond the geographic limit.

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 adds genuinely non-obvious behavior: keyword search is conjunctive ("all keywords must match") and applies typo correction, plus it lists which fields come back. It doesn't state result ordering or ranking, which keeps it from 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?

One paragraph that is front-loaded with purpose, then filters, then return fields, then usage examples — a sensible order. The long enumeration of tool types ("coding agents, browser automation, vector databases...") is slightly padded, though it does communicate corpus breadth.

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 7 all-optional parameters, no output schema and annotations already covering the safety profile, the description covers what an agent still needs: what gets matched, how matching works, how to page with limit/offset, and exactly which fields come back in each result.

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 adds real meaning: the AND-matching rule for query, the fact query is optional when category or os is given, and that category values are slugs sourced from list_categories. Enum meanings (pricing/auth/os) are restated but not extended.

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: keyword search over the Swarmnest directory of AI agent tools, with the corpus enumerated (MCP servers, LLM APIs, frameworks, etc.). It points at list_categories as a helper but never explicitly distinguishes itself from sibling search_skills, so the agent must infer the corpus difference rather than being told.

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 operational context ("Use it to find or compare tools for a job") with three concrete example queries, and the schema-level note that query is optional when category or os is supplied. Missing an explicit when-not/alternative clause versus search_skills, so it's strong context without exclusions.

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 readOnly/idempotent/openWorld, so the description's job is added context — and it delivers: it discloses what each result contains (scripts, network use, credentials, license, author, source and canonical URLs) and warns that all skills are third-party and should be reviewed before installing. That trust/safety signal is real value beyond the annotations; only return-format/pagination detail is absent.

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 scope statement comes first, followed by search mechanics and then result payload, which is the right ordering for a search tool. It is dense but every sentence carries information; the catalog enumeration is long but earns its place by making the tool's scope unambiguous.

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 7 optional params, no required inputs and no output schema, the description does the necessary compensation by describing the result payload and the third-party caveat. Only minor omissions remain (no mention of paging via offset/limit or result ordering), which keeps it short of a 5.

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 the baseline is 3, but the description adds genuine semantics: it clarifies that the keyword query is matched against title, summary and category (not just any text) and that the filters cover category, format, platform and OS. That meaning is not in the schema descriptions, so a 4 is warranted.

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 Swarmnest catalog of Agent Skills') and enumerates the catalog's contents (SKILL.md skills, plugin bundles, Cursor rules, AGENTS.md templates, prompt packs) plus supported agents. Very clear what it does, though it never names the nearest sibling (search_directory / get_entry) to draw a boundary.

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 the field list ('Keyword search ...; filter by category, format, platform or OS'), which tells an agent how the tool is driven. However, there is no explicit when-to-use vs. when-to-use-a-sibling guidance and no stated prerequisites, so the agent must infer the routing itself.

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