load_skill

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

Beyond the annotations (all false), the description discloses meaningful behavioral traits: the two-stage retrieval pipeline, the return of source/path and relevance score, and the non-error handling of missing libraries. It does not directly contradict the annotations, though the readOnlyHint=false could be seen as inconsistent with the read-only nature implied, but the description never claims any write behavior.

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 dense sentence containing all essential information without fluff. It is reasonably structured with a colon and semicolon, making it readable despite the density. No word is wasted, though it could be split into clearer sentences for improved scannability.

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 there is no output schema, the description adequately explains the return format (source/path and score) and error handling for missing libraries. It also describes the fallback algorithm. Combined with the schema, it covers the essential aspects for a search tool, though it does not mention pagination or empty-result behavior, which are minor gaps.

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 input schema has full coverage for all three parameters (query, limit, libraries) with descriptions. The tool description does not add additional parameter-level semantics beyond what the schema already provides, 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 clearly specifies the action (search/retrieve), the target resource (SKILL.md from local knowledge base), and the method (two-level retrieval with high-precision then full-text fallback). This distinguishes it from sibling tools focused on other domains and leaves no ambiguity about what the tool does.

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 clear context: it is used to search for skill definitions by keyword, with a documented fallback strategy. It also explains behavior for missing libraries, guiding the agent on what to expect. However, it does not explicitly name alternatives or describe when not to use this tool, so it stops short of full guidance.

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