Server Quality Checklist

Tool Scores

• search_docsA
  4.3/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds context about the return format (best matching page sections with fields) and that results are attached as structured content, providing a bit more transparency beyond the annotations without contradicting them.

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

  Conciseness4/5

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

  The description is relatively long but packed with essential usage guidance, including when to use and when not to use the tool. It front-loads the main purpose and then provides exclusions and alternatives. It is not wasteful; every sentence adds value, though it could be slightly more streamlined.

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

  Completeness4/5

  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, scope, and exclusions thoroughly. Since an output schema exists (as noted in context signals), the description does not need to detail return values beyond mentioning the types of fields. It provides enough context for an agent to decide when and how to invoke the tool.

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

  Parameters3/5

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

  The input schema provides 100% coverage of all four parameters with descriptions, including enums for section and version, and a description for query noting that plain keywords work best. The tool description itself does not add additional parameter semantics beyond what the schema already states, 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.

  Purpose5/5

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

  The description clearly states it searches official Capacitor documentation by keyword and returns matching page sections. It distinguishes itself from siblings by explicitly naming get_doc_page, list_plugins, and list_blog_posts as alternatives, making the tool's unique purpose unambiguous.

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

  Usage Guidelines5/5

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

  It explicitly instructs to use this tool first for any Capacitor-related question and lists specific topics (CLI, config, native projects, plugin APIs, upgrading). It also provides clear 'do not use' guidance, directing users to get_doc_page for whole pages and to other MCP servers for Capawesome and Ionic Framework content.

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

• get_doc_pageA
  4.4/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint, openWorldHint, and destructiveHint. The description adds behavioral detail on output (page title, URL, version, complete markdown including code samples) and notes that anchors are ignored, which goes beyond the annotation. No contradictions exist.

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

  Conciseness4/5

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

  The description is moderately long but each sentence serves a purpose: defining the action, providing usage guidance, describing output, and stating restrictions. It avoids redundancy, though it could be slightly tightened without losing clarity.

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

  Completeness5/5

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

  The description gives complete context: when to use (after search_docs), what it returns (full markdown with code samples), and what not to use it for (finding pages, external domains) with explicit pointers to alternative tools for other domains. No critical information is missing.

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

  Parameters3/5

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

  Schema description coverage is 100% for both parameters, with examples for url and a clear enum with default and matching guidance for version. The tool description itself adds no further parameter-level meaning beyond what is already in the schema, so a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool reads a full documentation page, with a specific verb ('read') and resource ('single page of the official Capacitor documentation'). It explicitly distinguishes itself from sibling tools like 'search_docs' (which finds pages) and the list_* tools (which list content).

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

  Usage Guidelines5/5

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

  The description explicitly instructs using this tool after 'search_docs' and provides clear exclusions: 'Do not use this to find a page' and 'Do not use it for pages outside capacitorjs.com', with alternative tools for other domains. This leaves no ambiguity about when to choose this tool over siblings.

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

• list_blog_postsA
  4.7/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the feed only contains the newest posts, the blog covers both Capacitor and Ionic Framework, and each returned post includes specific fields. This goes beyond bare annotation coverage without contradicting it.

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

  Conciseness5/5

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

  The description is concise yet information-dense. Each sentence serves a purpose: defining scope, giving usage guidance, describing output fields, and providing a clear exclusion with an alternative. Key facts are front-loaded.

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

  Completeness5/5

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

  For a simple zero-parameter read-only tool, the description is complete: it specifies source, ordering, recency limit, return fields, applicable use cases, and the correct sibling tool for documentation questions. No important context is missing.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema carries no parameter documentation burden. The baseline for 0-parameter tools is 4, and the description appropriately focuses on output and usage rather than parameter details that do not exist.

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

  Purpose5/5

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

  The description clearly states the tool's function: listing the 10 most recent posts from the Capacitor tag of the Ionic blog, newest first. It names a specific resource and scope, and the presence of sibling tools like search_docs and get_doc_page makes the boundary between them easy to infer.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool ('when the question is about what is new — recent releases, announcements or deprecations') and when not to use it ('Do not use this to answer a documentation question'). It also names the alternative, search_docs, making the routing decision unambiguous.

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

• list_pluginsA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and openWorldHint annotations, the description discloses meaningful behavioral details: the exact output fields, the `core` and `experimental` flags, and the specific ranking order (official, then Capawesome, then community). It also describes how sources map to plugin ecosystems. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is compact yet complete: it front-loads the core purpose, then use case, output shape, ranking behavior, and exclusions. Every sentence adds distinct information; there is no filler or redundancy.

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

  Completeness5/5

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

  With no output schema, the description fully specifies return fields and flags. It also covers ranking, parameter context, and routing to alternatives. The tool is simple enough that nothing essential is missing for correct invocation and interpretation.

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

  Parameters3/5

  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. Each parameter is already thoroughly documented with defaults, enums, and filter behavior. The description adds some contextual color (e.g., 'official' means Capacitor team, 'community' means awesome-capacitorjs entries) but does not need to compensate for schema gaps.

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

  Purpose5/5

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

  The description states both a specific verb and resource: 'List Capacitor plugins', and distinguishes the two categories of plugins (official and community). It also clarifies the tool's purpose—finding a plugin before writing custom native code—and contrasts itself with get_doc_page for reading APIs, making sibling differentiation explicit.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance ('Use this to find a plugin for a native capability before writing custom native code') and explicit when-not-to-use guidance with alternatives ('Do not use this to read a plugin's API: call get_doc_page ... use the Capawesome MCP server'). No ambiguity remains.

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