skillmd

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds extra context that skills are 'plain-text instructions' and 'nothing executes', plus every listed skill has passed safety review, which goes beyond the annotations to explain the safe nature and content type.

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 concise, front-loaded with the primary purpose, and uses two clear sentences. No redundant or vague terminology, 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?

Given the single parameter and the presence of an output schema, the description is complete: it explains what is returned (full contents and companion files), the format (plain-text), the safety aspect, and the intended use (ready to write to disk). No critical usage context 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?

The schema already provides a description and example for the slug parameter (100% coverage). The tool description merely repeats 'owner/name slug' without adding new parameter-specific semantics, so the baseline of 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 clearly states the specific action (return full contents), the resource (public skill by owner/name slug), and differentiates from siblings by emphasizing 'full contents' and 'every companion file for packs', which implies a complete download rather than a single item retrieval.

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 implies usage for downloading full skill packs (e.g., 'ready to write to disk') but does not explicitly contrast with alternatives like skillmd_get or provide when-to-use/when-not-to-use guidance. The context is implicit, not explicit.

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 the operation read-only, idempotent, and non-destructive. The description adds useful behavioral detail by listing exactly what data is returned, including provenance, license, safety verdict, capability flags, and companion files. No contradictions with 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?

The description is a single, well-structured sentence that front-loads the action and then efficiently lists the returned fields. Every phrase contributes useful information and there is no redundant 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?

For a simple read-only tool with one parameter, a rich output schema, and safety annotations, the description covers all necessary context: what it fetches, how it is identified, and what the result includes. Nothing essential 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% and already documents the slug as an owner/name identifier with an example. The description's 'owner/name slug' phrasing repeats this meaning without adding new format or validation information, so the baseline of 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 ('Fetch'), a specific resource ('one skill by owner/name slug'), and enumerates the returned content, distinguishing it clearly from sibling tools like skillmd_search or skillmd_download. The scope is unambiguous.

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 phrase 'Fetch one skill by owner/name slug' clearly implies this tool is for retrieving a known skill by its identifier, while the sibling names suggest alternatives for searching, recommendation, and trending. It does not explicitly state when not to use it, but the context is clear enough.

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 destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context: based_on restricts results to the skill's category, excludes the skill itself, and the no-argument fallback returns trending over the last 30 days. No contradictions with 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 carry all essential information with no filler. The primary action is front-loaded, and the conditional modes are described compactly in one sentence each.

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 only two optional parameters, an output schema present, and annotations covering safety, the description is complete. It explains both parameter modes and the default behavior, so an agent has enough context to select and invoke 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 coverage is 100%, so the baseline is 3. The description adds real semantic value beyond the schema by explaining what based_on means in practice (category-based recommendations, excluding itself, falling back to trending). Limit is not described in the description, but the schema fully documents its constraints and default.

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 action ('Recommend skills') and precisely defines two modes of behavior: category-based recommendations when based_on is present, and 30-day trending when it is absent. This clearly distinguishes it from sibling tools like skillmd_get, skillmd_search, and skillmd_trending by describing the selection criteria and behavior.

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 explicit conditional usage: set based_on for skill-category recommendations, omit it for trending results. It does not explicitly name alternatives or state when not to use this tool, but the conditional logic provides clear guidance for the two supported modes.

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 establish this as safe, read-only, and idempotent. The description adds useful behavioral context such as 'best match first' and the specific returned fields, but does not disclose deeper operational behavior like result count limits, empty-result handling, or ranking caveats.

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 one tight sentence that front-loads the action and resource, clearly states search dimensions, and lists the useful return fields. There is no filler or redundant repetition of the schema.

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 rich input schema, output schema, and safety annotations, the description is largely sufficient for an agent to call the tool correctly. The main gap is the lack of explicit guidance on how this search tool relates to sibling tools such as recommend and trending.

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 every parameter is already documented. The description adds little param-specific semantics beyond confirming that the query can be a natural-language task, name, or keyword, which aligns with the query 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 names a specific verb ('Search'), a specific resource ('SkillMD registry of Agent Skills'), and the search dimensions (task, name, keywords). It clearly conveys what the tool does, though it does not explicitly contrast with sibling tools like skillmd_get or skillmd_recommend.

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 implies that this tool should be used when an agent needs to find matching skills in the registry, and it mentions the returned result fields. However, it does not explicitly state when to prefer this over siblings or when not to use it, leaving usage guidance mostly implicit.

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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context about ranking criteria and optional filtering, but does not disclose details like pagination behavior or data freshness. This is acceptable given the strong annotation coverage.

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 a single, well-structured sentence that front-loads the core purpose and then adds optional filtering context. Every phrase earns its place with no redundant or vague 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?

For a read-only, low-complexity tool with three optional parameters, a complete output schema, and strong annotations, the description provides sufficient context. It explains the ranking criteria and optional filters, leaving no critical gap for an agent 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 the schema already documents all three parameters. The description reinforces the category and time-window concepts and adds the ranking basis, but it does not add meaningful parameter-level detail beyond what the schema provides.

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 a specific resource ('SkillMD leaderboard') and a precise ranking basis ('installs, saves and ratings'). It also conveys optional filtering by category and time window, which distinguishes it from generic search or get operations among 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 implies when to use the tool: when an agent needs top skills from the leaderboard with optional filters. However, it does not explicitly state when not to use it or mention alternative sibling tools like skillmd_search or skillmd_recommend, leaving some routing to inference.

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