Recommend a skill flow

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds value by disclosing the advisory-only semantics and that additional candidates are retained (not filtered out or hidden), which is a meaningful behavioral trait. However, it doesn't describe return format, ordering, or how limits interact across sections beyond the schema's param descriptions.

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, both earning their place. The first states the core purpose and the second clarifies the critical advisory/non-hiding behavior. No filler or repetition of what schema/annotations already provide. Loses one point only for not front-loading a strong verb phrase more prominently.

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 non-destructive, advisory tool with excellent annotations and 100% schema coverage, the description is appropriately complete. It covers purpose, scope (installed skills), and key behavioral caveat (advisory only, candidates not hidden). No output schema exists, so return values aren't specified, but for a recommendation tool the structure is reasonably inferable from the schema coverage. Complete enough for safe invocation.

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 schema already documents all three parameters (task, primaryLimit, candidateLimit) with descriptions. The description adds marginal value by clarifying these are installed skills and that candidates aren't hidden. Baseline 3 is appropriate since the schema carries the parameter documentation burden adequately.

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 verb 'recommend' with specific resources (primary, complementary, additional skills) for a task. It differentiates from siblings like inventory_skills (listing) and search_skills (finding specific skills) by framing the deliverable as a curated recommendation flow rather than raw enumeration. Could be slightly stronger by naming that it works across 'installed skills' explicitly versus search across all.

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 of when to use this tool (for a task needing skill recommendations) and importantly clarifies the advisory nature — the agent retains final decision and candidates aren't hidden. It implicitly distinguishes from siblings (inventory lists skills plainly, search finds specific ones) though it doesn't explicitly name alternative tools. A clear when-to-use context with implied exclusions merits a solid score.

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