wondel-skills-mcp

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

The description complements the readOnly and idempotent annotations by explaining what a journey contains and how parameters affect the selection. It does not contradict the annotations and adds useful context about the tool's behavior without needing to restate the obvious read-only nature.

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 succinct and well-structured, packing all necessary information into two sentences. It directly states what the tool returns and how to invoke it, with no redundant or confusing wording.

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 description fully explains the tool's output (a journey plan with its components) and the two usage modes, covering both parameters and the tool's behavior. Given the simple schema and no return schema, this is complete and self-contained.

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 already defines each parameter, but the description adds valuable meaning: it explains that 'slug' identifies a specific journey and 'goal' triggers an automatic selection. This clarifies the usage of both optional parameters beyond their basic type definitions, enriching the schema's coverage.

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 that this tool retrieves a guided journey, which is a phase plan with specific components (ordered skills, decision questions, docs file writes, go/no-go gates). It distinguishes from siblings like get_skill or search_skills by focusing on journeys, making its purpose unambiguous.

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?

It explicitly states when to use the tool: pass a slug for a known journey, or pass a goal to have one picked. This gives clear situational guidance, though it doesn't explicitly mention when not to use it in favor of alternatives, which is implicit from the sibling context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, lowering the bar. The description adds genuinely useful behavioral context beyond annotations: the ~300 token cost estimate, the sections widening behavior including the 'all' shortcut, and the explicit statement of what is NOT returned (skill instructions). No contradiction with annotations.

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?

Three sentences, zero filler. The opening sentence establishes purpose, the second adds the cost rationale and the sections mechanic, the third disambiguates from load_skill. Each sentence is front-loaded and 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?

For a metadata-retrieval tool with an output schema, 3 documented params, and strong annotations (readOnly, idempotent), the description covers purpose, usage context, cost behavior, section semantics, and sibling differentiation. The output schema handles return values, so nothing essential is missing.

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 all 3 parameters are documented. The description adds value beyond the schema by explaining the sections param usage pattern ('Pass sections to widen, or sections:[all]'), which the enum list alone doesn't convey. It also contextualizes slug examples indirectly. Slightly above baseline due to the practical 'all' guidance.

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 uses a specific verb+resource ('Metadata for one skill or journey') and enumerates exact content (definition, when to use, when not to, related slugs). It explicitly distinguishes itself from siblings with 'This does not return the skill instructions — load_skill does,' differentiating clearly from load_skill and get_journey.

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 gives explicit when-to-use guidance: 'cheap (~300 tokens) so you can check a candidate before committing context to it' clearly frames the use case. It also names the alternative (load_skill) for skill instructions, giving concrete when-not-to direction, and explains how to widen results with sections.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds value by explaining that the tool not only provides instructions but also lists reference files with token costs, and that further calls can retrieve specific files. This goes beyond the annotations without contradicting them.

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, front-loaded with the core purpose, zero filler. The second sentence efficiently conveys the extra capability (pulling reference files) without verbosity.

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 read-only retrieval tool, the description fully covers the response contents (skill instructions + reference files with token costs) and the usage pattern (set part to a filename). Annotations confirm safety, so no further behavioral disclosure needed.

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 covers 100% of parameters, so baseline is 3. The description adds value by clarifying the default behavior of 'part' (core SKILL.md) and the workflow of re-calling with a reference filename for deeper material, reinforcing the schema's meaning.

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 specifies the verb (load), the resource (skill instructions), and the exact scope ('ready to follow in this session with nothing installed'). It also distinguishes from siblings by clarifying that this returns the skill's actual instructions for immediate use, not just metadata like get_skill or get_journey.

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?

States when to use (to follow the skill's instructions) and explains the two-step workflow (load core, then call again with part set to a filename for deeper material). It doesn't explicitly mention when NOT to use or name sibling tools, but the context is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false. The description adds substantial behavioral detail beyond these flags: it explains the skip logic based on a skill's own 'not for' line, that exclusions are quoted verbatim, and that a guided journey is returned for project-level tasks. This clarifies output structure and decision-making, going beyond what annotations convey.

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?

Three concise sentences, each adding value: the main action, the specific outputs, and a usage directive. Front-loaded with the core purpose, no fluff or repetition. The description is tightly packed and efficient.

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 the output schema exists and annotations are rich, the description covers the essential behavioral contract (what it returns, when to use it, and how it handles task scope). It doesn't detail each parameter's role, but that's already in the input schema. The only minor gap is not explicitly mentioning that context, phase, and stack are used to narrow results, but schema descriptions fill that need. Overall, adequate for the tool's simplicity.

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 100%, so all five parameters already have clear definitions. The description reinforces the task parameter ('Describe the job in your own words') but adds no new semantic meaning beyond the schema. Per the rubric, baseline 3 is appropriate when schema fully covers parameters.

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 states a specific verb+resource ('route a task to the right skills') and details what the tool returns (which skills to load first, which to skip, and a guided journey for project-level tasks). It clearly differentiates from sibling tools by positioning itself as 'the tool to reach for first,' so it stands apart from get_journey, get_skill, load_skill, and search_skills.

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 explicitly says 'This is the tool to reach for first,' giving a clear directive on when to use it (as the initial step for any task). It also hints at when a different response is expected ('when the task spans a whole project') without needing to name alternatives, as the first-step context makes the usage pattern evident.

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

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

Annotations already mark this as read-only and idempotent; the description adds valuable behavioral context: matching is performed against trigger text, compact hits are returned, and each hit quotes the matching line. No contradiction with annotations.

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?

Three sentences, front-loaded with the tool's scope and matching behavior, then the return shape, then the routing alternative. No filler or repetition of schema details.

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 description covers what is searched, how matching works, what results look like, and when to use the sibling instead. Given annotations, a rich input schema, and an output schema, nothing essential is missing for an agent to select and invoke the tool correctly.

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 baseline is 3. The description adds value by explaining why plain task language works (trigger text matching) and by providing query examples that map to the query parameter, going slightly beyond the schema's own descriptions.

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 states a specific verb and resource: search over 51 skills and 14 journeys by keyword or phrase. It also supplies concrete examples ('my UI looks amateur', 'pricing', 'dark mode') and clearly differentiates itself from sibling tools like recommend_skills.

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?

It explicitly tells the agent when to prefer recommend_skills ('when you have a task rather than a keyword'), which is the key routing decision among siblings. The trigger-text matching explanation further clarifies appropriate query language.

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