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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'evaluation' and 'quality grades' but doesn't specify what the tool does operationally—e.g., whether it analyzes dependencies, runs tests, or generates reports. It lacks details on performance, side effects, or output format, which is critical for a tool with no output 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 a single, efficient phrase: 'Comprehensive architecture evaluation with quality grades'. It's front-loaded and wastes no words, though it could be more specific. However, for a tool with 4 parameters and no annotations, it might be overly concise, leaving key details implied rather than stated.

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 4 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., grades, scores, recommendations) or how the evaluation is performed. For a tool named 'evaluate' with siblings that might overlap, more context is needed to guide effective use.

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 75%, with clear descriptions for 'packages', 'devDependencies', and 'framework', but 'ecosystem' lacks a description (only an enum). The tool description adds no parameter-specific information beyond the schema, such as explaining how these inputs affect the evaluation or what 'quality grades' are based on. With moderate schema coverage, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Comprehensive architecture evaluation with quality grades' states the general purpose (evaluation) but is vague about what specifically is evaluated and what 'quality grades' entail. It mentions 'architecture' but doesn't specify if this refers to dependency structure, code organization, or other aspects. It doesn't clearly distinguish from siblings like 'signals.evaluate' or 'stack.validate' which might overlap.

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. With siblings like 'dependency.health', 'stack.validate', and 'signals.evaluate', the description offers no context on whether this is for initial assessment, ongoing monitoring, or specific scenarios. There's no mention of prerequisites, alternatives, or exclusions.

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 full burden for behavioral disclosure. It mentions the tool provides 'adoption stats and migration effort' which gives some behavioral context, but doesn't cover important aspects like whether this is a read-only operation, potential rate limits, authentication requirements, or what format the results come in. For a tool with 4 parameters and no output schema, this is insufficient.

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, efficient sentence that gets straight to the point. Every word contributes to understanding the tool's purpose without any wasted text. It's appropriately sized for what it communicates.

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 4 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what the output looks like (format, structure), doesn't mention any constraints or limitations, and provides minimal behavioral context. Given the complexity and lack of structured metadata, the description should do more to help an agent understand how to use this tool effectively.

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 75% (3 of 4 parameters have descriptions), so the baseline is 3. The description doesn't add any parameter-specific information beyond what's in the schema. It doesn't explain how 'framework context for ranking' works, what 'adoption stats' includes, or how 'migration effort' is calculated.

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 'find' and the resource 'alternative packages', with additional context about what information is provided ('adoption stats and migration effort'). It distinguishes from some siblings like dependency.explain or dependency.health, but doesn't explicitly differentiate from all alternatives like dependency.trends or stack.recommend.

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 like dependency.trends, stack.recommend, or dependency.safe-upgrade. It doesn't mention prerequisites, exclusions, or specific scenarios where this is the appropriate choice among the 9 sibling 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the output includes 'health, risk, and recommendations' but doesn't describe the format, depth, or limitations of the explanation. It doesn't address whether this is a read-only operation, potential rate limits, authentication needs, or error conditions.

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, efficient sentence that front-loads the core purpose. Every word earns its place, with no redundant or vague phrasing. It's appropriately sized for a tool with clear functionality.

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 6 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain the return format, error handling, or how the comprehensive explanation integrates the various input parameters. The agent would lack critical context to use this tool effectively.

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 high (83%), providing good documentation for most parameters. The description adds minimal value beyond the schema, only implying that parameters like 'includeAlternatives' and 'includeMigrations' relate to the 'comprehensive explanation' concept. It doesn't explain how parameters interact or affect the output.

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 ('Get comprehensive explanation') and resource ('of a package'), specifying what information will be provided (health, risk, recommendations). It distinguishes from sibling tools like dependency.health (which likely focuses only on health) and dependency.alternatives (which likely focuses only on alternatives), though the differentiation could be more explicit.

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 like dependency.health or dependency.alternatives. It doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage based on the tool name and description alone.

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 of behavioral disclosure. It mentions the tool checks for 'deprecated, vulnerable, unmaintained' status, which hints at read-only behavior, but doesn't clarify if it requires authentication, has rate limits, or what the output format looks like. For a tool with zero annotation coverage, this is insufficient.

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 extremely concise and front-loaded in a single phrase, with no wasted words. Every part ('Quick health check for a package (deprecated, vulnerable, unmaintained)') directly contributes to understanding the tool's purpose, making it efficient and well-structured.

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 no annotations, no output schema, and incomplete parameter documentation (50% coverage), the description is inadequate. It doesn't explain what the health check returns, how results are formatted, or any behavioral constraints, leaving significant gaps for an AI agent to use the tool effectively.

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 50% (only the 'package' parameter has a description), and the description adds no additional parameter details beyond what's implied by 'package' in the context. It doesn't explain the 'ecosystem' parameter or provide examples, so it doesn't compensate for the coverage gap, resulting in a baseline score.

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: 'Quick health check for a package' with specific criteria (deprecated, vulnerable, unmaintained). It uses a specific verb ('check') and resource ('package'), though it doesn't explicitly differentiate from siblings like dependency.alternatives or dependency.trends, which prevents a score of 5.

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 like dependency.alternatives or dependency.safe-upgrade. It lacks context about prerequisites, exclusions, or specific scenarios where this health check is most appropriate, leaving the agent to infer usage.

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 of behavioral disclosure. It mentions 'breaking change analysis' but doesn't specify what 'safe' means (e.g., compatibility checks, risk levels, or recommendations), nor does it cover aspects like rate limits, authentication needs, or output format. This leaves significant gaps for an agent to understand the tool's behavior beyond basic purpose.

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, efficient sentence that front-loads the core purpose ('Evaluate if upgrading a package is safe') and adds key context ('with breaking change analysis'). There is no wasted text, and it's appropriately sized for the tool's complexity, making it easy for an agent to parse quickly.

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 no annotations and no output schema, the description is incomplete for a tool with 4 parameters and behavioral complexity. It covers the basic purpose but lacks details on what 'safe' entails, how results are returned, or any error handling. This is adequate as a minimum viable description but has clear gaps that could hinder an agent's ability to use the tool effectively 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?

Schema description coverage is 75%, with parameters like 'package' and 'currentVersion' well-described in the schema. The description adds no additional parameter semantics beyond implying 'breaking change analysis' for the upgrade evaluation, which doesn't clarify parameter usage beyond what the schema provides. Since coverage is high (>80% threshold not met, but close at 75%), the baseline of 3 is appropriate as the schema does most of the work.

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 'evaluate' and the resource 'upgrading a package', specifying the purpose as analyzing breaking changes for safety. It distinguishes from siblings like dependency.alternatives or dependency.trends by focusing on upgrade safety rather than alternatives or trends. However, it doesn't explicitly differentiate from dependency.explain or dependency.health, which might overlap in analyzing dependencies.

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 when considering a package upgrade to assess safety, but it doesn't explicitly state when to use this tool versus alternatives like dependency.alternatives (for finding alternatives) or dependency.health (for general health checks). No exclusions or specific contexts are provided, leaving some ambiguity about optimal 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does (get trend data) but lacks critical behavioral details: it doesn't specify data sources, timeframes for trends, update frequency, rate limits, authentication needs, or what the output looks like (e.g., numerical trends, visualizations). For a tool with no annotations, this leaves significant gaps in understanding its 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 a single, efficient sentence that front-loads the core purpose ('Get trend data for a package') and adds specific detail ('rising, stable, declining'). There is no wasted verbiage, and every word contributes to understanding the tool's function.

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 (trend analysis with 3 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what trend data entails (e.g., metrics, time periods), how results are returned, or prerequisites for use. For a data-fetching tool with multiple inputs and no structured output documentation, more context is needed to guide effective usage.

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 67% (2 of 3 parameters have descriptions), with the 'package' and 'framework' parameters documented but 'ecosystem' relying on an enum without a description. The description adds minimal value beyond the schema: it implies 'package' is the target and hints at trend types, but doesn't clarify parameter interactions (e.g., how framework or ecosystem affect trends) or provide examples. Baseline 3 is appropriate given moderate schema 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 the action ('Get trend data') and resource ('for a package'), specifying the types of trends (rising, stable, declining). It distinguishes from siblings like dependency.health or dependency.alternatives by focusing on trend analysis rather than health metrics or alternative packages. However, it doesn't explicitly differentiate from all siblings in the dependency category.

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 like dependency.health (for overall package health) or dependency.alternatives (for finding substitutes). It mentions trend types but doesn't specify scenarios where trend data is preferred over other dependency metrics or how it complements sibling 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 of behavioral disclosure. It states the tool 'Get reward signal', which implies a read-only, non-destructive operation, but doesn't elaborate on what a 'reward signal' entails, potential side effects, rate limits, or authentication needs. For a tool with 7 parameters and no annotations, this is a significant gap in 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 a single, efficient sentence: 'Get reward signal for add/remove/upgrade/replace actions'. It is front-loaded with the core purpose, has zero wasted words, and is appropriately sized for the tool's complexity, making it highly concise and well-structured.

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 7 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what a 'reward signal' is, how it's used, or the expected return values, leaving significant gaps for an AI agent to understand the tool's full context and behavior.

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 high at 86%, so the schema already documents most parameters well. The description adds minimal value beyond the schema by hinting at the action types ('add/remove/upgrade/replace'), but it doesn't provide additional context like parameter interactions or usage examples. This meets the baseline for high schema 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 the tool's purpose: 'Get reward signal for add/remove/upgrade/replace actions'. It specifies the verb ('Get reward signal') and the resource/scope ('add/remove/upgrade/replace actions'), making it understandable. However, it doesn't explicitly differentiate from sibling tools like 'architecture.evaluate' or 'dependency.safe-upgrade', which might also evaluate actions, so it doesn't reach the highest clarity level.

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 doesn't mention any context, prerequisites, or exclusions, and with multiple sibling tools like 'dependency.safe-upgrade' or 'stack.recommend' that might overlap in functionality, the agent lacks explicit direction on tool 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but doesn't explain how it behaves—e.g., whether it's a read-only operation, if it requires authentication, what happens on errors, or the format of returned data. This leaves significant gaps for a tool with three parameters and no output 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 a single, efficient sentence that front-loads the core action without any wasted words. It's appropriately sized for the tool's complexity, making it easy to parse quickly.

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 three parameters, no annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like safety, error handling, or return format, which are crucial for an agent to use the tool effectively without structured guidance.

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 100%, so the input schema already documents all three parameters thoroughly. The description adds no additional meaning beyond implying the tool fetches defaults, which is consistent with the schema but doesn't provide extra context like example frameworks or category 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?

The description clearly states the verb ('Get') and resource ('canonical/default packages for a framework'), making the purpose understandable. However, it doesn't distinguish this tool from sibling tools like 'stack.recommend' or 'stack.validate', which might also involve package-related operations, so it lacks explicit differentiation.

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, such as 'stack.recommend' or 'dependency.alternatives'. It doesn't mention prerequisites, exclusions, or specific contexts, leaving the agent to infer usage based on the name alone.

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 of behavioral disclosure. It states the tool 'gets' recommendations, implying a read-only operation, but doesn't clarify if it's a query, a generative process, or if it has side effects like caching. There's no information on rate limits, authentication needs, or what the output looks like (e.g., structured data or free text), which is critical for a tool with 7 parameters and no output 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 a single, clear sentence: 'Get stack recommendations based on use cases and requirements.' It's front-loaded with the core purpose, has zero wasted words, and efficiently communicates the tool's intent without unnecessary elaboration. This makes it easy for an agent to parse and understand quickly.

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 complexity (7 parameters, nested objects, no output schema, and no annotations), the description is incomplete. It doesn't address behavioral aspects like how recommendations are generated, what the return format is, or any constraints on use. For a tool that likely outputs complex data (stack recommendations), the lack of output schema means the description should at least hint at the response structure, but it doesn't, leaving significant gaps for the agent.

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 43% (3 out of 7 parameters have descriptions), which is low. The description mentions 'use cases and requirements,' hinting at parameters like 'useCases' and possibly 'priorities' or 'constraints,' but it doesn't add specific meaning beyond the schema. For example, it doesn't explain how 'framework' interacts with 'useCases' or what 'projectClass' entails. The description compensates minimally, so a baseline score of 3 is appropriate given the partial 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 the tool's purpose: 'Get stack recommendations based on use cases and requirements.' It specifies the verb 'Get' and resource 'stack recommendations' with the criteria 'use cases and requirements.' However, it doesn't differentiate from sibling tools like 'stack.defaults' or 'stack.validate,' which might offer similar functionality, leaving some ambiguity about when to choose this specific tool.

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. With siblings like 'stack.defaults' and 'stack.validate,' it's unclear if this tool is for general recommendations, while others might provide defaults or validation. There's no mention of prerequisites, exclusions, or specific scenarios that warrant its use over other tools, leaving the agent to guess based on tool names alone.

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 tool validates for 'conflicts, redundancies, and issues' but doesn't disclose behavioral traits such as whether it's read-only (likely, but not confirmed), what output format to expect, if it has side effects, rate limits, or authentication needs. For a validation tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.

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, efficient sentence that front-loads the core purpose ('Validate a stack') and specifies the validation targets. There is no wasted verbiage, repetition, or unnecessary elaboration, making it highly concise and well-structured for quick comprehension.

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 complexity (validation tool with 3 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the validation output includes (e.g., report format, severity levels), behavioral constraints, or how it integrates with sibling tools. For a tool that likely produces detailed results, more context is needed to guide effective use.

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 67% (2 out of 3 parameters have descriptions), with 'packages' and 'framework' documented but 'ecosystem' lacking a description. The tool description adds no parameter-specific information beyond what the schema provides. With moderate schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate for the undocumented 'ecosystem' parameter or enhance understanding of the documented ones.

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 action ('validate') and target ('a stack'), specifying what gets validated ('for conflicts, redundancies, and issues'). It distinguishes from siblings like 'stack.defaults' or 'stack.recommend' by focusing on validation rather than configuration or suggestions. However, it doesn't explicitly differentiate from 'architecture.evaluate' or 'signals.evaluate' which might also assess technical issues.

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 doesn't mention prerequisites, timing (e.g., before deployment), or compare to siblings like 'dependency.health' for dependency-specific checks or 'architecture.evaluate' for broader architectural validation. Usage is implied only by the tool's name and description.

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