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 the important behavioral note that the full text is 'explicitly untrusted', warning the agent about potential risks. However, it does not describe other behaviors such as error handling, not-found cases, or rate limits. The untrusted warning adds value, but more context could be given.

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, with only two sentences. The first sentence states the core purpose, and the second provides a practical usage hint. It is front-loaded with the main action. No wasted words, though the second sentence is more of an advisory note than a description of the tool itself.

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?

The tool is simple (2 params, no nested objects), and annotations cover safety, but there is no output schema. The description confirms it returns a 'descriptive catalog record' and optionally full text, but does not detail the record's structure, pagination, or error behavior. Given the abundance of similar sibling tools, the description should more clearly specify when this tool is the right choice, which it only weakly does via the 'local skill' qualifier.

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 provides no descriptions for parameters (0% coverage), so the description must compensate. It explains includeContent indirectly by mentioning 'only when requested, explicitly untrusted full text', implying that setting includeContent=true triggers retrieval of full text. However, it does not explicitly describe the 'id' parameter's purpose beyond being an identifier, and it does not mention default behavior when includeContent is false or the format of the catalog record. The description adds some meaning but not enough for full comprehension.

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 primary action: retrieving a descriptive catalog record and optionally the full text for a local skill. It identifies the resource (local skill) and the verb (get), which is clear. However, it does not explicitly distinguish itself from the sibling 'registry_get_skill' or clarify what makes it different from 'read_skill_file' or 'search_skills', so it's not fully differentiated.

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 provides a general workflow instruction ('Compare multiple plausible candidates... before selecting exact IDs') but does not explicitly state when to use this tool instead of alternatives like search_skills or registry_get_skill. It also does not explain when to use includeContent beyond implying it is opt-in. No exclusions or conditions for non-use are given.

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