get_skill

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

With no annotations, the description carries the full burden and does well: it discloses a conditional output shape (install info withheld for blocked, withheld, or safety-flagged-awaiting-review skills) and a concrete failure mode (namespaced name 404s, UUID id also accepted). It adds no auth, rate-limit, or caching context, but for a read tool the disclosure is otherwise substantial.

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 core purpose is front-loaded and the parameter caveats follow in a clearly labelled Args block. The opening sentence is a dense enumeration of return fields that could be tightened, but with 0% schema coverage the detail largely earns its place.

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?

An output schema exists, so return-value explanation is not strictly required, yet the description still names the key fields and the one case where they are absent. The main remaining gap is that it does not say how to obtain a slug if the agent has not run a search.

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 0% for the single 'slug' parameter, so the description must compensate entirely, and it does: it distinguishes url_slug from name, explains the namespacing transformation (owner/skill -> owner-skill), explains why a slash 404s, and notes that the UUID id is also valid.

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 skill's full record') and enumerates exactly what the record contains: safety-scan status, benchmark evidence, SkillScore, ratings, SKILL.md body, and install info. It ties itself to 'search results' but never names search_skills or get_leaderboard to explicitly draw the boundary, so it stops short of full sibling differentiation.

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?

Context is clear: this is the single-record lookup whose input comes from search results, and it tells the agent that install details are omitted for blocked/withheld/flagged skills. It does not explicitly state when to prefer this over the sibling list/leaderboard tools or how to obtain a slug if none is known.

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