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

Annotations are absent, so the description carries the behavioral disclosure burden. It mentions the output type (added, removed, modified APIs), which is useful, but does not explicitly state that the operation is read-only, or disclose any side effects, limitations, or potential failures. 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 sentences, front-loaded with the main action and outcome, and contains no redundant text. Each sentence contributes distinct 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?

With no output schema and no annotations, the description gives a general sense of output (added/removed/modified APIs) but lacks details on output structure, default behaviors (e.g., summary vs. detailed), or any operational caveats. The schema is rich, but the description could be more complete for a 6-parameter 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?

Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds no extra nuance about parameters beyond reiterating that it compares two versions. Baseline 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 clearly states the tool's function: comparing API differences between two library versions and listing added, removed, and modified APIs. This specific verb+resource combination distinguishes it from sibling tools like resolve-library or suggest-migration-path, which focus on different tasks.

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 a clear use case: 'useful for understanding breaking changes and new features when upgrading.' This implies when to use the tool, though it does not explicitly mention alternatives or when not to use it, which prevents a 5.

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 does not state whether the operation is read-only, what output format to expect, or any potential side effects. The agent is left without crucial context about the tool's behavior, especially given the lack of an 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, focused sentence that starts with the action verb 'Detects' followed by the specific resources. It contains no extraneous information and is easy to parse quickly, scoring top marks for conciseness and front-loaded structure.

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 tool with one parameter, the description is brief but incomplete. Since there is no output schema, it should state what the tool returns (e.g., version numbers, package names) to help the agent use the result. It also lacks usage guidance, making the description insufficient for full contextual understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides a clear description for the single 'cwd' parameter ('The current working directory to check.'), and schema coverage is 100%. The description adds minimal extra meaning by referring to 'current project,' which aligns with the schema, but does not introduce new details. Baseline 3 is appropriate when the schema fully covers parameters.

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

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

The description clearly states the tool's function: detecting versions of specific frameworks (React Native, Expo, React Navigation, Ignite) in the current project. This is specific and distinguishes it from sibling tools like resolve-library or compare-api-versions, which focus on different actions.

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 when to use it: when you need to know the versions of these libraries in the current project. However, it does not explicitly state when not to use it or mention alternatives, leaving the agent to infer the appropriate context from the tool's name and purpose.

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 present, so the description carries the full burden of disclosing behavior. It only mentions 'using the index' without explaining what that means, what side effects (if any) exist, what triggers failures, or what the return format is. This is insufficient for a tool with 4 parameters.

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 concise sentence with no wasted words. It is appropriately short for a simple tool, though it sacrifices helpful details for brevity.

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 4 parameters, no output schema, and no annotations, the description is too minimal. It does not explain the role of 'cwd', the 'auto' version default, what 'the index' refers to, or how results are structured. This is incomplete for an agent to use confidently.

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 only 25% (only 'topic' is described). The description adds no parameter semantics at all—it doesn't explain 'library', 'version', 'cwd', or how they interact. With low schema coverage, the description was expected to compensate but fails to do so.

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 core function: 'Finds code examples for a specific topic using the index.' It uses a specific verb and resource. However, it does not explicitly distinguish it from sibling tools like search-docs or semantic-search-docs, and the phrase 'using the index' is vague.

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 compared to alternatives. With siblings like search-docs, get-library-docs, and semantic-search-docs, the description offers no distinctions, exclusions, or when-not-to-use advice.

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 alone must convey behavioral traits. It mentions 'generates configuration files' (a write operation), but does not disclose whether files are written to disk, if existing files are overwritten, or any side effects. The schema notes that outputDir is optional and content is returned if omitted, but this isn't in the description.

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 action and purpose in the first sentence. The second sentence adds value by explaining the output's benefits without unnecessary 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?

The description covers the tool's purpose and value well, and the parameter descriptions fill in details about optionality and return behavior. However, the main description alone doesn't explain how output is delivered (file system vs content), relying on the schema for that. Given the parameter richness and no output schema, it's mostly complete but could be slightly more self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter already well-described (e.g., framework, outputDir, generateAll). The description adds high-level context about templates but doesn't enhance the semantic meaning of individual parameters beyond what the schema provides.

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: generating configuration files for AI coding assistants. It lists specific frameworks (Cursor, Windsurf, Claude Code, etc.) and explains the benefit (React Native best practices, API validation, project context), effectively distinguishing it from sibling tools like generate-component-scaffold.

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 setting up AI assistant configs in React Native projects, but it doesn't explicitly compare with alternatives or state when not to use it. It provides context but lacks direct selection 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 behavior disclosure. It mentions generation and returns production-ready code, but omits key behaviors such as the listScaffolds mode (returning a list instead of code), filtering by library/category, and the effect of customizations on template variables. It also doesn't state whether it has side effects or dependencies, leaving significant behavioral aspects unclear.

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 sentence that is front-loaded with the verb 'Generates'. It is concise, includes relevant examples, and the phrase 'production-ready, type-safe code following best practices' conveys quality without excess. Every word contributes to the core message, and the length is appropriate for the tool's complexity.

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?

This tool has 8 optional parameters, including a list mode (listScaffolds), filtering, and a nested customizations object, yet the description omits these features entirely. Without an output schema, the description should explain return values, but it only vaguely states 'Returns production-ready, type-safe code.' The description is insufficient for a user to know how to list scaffolds, use filtering, or handle customizations, making it far from 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?

Schema description coverage is 100%, so the baseline is 3. The description adds no extra parameter meaning beyond what the schema already provides. Each parameter has a clear description, including enums and defaults, so the description does not need to compensate. The minimal addition is the phrase 'like FlatList, navigation screens...' which hints at categories but doesn't clarify parameter usage beyond 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 function: it generates boilerplate code for specific React Native patterns (FlatList, navigation screens, forms, API calls). The verb 'Generates' plus the resource 'boilerplate code for common React Native patterns' distinguishes it from sibling documentation/search tools. The mention of 'production-ready, type-safe code' further clarifies the output quality.

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 search-docs or get-best-practices. It doesn't mention the listScaffolds mode as an alternative usage, nor does it advise when to use filtering parameters. The only implicit hint is that it's for code generation, but no explicit when/when-not or alternative references are 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?

With no annotations provided, the description carries the burden of disclosing behavioral traits. It only says 'Get' which implies a read operation, but it does not mention output format, coverage, risk factors, or any side effects. Minimal 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, focused sentence that immediately states the tool's purpose. It is front-loaded and uses no unnecessary words, making it efficient and easy to parse.

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 a single parameter and no output schema, the description is minimally viable but lacks richness. It does not clarify what 'best practices' entails, what makes it different from other doc/search tools, or what kind of result to expect. Given the sibling tools and simple schema, a bit more context would help.

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 one parameter (`library`) with an enum but no descriptions, and schema coverage is 0%. The description adds only the phrase 'for a library,' which is redundant with the parameter name. It does not explain the valid values or how to choose between them, so it fails to compensate for the lack of schema 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 uses a specific verb ('Get') and specifies the resource ('performance and architecture best practices for a library'). It clearly distinguishes from sibling tools like get-library-docs, which would cover general documentation, but it does not explicitly mention that distinction.

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?

There is no guidance on when to use this tool versus alternatives such as get-library-docs or search-docs. The description simply states what it does without mentioning context, prerequisites, or exclusions, leaving the agent without decision support.

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 mentions 'smart chunking and pagination for token efficiency,' which is a useful behavioral detail, but it does not clarify API conventions, error handling, or the nature of the returned content (e.g., a single page vs. all chunks). The transparency is moderate but incomplete.

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, concise sentence that communicates the core purpose and key behavioral features without unnecessary fluff. Every word contributes meaning, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a doc-retrieval tool with no output schema, the description provides a reasonable overview but leaves gaps. The pagination mechanism, return format, and behavior for missing topics are unspecified. Given the tool's moderate complexity and the lack of output schema, a more thorough description would improve completeness.

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 descriptions for 4 of 5 parameters (80% coverage), so the description does not need to compensate heavily. However, the description does not add any additional meaning about parameter interactions (e.g., how page and version affect results), and the 'library' parameter has no textual description beyond its enum. Overall, the schema handles the semantics adequately.

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

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

The description clearly states a specific verb ('Get') and a resource ('specific documentation'), with added detail about chunking and pagination. It differentiates from 'search-docs' or 'semantic-search-docs' by implying targeted retrieval, but does not fully distinguish from those siblings without further 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 gives no explicit guidance on when to use this tool versus alternatives like search-docs or semantic-search-docs. It only states what the tool does, leaving the agent to infer usage context. No exclusions or alternative comparisons are provided.

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 the main output (exact ID and available versions) but does not discuss error handling, edge cases (e.g., no match found), or whether the operation is read-only. The term 'resolves' implies a lookup, which is helpful, but lacks depth.

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, tightly worded sentence that front-loads the core purpose and output. Every word earns its place, with no unnecessary filler or repetition.

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 low complexity (one parameter, no output schema), the description adequately explains what the tool does and what it returns. However, it omits details about failure behavior or output format, which would be useful. Overall, it is sufficient for a simple lookup 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 already covers the 'query' parameter with a clear description and examples (100% coverage). The tool description adds the qualifier 'fuzzy', which is useful context, but does not significantly extend what the schema already provides. Baseline 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 uses the specific verb 'Resolves' and clearly states the resource: fuzzy library name to exact library ID and available versions. This distinguishes it from sibling tools like search-docs or get-library-docs, which focus on documentation retrieval rather than name resolution.

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 'fuzzy library name' provides clear context for when to use this tool—when the user has a partial or ambiguous library name. However, it does not explicitly mention alternatives or exclusions, so it falls short of a perfect 5.

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 must carry the full burden of behavioral disclosure. It only states 'Lists available documentation topics' and does not mention side effects, error behavior, output format, or prerequisites. The read-only nature is implied but not explicitly stated.

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 sentences with no fluff. It front-loads the core purpose and provides a clear alternative, 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?

The tool has no output schema, yet the description does not clarify what the return value looks like beyond 'topics.' It also does not mention when to use this tool over other siblings like get-library-docs or find-examples, leaving gaps in context for a tool with moderate 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?

The schema description coverage is 67% (cwd and version have descriptions, library lacks one). The description itself adds no parameter semantics, leaving the library parameter's purpose to be inferred from its enum. It does not explain how cwd/version interact with the tool.

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 with a specific verb+resource: 'Lists available documentation topics for a library.' It also distinguishes itself from semantic-search-docs by recommending that tool for AI-powered content search, aiding 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 explicitly recommends using semantic-search-docs for AI-powered content search, which clarifies when not to use this tool. However, it does not address other sibling tools like get-library-docs or resolve-library, so it is not fully comprehensive.

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 key behavioral aspects: use of AI embeddings, conceptual matching, and returning similarity scores. However, it does not mention whether the operation is read-only, any rate limits or network dependencies, or behavior when no results are found. For a search tool this is a moderate 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 two sentences long, front-loaded with the core action (semantic search) and key differentiator (embeddings). Every word earns its place, clearly conveying purpose and output without verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, no output schema, no annotations), the description covers the essential context: what it does, how it works, and what it returns. It does not explain output structure in detail, but since no output schema exists, the return description is somewhat brief. Overall, it is reasonably complete for a search 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 100% description coverage for all 6 parameters, so the schema already provides comprehensive meaning for 'query', 'topK', 'library', 'version', 'cwd', and 'searchMode'. The description adds no additional parameter-specific semantics beyond what the schema provides, so a 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 clearly states the tool performs semantic search across documentation using AI embeddings to find conceptually similar content. It distinguishes itself from the sibling search-docs by highlighting the embedding-based approach and the ability to match even when exact keywords don't match. The returns (relevant documentation chunks with similarity scores) are also explicitly mentioned.

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 exact keyword matching is insufficient ('even when exact keywords don't match'), providing clear context for when to choose this tool. However, it does not explicitly name alternatives like search-docs or state when NOT to use this tool, so the guidance remains 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. It discloses what the tool produces (step-by-step guidance, breaking changes, deprecated APIs, code examples, effort) and that it combines 'curated migration guides with documentation search' – giving insight into internal mechanism. Does not mention side effects or limitations, but as a read-only suggestion tool, transparency is strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose and key deliverables. No fluff, every word contributes value. The second sentence succinctly explains the hybrid source approach.

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?

Tool has 6 parameters and no output schema, but the description provides a solid overview of purpose and outputs. The schema fills in parameter details. It lacks explicit notes on return structure or edge cases, but for this complexity level, the description is sufficiently complete for an agent to infer 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 100% for all 6 parameters, so the schema already defines each parameter. The tool description adds context (e.g., 'code examples' and 'estimated effort') but does not explain parameter-specific behavior like the meaning of 'format' or 'fromVersion: auto'. Baseline 3 is appropriate since schema handles the heavy lifting.

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 the tool's function: 'Provides step-by-step migration guidance for upgrading between library versions'. It enumerates specific content (breaking changes, deprecated APIs, code examples, estimated effort) and distinguishes from siblings like compare-api-versions by focusing on migration guidance rather than comparison. The verb 'suggest-migration-path' aligns with the description.

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 migration scenarios ('upgrading between library versions'), but does not explicitly state when to use this tool versus alternatives like compare-api-versions or get-library-docs. No exclusions or alternative references provided. The context from sibling names suggests differentiation is possible but not stated.

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 of behavioral disclosure. It adds valuable context about the checking order (node_modules before docs index), suggesting a read-only operation, but does not disclose what the tool returns, whether it has side effects, or how it handles errors. This is partially transparent but incomplete.

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, well-structured sentence that front-loads the core purpose ('Fast validation') and efficiently conveys the search order. Every word contributes meaning, with no wasted text.

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 validation tool with 3 parameters and no output schema, the description covers the purpose and search strategy but omits the return format (e.g., boolean or diagnostics) and does not explain how 'cwd' affects the search. Given the absence of an output schema, these details would be valuable for complete 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?

Schema coverage is 67%, with descriptions for 'symbol' and 'cwd' but not 'library' (only an enum). The description indirectly explains the role of library and symbol by mentioning node_modules and docs index, but does not explicitly elaborate on parameter usage or constraints. It adds some context beyond the schema but does not fully compensate for the missing library description.

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 primary action: 'Fast validation if a symbol exists'. It specifies the resource (symbol) and scope (node_modules first then docs index), which distinguishes it from sibling tools like search-docs or resolve-library. The verb 'validation' 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 implies usage when a quick existence check is needed, contrasting with more extensive search tools like search-docs or get-library-docs. It does not explicitly name alternatives or state when not to use, but the 'fast validation' phrasing sets clear context. No exclusions are provided, but the use case is evident.

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