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

With no annotations, the description carries the full burden. It discloses that each entry includes a sha256 manifest, implying integrity verification, and that it returns metadata (URI, name, description, frontmatter) rather than the full body. It explicitly points to read_skill for reading the body, which clarifies that this tool does not return bodies. This is good behavioral context beyond the schema.

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, only two sentences, but it packs significant detail: the resource, the list of fields in each entry, and a pointer to the sibling tool. It is appropriately sized and front-loaded with the core purpose. Minor redundancy like 'verbatim frontmatter' could be trimmed but adds precision, so it's fine.

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 that the tool has no parameters and no output schema, the description does a good job of explaining what the tool returns. It covers the entry content (URI, name, description, frontmatter, sha256) and the limitation that it does not return the body. Enough for an agent to know what to expect. Missing details like whether pagination or sorting exist, but for a simple list tool, it's adequately 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?

The tool has no parameters, so the schema provides no semantic guidance. The description fully compensates by clearly stating what the output contains, which is effectively the semantics of the tool's result. Since the tool takes no input, the description's explanation of the output serves as the primary semantic information for the agent.

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 tool's purpose: to list the product's skills and enumerates the exact content of each entry (SKILL.md URI, name, description, frontmatter, sha256 manifest). This distinguishes it from the sibling 'read_skill' which is for reading a skill's body. However, it could be more specific about the 'product' context, but it's sufficiently clear.

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 the primary use case: when you need an overview of available skills. It explicitly mentions the alternative, 'read_skill', for reading a skill's body, which serves as a clear contrast. It doesn't explicitly state when NOT to use it, but the mention of read_skill provides a functional distinction.

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