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

The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the main behavioral traits (safety, non-destructive, open-world) are covered. The description adds the return format ('Returns the best matching page sections with title, url, snippet, section and version, plus the parentTitle and parentUrl') which provides some transparency about output structure, but does not detail internal search behavior, ranking, or error handling. Given the annotations cover safety semantics, a score of 3 is appropriate.

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, but it is somewhat long due to the detailed list of covered topics and the three 'do not use' clauses. It front-loads the core purpose and usage guidance, and the clarifications are useful for disambiguating from siblings. It earns a 4 rather than 5 because the enumeration of topics and exclusions, while valuable, could be seen as slightly verbose, though 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?

Given the rich schema (4 parameters with full descriptions), clear annotations (readOnly, openWorld, non-destructive), and a descriptive output schema, the tool description fully equips an agent to decide when to use it, how to set parameters (including version matching guidance), and what to expect in the response. The description also differentiates from all sibling tools and alternative MCP servers, making the context 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 schema already covers 100% of parameters with descriptions, including examples for query ('modal dismiss' or 'dark mode css variables'), the meaning of section (e.g., 'components' for component reference), and the version instruction (match @ionic/core version). The description reinforces the query semantics ('Plain keywords work best; no search operators are supported') but does not add substantial new meaning beyond the schema. With full schema coverage, 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's purpose: to search the official Ionic Framework documentation by keyword. It explicitly enumerates the topics covered (UI component properties, events, CSS custom properties, theming, layout, Angular/React/Vue integrations, navigation, routing, Ionic CLI, upgrading) and distinguishes itself from sibling tools by naming get_doc_page, Capacitor MCP server, and Capawesome MCP server as alternatives for different use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage guidance: use this tool first for any question about Ionic Framework itself, and provides clear 'do not use' conditions (for reading whole pages, for Capacitor core/plugins/native configuration, for Capawesome plugins/cloud services) with precise alternative tools (get_doc_page, Capacitor MCP, Capawesome MCP). This leaves no ambiguity about when to select this tool over its siblings.

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