consult_skill

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose the deprecation status and that it returns 'The persona's perspective,' which are useful behavioral traits. However, it does not explicitly state whether the operation is read-only, whether it has side effects (e.g., session recording), or any limitations/errors. The lack of side-effect discussion for a tool that takes session_id and project_root leaves some ambiguity.

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 structured with clear sections (deprecation notice, usage, args, returns, personas). It is longer than necessary due to a detailed persona list, but that list directly supports the skill_name parameter and is not filler. The deprecation notice, while verbose, is essential for correct tool selection. Overall, each section earns its place, and the front-loaded deprecation notice is well-positioned.

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 simple 4-parameter tool with an output schema, the description provides enough to select and invoke correctly: purpose, usage, parameter semantics, return value, and available personas. The deprecation notice adds crucial context about its lifecycle. However, it omits potential side effects (e.g., whether the consultation is persisted) and any prerequisite conditions (e.g., need project_root for some queries), which slightly reduces completeness. Overall, it is nearly complete for its complexity.

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 0%, so the description must compensate, and it does via an Args section that explains each parameter: skill_name with examples, query as 'Your question,' session_id as 'Session identifier,' and project_root as 'Absolute path to project root.' This adds meaning beyond property names, though it doesn't clarify defaults (e.g., session_id has a default 'default') or formats beyond the examples. Still, it largely fills the gap.

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 opens with 'Consult a single skill persona directly,' which clearly specifies the verb (consult) and resource (skill persona). It also states the purpose: 'Use this when you want guidance from a specific expert without orchestration,' differentiating it from orchestration-heavy siblings like get_engineering_guidance or suggest_mcps_for_query. The provided persona list further clarifies the exact resource scope.

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?

Explicit usage guidance is present: 'Use this when you want guidance from a specific expert without orchestration.' Additionally, the deprecation notice explicitly names the alternative (get_persona_content) and instructs when to use it instead, offering clear when/not-to-use context. This is strong guidance beyond just a generic description.

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