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

With no annotations provided, the description must fully disclose behavioral traits. It mentions the input parameters and the return summary, but does not state whether the tool is read-only, what happens if no staged changes exist, any permissions needed, or potential side effects. This leaves significant behavioral 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 concise and front-loaded with a clear summary sentence. The 'Args' and 'Returns' sections are structured and each line adds information. However, the inclusion of '(v0.5.0 enhanced)' is unnecessary clutter and doesn't add value for an agent selecting or invoking the tool.

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 an output schema and the description explains the return content in brief, the basic functionality is covered. However, it lacks broader context about when to use this tool in a workflow, what 'relevant engineering contexts' means, or any limitations/requirements. The sibling tools suggest a larger system, and this description does not explain how this tool fits in, making it minimally viable but with clear 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 schema description coverage is 0%, so the description must compensate. It adds meaning beyond the schema titles: 'project_root' is clarified as 'Absolute path', 'include_diff_stats' is explained as 'line change statistics (additions/deletions)', and 'suggest_personas' is described as 'Suggest relevant personas based on change context'. These explanations add genuine semantic value, though they do not cover all possible nuances or defaults (though defaults are in the schema).

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 tool's purpose: 'Analyze staged git changes to identify relevant engineering contexts.' This uses a specific verb (analyze), resource (staged git changes), and intended outcome (identify contexts). It also distinguishes itself from siblings by focusing on git changes rather than queries, sessions, or standards.

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 no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites (e.g., needing staged changes to exist), or scenarios where other tools would be more appropriate. The usage is only implied by the description itself, but no explicit 'when to use' guidance is given.

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?

No annotations are provided, so the description carries the full burden. It only says 'check', which implies a non-mutating read operation, but it does not disclose what happens when inconsistent, whether it depends on an existing session, or any other behavioral details.

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, front-loaded sentence that efficiently states the tool's purpose with no filler or redundancy.

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?

Despite having an output schema, the description lacks context on how session decisions/constraints are accessed, what prerequisites exist (e.g., a session must exist), and why this tool should be selected over the many related session and validation tools. The description is underspecified for a tool with three parameters and no annotations.

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%. The description clarifies 'proposed_change' by using that phrase, but session_id and project_root are completely unexplained. The description does not compensate for the lack of schema documentation.

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 'check' and the resource 'a proposed change' against 'session decisions and constraints', which is specific and distinguishes it from sibling tools like validate_against_standards.

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 usage is implied: use this when you have a proposed change and need to verify consistency with session context. However, there is no explicit guidance on when not to use it or how it differs from alternatives like validate_against_standards or analyze_changes.

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?

With no annotations, the description carries the full burden. It discloses the return format and gives a sense of being a non-destructive comparison, but does not explicitly state read-only behavior, error cases, or system requirements.

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 well-structured with Purpose, Use case, Args, Returns, and Examples. Each section earns its place and is efficiently written, with examples illustrating usage.

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, return values are covered. The description includes inputs, outputs, usage context, and examples. Missing edge behaviors such as error handling or local vs remote session handling, but overall robust.

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 compensates by providing an Args section: 'session_a_id: First session ID', 'session_b_id: Second session ID', 'project_root: Optional project root for local sessions'. This adds meaning beyond the bare schema, though not highly detailed.

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 tool's purpose: 'Compare two sessions and return differences' with a specific verb and resource. It distinguishes from siblings like merge_sessions by focusing on comparison, not merging.

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?

Provides clear context: 'Useful for understanding what decisions and patterns differ between two developer sessions or team branches before merging.' This implies usage timing and purpose, though it does not explicitly name or exclude alternative tools.

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?

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.

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

With no annotations provided, the description carries the full burden. It discloses the return type ('Formatted consultation report') and provides examples, but does not explicitly state whether the operation is read-only, if it writes files, or any permission requirements. This is a moderate level of transparency.

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 well-structured with an intro, use cases, Args, Returns, and Examples. Each section is concise and adds value, with no redundant text. The examples are particularly helpful.

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 tool's moderate complexity (4 params, output schema exists), the description covers purpose, usage, parameters, and return type. It could be more explicit about the relationship between project_root and file output, and explicitly mention export_session_summary as an alternative for session-level exports, but overall it is fairly complete.

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 no parameter descriptions (0% coverage), so the description's Args list provides essential meaning. It explains each parameter (e.g., consultation_id with example, format with allowed values) and examples illustrate typical usage, though it could go deeper on optionality or constraints.

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 tool exports a single consultation as a shareable report, using the specific verb 'export' and resource 'single consultation'. This distinguishes it from sibling tools like export_session_summary, which likely exports session-level data.

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 use cases (sharing decision-making discussions, documenting rationale, creating ADRs) and implies the distinction from session-level exports. However, it does not explicitly mention when not to use this tool or name alternatives like export_session_summary.

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?

No annotations are provided, so the description carries full burden. It discloses that the tool 'Generates' a comprehensive report and returns it, plus details the included components. However, it does not clarify whether 'export' writes to disk or simply returns a string, nor does it address potential side effects or permission requirements. This is a moderate gap given the ambiguity of the word 'export'.

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 well-organized: a one-sentence purpose, a bulleted list of use cases, an Args section with parameter explanations, and a Returns line. Examples are valuable and not duplicated in the schema. Every section earns its place; it is appropriately detailed without being bloated.

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 tool has 5 parameters, no schema descriptions, and no annotations, the description thoroughly covers all necessary aspects: purpose, parameter semantics, return value, and usage examples. It is complete enough for an AI agent to select and invoke the tool correctly without additional context.

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 has zero parameter descriptions, but the tool description compensates fully: it explains format options, the 'include' list with each item's meaning, and provides three concrete examples showing parameter combinations. This adds substantial meaning beyond the bare schema property titles and defaults.

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 'Export comprehensive session summary for team sharing' and goes into detail about producing ADRs, consultation history, and constraints/patterns. This distinguishes it from sibling tools like get_session_summary (which likely retrieves a summary) and export_consultation (which exports a single consultation). The verb+resource+scope is specific and 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?

The description provides explicit use cases under 'Perfect for': onboarding, documenting decisions, sharing knowledge, and creating reports. It does not explicitly mention when NOT to use this tool or name alternatives like get_session_summary, but the use-case list makes the intended scenarios clear, earning a strong score rather than a top score.

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?

No annotations are provided, so the description carries the transparency burden. It discloses the return format ('Markdown-formatted engineering standards') and notes project_root is 'for local rules/sessions', but does not explicitly state read-only behavior or side effects.

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 purpose is stated in one sentence, followed by a clearly structured Args/Returns list. The description is scannable and appropriately sized for a 5-parameter tool with no fluff.

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 purpose, all parameters, and return format, and an output schema exists. It lacks usage guidance and sibling differentiation, but is otherwise adequate for a retrieval tool.

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?

All five parameters are described in the Args section with meaningful context beyond the schema (e.g., operation is 'What you're doing', file_paths is 'List of file paths involved'). This fully compensates for the 0% schema description 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?

Description clearly states 'Get relevant Sensei engineering context for the current task' with a specific verb and resource. It is clear but does not explicitly differentiate from siblings like get_engineering_guidance or get_session_context.

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 implies usage for retrieving engineering standards by listing operation, file_paths, and description as inputs. However, it provides no explicit guidance on when to use this tool versus alternatives or when not to use it.

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?

With no annotations, the description carries the full burden and does disclose orchestration behavior, default mode, return value shape, and legacy standards mode. It also explains the architectural intent (content for Claude to analyze rather than in-server analysis), though it omits permission or rate-limit context.

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 well-structured with Args, Returns, and Examples sections, making it easy to scan. However, the deprecation notice and contradictory status lines add considerable confusing baggage that could be trimmed without losing essential information.

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 complex orchestration tool with multiple modes and alternatives, the description covers purpose, parameters, return semantics, and provides examples. The contradiction between deprecation and 'primary tool' status is a notable gap that affects completeness, but the presence of an output schema reduces the burden for return-value documentation.

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 has 0% description coverage for its six parameters, but the description fully compensates by explaining every parameter, including mode enum values, persona overrides, session/project context, and output format. This adds significant meaning beyond the raw schema.

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 opening line clearly specifies the tool's function (get engineering guidance) and mechanism (multi-persona orchestration), distinguishing it from the granular sibling tools. However, the deprecation notice telling users to prefer new granular tools conflicts with the later claim that this is the NEW primary tool, which slightly muddies the intended purpose.

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 names alternative granular tools and says to use them instead, while also documenting mode-specific use cases (quick, crisis, standards, specific personas). The contradictory statement calling this the 'NEW primary tool' weakens the guidance, preventing a perfect score.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses return format ('JSON with workflow steps, required MCPs, personas, and estimates') and the behavior of optional parameter substitution. It does not explicitly state that the operation is read-only or has no side effects, but the 'Get a template' phrasing implies a safe read operation. The description adds meaningful behavioral context beyond the schema.

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 well-structured with distinct sections: a one-sentence summary, an 'Args' section describing each parameter, a 'Returns' section, and a concrete example. Every sentence earns its place by explaining a template name, parameter usage, or output format. It is appropriately sized for the tool's complexity and remains easy to scan.

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 tool with two parameters, one required, and an output schema present, the description is complete. It explains both parameters, enumerates valid template names, describes the return structure, and provides a working example. With no annotations, it still gives an agent enough context to select and invoke the tool correctly without needing to consult external documentation.

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%, but the description fully compensates. It lists all valid values for template_name in a clear enumeration, which is critical since the schema provides no enum. For the 'parameters' object, it provides an example with fields like 'user_query', 'app_url', and 'framework', showing how substitution works. Both parameters are thoroughly explained despite the lack of schema-level 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 clearly states the tool's purpose: 'Get a pre-built multi-MCP workflow template.' It specifies the resource (pre-built workflow templates) and the action (get), and it distinguishes itself from sibling tools like list_mcp_workflow_templates by focusing on retrieving a single template with customizable parameters rather than listing available ones. The list of available templates further reinforces the specific functionality.

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 strong context for when to use the tool by enumerating the available template names (e.g., 'auth-security-review', 'performance-debug') and giving a concrete example invocation. However, it does not explicitly mention when not to use this tool or directly compare it with alternatives such as list_mcp_workflow_templates. The usage context is clear, but exclusions are missing.

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?

With no annotations, the description carries the full burden and does well. It discloses the return format (markdown), the content composition (expertise, principles, personality, guidelines), and the design philosophy that no analysis is performed—only content is returned. It also details the include_metadata behavior and provides a usage example, offering rich context beyond a mere getter.

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 well-structured with purpose, design philosophy, args, returns, and an example. It is slightly verbose—the design philosophy and example could be condensed—but every section adds value and the critical information is front-loaded in the first two sentences.

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 tool's simplicity (2 params, no annotations) and the presence of an output schema, the description is sufficiently complete. It covers parameter meanings, return type, and the intended downstream usage. It does not discuss edge cases like invalid persona names, but that is not essential for a straightforward retrieval tool.

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 zero description coverage for its two parameters, so the description must compensate and does so thoroughly. It explains persona_name with concrete examples ('security-sentinel', 'pragmatic-architect') and specifies that include_metadata controls the presence of a metadata header (name, description, expertise). This gives the agent full semantic understanding of both arguments.

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 a specific verb-resource pair: 'Get full skill content for a specific persona.' It further clarifies that it returns the complete SKILL.md content, and the explicit design philosophy ('returns CONTENT for the LLM to use, not pre-generated analysis') distinguishes it from analysis-oriented sibling tools like suggest_personas_for_query.

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 states when to use the tool: 'The calling LLM should use this content to analyze queries from that persona's perspective.' It also contrasts with pre-generated analysis, implying when not to rely on it. However, it does not explicitly name alternative sibling tools to choose instead, which would have made the guidance even stronger.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool returns session memory as data, avoiding any implication of side effects, and specifies the return format as JSON with constraints, patterns, and decisions. However, it omits details about error conditions (e.g., nonexistent session) or permission requirements, which would enhance transparency.

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 well-structured and front-loaded with the core purpose. The additional sections (Args, Returns, Example, Design Philosophy) are each concise and contribute directly to understanding usage. No sentence is wasted, and the length is appropriate given the lack of schema descriptions and annotations.

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 tool's low complexity (2 optional parameters) and the presence of an output schema, the description is thorough. It covers purpose, usage, parameter meaning, return values, and an example. It also explains the intended integration with personas, making it fully sufficient 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 description coverage is 0%, so the description must compensate. It provides brief but meaningful semantics: session_id is the session identifier, and project_root is an optional project root for local sessions. This adds context beyond the raw schema types and defaults, though it could elaborate further on accepted formats or behaviors.

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 tool gets session context (constraints, decisions, patterns) for context-aware analysis. This specific resource listing distinguishes it from sibling tools like get_session_summary or get_engineering_context, 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?

The description explicitly explains when to use the tool: to ensure consistency with previous decisions and agreed patterns. It goes further to describe the MCP design philosophy and provides a concrete example of how the returned context should be included in prompts to personas, offering clear usage guidance.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly details what the tool returns (including specific report sections) and clarifies parameter behavior (e.g., project_root is 'for local sessions', time_range options, format options). It does not explicitly state whether the operation is read-only or has side effects, but the 'Get' verb and analytic nature make it strongly inferred as non-mutating.

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 well-structured with clear sections (overview, Args, Returns, Examples) and is appropriately sized for the complexity. It includes useful examples and return details without excessive verbosity. Slightly longer than necessary, but every sentence earns its place by providing actionable information.

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 tool's complexity (4 parameters, rich analytics output) and the absence of annotations or an output schema, the description is exceptionally complete. It covers purpose, parameter semantics, return format, and usage examples. The output section clearly enumerates what the report will contain, making it easy for an agent to understand the tool's capabilities and limitations.

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%, but the description compensates fully by providing detailed semantics for every parameter: session_id ('Session identifier'), project_root ('Absolute path to project root'), time_range (with enumerated values and defaults), and format (with allowed values). This goes far beyond the bare schema and adds essential context for proper usage.

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 tool's purpose: 'Get comprehensive analytics and insights for a session.' It uses a specific verb ('Get') and resource ('session insights'), and enumerates the types of insights (persona usage, decision trends, health metrics). This distinguishes it from sibling tools like get_session_summary, which likely provides a basic summary rather than deep analytics.

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 implies usage through parameter explanations and examples (e.g., 'Get all-time insights', 'Last 30 days in JSON'), but does not explicitly state when to choose this tool over alternatives like get_session_summary or export_session_summary. There are no exclusions or alternative recommendations, so guidance is implied rather than explicit.

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?

With no annotations, the description carries the full burden, but it only says 'Get a summary' without explaining permissions, side effects, return format specifics, or behavior with default parameters. It implies a read operation but adds minimal context beyond the tool's name.

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 brief and well-structured with Args and Returns sections, avoiding redundancy. However, its brevity sacrifices essential details, keeping it from a perfect score.

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?

Despite having an output schema, the description lacks full context: it doesn't clarify how project_root is used, whether session_id is required despite having a default, or how this differs from get_session_context. The presence of many sibling summary/context tools makes this insufficient.

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, but it only offers terse labels like 'Session identifier' and 'Absolute path to the project root.' It does not explain defaults, nullability, or how session_id relates to 'current session.'

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 it retrieves a summary of session decisions and context, using a specific verb and resource. However, it does not differentiate this tool from sibling tools like get_session_context or export_session_summary.

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?

No guidance is provided on when to use this tool versus alternatives like export_session_summary or get_session_insights. There are no exclusions, prerequisites, or example use cases.

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?

No annotations are provided, so the description carries full burden. It transparently states the action ('List'), the return value ('Formatted list of available personas'), and the varying detail levels. The examples demonstrate expected behavior, and there is no indication of side effects or hidden complexities.

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 well-structured with Args, Returns, and Examples sections, and the purpose is front-loaded. It is longer than strictly necessary due to four example blocks, but each example is useful and the overall layout remains scannable.

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 list tool, the description covers lifecycle, parameters, output formats, and usage scenarios. The presence of an output schema reduces the need to enumerate return fields, and the description sufficiently contextualizes the tool among its sibling listing/query tools.

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 0%, but the description fully compensates by documenting both parameters. 'category' lists all valid values, and 'format' explains the three output modes with behavioral differences. This gives the agent all parameter-level semantics needed.

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 'List all available skill personas with flexible detail levels', a specific verb+resource pair that immediately conveys the tool's function. It is clearly distinguished from sibling tools like get_persona_content and consult_skill, which focus on individual persona details or interactive consultation.

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 context by explaining the 'format' parameter options (standard, detailed, quick) and the category filter, with examples showing typical usage. However, it does not explicitly state when to choose this tool over alternatives, nor does it mention exclusions or fallback tools.

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?

No annotations are provided, so the description carries the full burden. It discloses the return format (JSON array with descriptions and example parameters) and an example result. However, it does not explicitly state that the operation is read-only or has no side effects, which would be useful for full transparency. The example helps, but the safety profile is not explicitly addressed.

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 well-structured with a main description, return specification, and example. It is not overly verbose, though the example section could be slightly tightened. The information is front-loaded with the core purpose in the first line, and each section serves a purpose.

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 zero-parameter listing tool with an output schema, the description is complete: it states what is being listed, the return type and content, and provides an example. There is no ambiguity about what the tool does or what it returns. The presence of an output schema further reduces the need to detail return values, and the description still covers them.

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 tool takes zero parameters, and the schema coverage is 100% (vacuous). The baseline for 0 params is 4. The description adds context about the example invocation and return value, but since there are no input parameters to explain, the score aligns with the baseline.

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?

Description clearly states 'List all available demonstration workflows' with a specific verb and resource. It further distinguishes itself from siblings by mentioning 'multi-MCP orchestration capabilities', which separates it from list_available_skills, list_sessions, and list_mcp_workflow_templates.

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 lists executable demos that showcase orchestration. It implies usage for discovering available demos, but does not explicitly say when to use it versus run_demo or when not to use it. Hence, clear context but no explicit exclusions or alternatives.

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?

With no annotations, the description carries the full burden. It discloses the return type (JSON array), the key fields included (descriptions, required MCPs, cost estimates, time estimates), and provides an example with a count. It does not mention side effects or permissions, but for a read-only list operation this is reasonable.

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 well-structured and front-loaded with the core statement, followed by concise details about the return value, a formal 'Returns' line, and an illustrative example. No unnecessary words; every sentence contributes meaning.

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 zero-parameter list operation, the description is sufficiently complete. It describes the return content and structure, and the output schema exists (as noted in context signals), so the description need not explain return values in depth. Minor gaps remain (e.g., pagination, performance), but these are not critical for a simple list tool.

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 zero parameters, so parameter semantics are not applicable. The baseline score of 4 applies. The description appropriately adds value by describing what the returned data contains, which is more useful than parameter explanations.

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 a clear, specific verb and resource: 'List all available multi-MCP workflow templates.' The phrase 'all available' explicitly distinguishes this from the sibling tool 'get_mcp_workflow_template' which retrieves a single template. The purpose is 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?

The description implies usage context by stating it lists all templates, and the sibling list includes a singular getter, but it does not explicitly say 'When you need a specific template, use get_mcp_workflow_template.' There are no explicit alternatives or exclusions, so the guidance is implied rather than explicit.

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?

With no annotations, the description carries the transparency burden. It discloses the key behavioral nuance (global vs local) but does not mention return format, permissions, or side effects. For a simple list operation, this is adequate but not rich.

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 two short sentences, front-loaded with the main action, and every word adds value. No redundancy or filler.

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 zero parameters, a clear scope note, and an output schema, the description covers everything necessary 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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter details, but none are needed since the schema is empty.

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 'List all available sessions in the global directory' with a specific verb and resource. The note differentiating from local project sessions further clarifies the scope and distinguishes it from potential alternatives.

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 gives clear context by specifying 'global directory' and explicitly notes what it does NOT list (local project sessions). While it doesn't name alternative tools, the exclusion helps the agent understand when to use this tool.

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?

With no annotations, the description carries the full burden. It discloses conflict resolution strategies, return statistics, and attribution tracking, but does not specify whether source sessions are modified or what happens if the target session already exists. This missing side-effect information is important for a merge operation.

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 well-structured with Args, Returns, and Examples, and it front-loads the core purpose. It is slightly longer than necessary due to the version tag and multiple examples, but every section adds practical value.

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 is complete for a tool with four parameters and an output schema: it explains behavior, parameter options, return value, and provides three usage examples. The output schema is already present, so the Returns line sufficiently summarizes output.

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 0%, but the description fully explains all four parameters, including the meaning of each conflict_strategy option and optional project_root. Examples further clarify parameter usage, making the description the primary source of semantic information.

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 tool merges multiple sessions into a single target session, with a specific verb and resource. This distinguishes it from siblings like compare_sessions and export_session_summary by focusing on the merging action.

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: teams combining session insights from multiple developers and resolving conflicts. It does not explicitly list alternatives or when not to use it, but the intended use case is evident from the examples and conflict strategy explanation.

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?

With no annotations, the description carries the full burden of behavioral disclosure. The word 'Query' strongly implies a read-only operation, which is helpful, but the description does not elaborate on potential side effects, required permissions, or the nature of the returned data. Since it is a simple query tool, this minimal transparency is acceptable but not rich.

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, focused sentence that immediately conveys the core functionality. It is front-loaded with the action and resource, and contains no filler or repetition. Every word adds value.

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 query tool with an output schema, the description provides a basic understanding. However, it lacks guidance on when to prefer this tool over siblings and omits any mention of the optional session_id and project_root parameters. This makes the description minimally complete but not fully self-sufficient.

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 for all parameters. It implicitly explains 'section_name' via 'directly by name', but completely ignores 'session_id' and 'project_root'. Given that there are three parameters and only one is touched, the description does not sufficiently bridge the gap left by the schema.

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 tool's action ('Query'), the target resource ('specific section of the rulebook'), and the method ('directly by name'). This distinguishes it from sibling tools that suggest broader guidance or validation, such as get_engineering_guidance or validate_against_standards.

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 phrase 'directly by name' provides clear context: use this tool when you know the exact section name and want to retrieve that section. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of full exclusionary guidance.

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?

No annotations are provided, so the description carries the full burden. It states the primary effect ('record the consultation') and the return value ('Confirmation with consultation ID'), but doesn't disclose prerequisites, failure modes, or whether the operation is reversible. For a logging tool, this is adequate but not deeply transparent.

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 well-structured: a one-line summary, a contextual sentence, an Args block, a Returns line, and an Example. Every section serves a purpose, and the content is front-loaded with the main verb and object.

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 tool's simplicity (5 params, 2 required), the description covers purpose, usage trigger, all parameter semantics, return value, and an example. No output schema is provided in the context, but the Returns line clarifies the output. This is complete for an MCP logging tool.

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 parameter descriptions (0% coverage), but the description's Args section explains each parameter: query (original query), personas_used (list of consulted personas), session_id, project_root (optional), and synthesis (optional recommendation). This fully compensates for the schema gap and adds meaning beyond the bare types.

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?

Description opens with 'Record a consultation in session history,' a specific verb+resource statement. It adds context that it's used after Claude analyzes a query with persona content, helping distinguish from the sibling record_decision. However, it doesn't explicitly contrast with alternative tools.

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 states a clear trigger: 'After Claude analyzes a query using persona content, record the consultation for session analytics and history.' This provides clear when-to-use context, but it does not mention when not to use or name alternative tools like record_decision.

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?

With no annotations, the description carries the burden of behavioral disclosure. It explains that optional constraint and pattern parameters modify active constraints and agreed patterns, and that the tool returns a confirmation with a decision ID. It does not mention persistence or permissions, but enough behavior is disclosed for a record operation.

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 and well-structured, with a clear one-liner followed by an Args list and Returns statement. Every parameter earns its place, and the layout is easy to scan. No unnecessary fluff.

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 7-parameter tool with no annotations, the description is complete: it covers all parameters, describes the return value, and notes optional side effects. The output schema exists, so return details are not over-explained, but the description still provides the key info. It adequately fulfills its contextual role.

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 0% (no descriptions in the schema), yet the description compensates fully by explaining every parameter: category with examples, description, rationale, session_id, optional constraint/pattern with their effects, and project_root. This is a comprehensive mapping that adds significant meaning beyond the raw schema.

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 'Record an architectural or technical decision for this session,' which clearly specifies the verb (record), resource (decision), and scope (for this session). It distinguishes itself from sibling tools like record_consultation by focusing on decisions rather than consultations.

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 implies usage: use this when you need to log a decision. It provides context about optional side effects (adding constraints/patterns) but does not explicitly state when to prefer this over alternative tools, nor does it mention any exclusions or prerequisites.

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?

With no annotations, the description carries the full burden of disclosing behavior. It states that the tool runs a self-contained demo, combines external MCPs, and returns a comprehensive report including workflow steps and expected output structure. It does not explicitly mention side effects or that no real changes occur, but 'self-contained demo' strongly implies a safe, simulated execution.

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 well-structured with clear sections (Args, Returns, Examples) and uses bullet lists to enumerate options. Every sentence adds value, and the length is appropriate for the tool's complexity. It is front-loaded with the core purpose and then provides detailed parameter guidance.

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 nested custom_params object and multiple demo types, the description is complete enough for an agent to select and invoke correctly. It covers all parameters, provides concrete examples, explains the return value, and even tells the user how to run the demo themselves. No critical gaps remain.

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 description provides rich detail beyond the schema: it lists all available demo types, gives an example of custom_params structure, and shows usage examples for output_format. This fully compensates for the 0% schema description coverage, making parameter usage unmistakable.

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 ('Execute a demonstration workflow') and identifies the specific resource ('showcases multi-MCP orchestration'). It clearly distinguishes itself from sibling tools like list_demos or get_mcp_workflow_template by focusing on actually running a demo rather than listing or providing templates.

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 use cases ('Testing multi-MCP coordination', 'Generating example documentation', etc.), which helps an agent decide when to invoke it. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of fully explicit guidance.

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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It adequately reveals that the tool analyzes the query and returns JSON with suggestions, rationale, workflows, and cost/time estimates. While it doesn't explicitly state 'does not modify state,' the analytical nature and return specification make the behavior clear.

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 well-structured with clear sections: summary line, Args, Returns, and Example. Every sentence contributes meaningful information, and the example is illustrative without being verbose. This is appropriately sized for a tool with three parameters.

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?

Despite the absence of annotations, the description is comprehensive. It covers the tool's purpose, parameter semantics, return value structure, and a realistic use case. The presence of an output schema reduces the need to detail return values, but the description still provides a useful example of what the output looks like.

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 has 0% description coverage, but the description's Args section fully compensates by adding meaning beyond the raw schema. It explains the context parameter with options (SECURITY, COST, etc.), describes user_mcps as a filter, and provides a complete example with actual parameter values.

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 ('suggest') and resource ('MCP servers'), clearly distinguishing this from sibling tools like get_mcp_workflow_template or consult_skill. It states the exact function: analyzing a query and recommending appropriate MCP servers.

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 for when to use this tool ('for a given query') and includes a concrete example for a security review scenario. However, it doesn't explicitly mention when not to use it or name alternative tools, so it falls short of full usage-guideline coverage.

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?

With no annotations provided, the description carries the burden. It discloses that the tool uses keyword matching, context detection, and relevance scoring, does not perform analysis itself, and returns a JSON list with scores and rationale. This is reasonable transparency, though it doesn't explicitly state read-only status or edge-case behaviors.

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 somewhat long but well-structured with sections for purpose, philosophy, Args, Returns, and Example. Each sentence adds value; the example is pragmatic. It earns a slight deduction for redundancy (e.g., 'JSON list of suggested personas with relevance scores and rationale' appears in both Returns and Example).

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 suggestion tool with an output schema, the description covers all needed aspects: purpose, usage workflow, parameter semantics, return format, and a concrete example. It is complete enough 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?

Despite the input schema lacking descriptions (0% coverage), the description includes an 'Args' section that explains each parameter: query, max_suggestions (with default), and context_hint (with example). This fully compensates for the schema gaps, making the parameters clear.

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 'Suggest relevant personas for a given query', a specific verb+resource that distinguishes this from sibling tools like get_persona_content (which retrieves content) and suggest_mcps_for_query (which suggests MCPs). The purpose is unmistakable.

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 'MCP Design Philosophy' explains that this tool is for discovering which personas to consult and that the LLM should then call get_persona_content() for each recommendation. This gives clear workflow context, though it doesn't explicitly state when NOT to use it or contrast with alternatives.

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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It states it 'Returns: Structured validation report,' but does not disclose any side effects, read-only nature, required permissions, or how validation is scoped. This lack of behavioral transparency is a significant gap.

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 well-structured and compact: a one-line purpose, a clean Args list, and a Returns line. Every element adds value, and the format is easily scannable. There is no fluff or redundant repetition of the schema.

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?

Despite having an output schema, the description remains incomplete for a tool with five parameters and no annotations. It does not explain the validation criteria, how to interpret the report, or the role of session_id. Given the abundance of similar sibling tools, richer context is needed for proper 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?

With schema description coverage at 0%, the description compensates by providing human-readable explanations for each parameter (e.g., 'Code to validate (optional)', 'Specific areas to check'). This adds meaning beyond the bare parameter names, though it could be enriched with more detail about how parameters interact or expected formats.

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 tool's function: 'Validate code or design against Sensei engineering standards.' It specifies the resource (code/design) and the action (validate), making the purpose immediately understandable. However, it does not explicitly distinguish itself from similar sibling tools like check_consistency or query_specific_standard, so it falls short of a perfect score.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios that would favor another tool. The only context is the general 'validate code or design,' which leaves the agent without clear direction on selection.

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