Server Quality Checklist

Tool Scores

• get_code_examplesA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses what the tool returns (all code examples, context, categorization, complexity analysis, metadata) and implies a read-only operation. It doesn't mention auth or error handling, but for a read-only extraction tool, this is reasonably transparent.

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

  Conciseness3/5

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

  The description is verbose and somewhat repetitive. It uses multiple sections (WORKFLOW INTEGRATION, USAGE PATTERN, PERFECT FOR) that overlap. While organized with headers, it could be more concise without losing key information.

  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?

  Given no output schema, the description compensates by listing expected return contents. It covers the tool's role within a broader search workflow. However, it omits potential error cases or authorization requirements, which would make it more complete.

  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?

  Schema coverage is 100% and the description enriches the meaning of docId (from search_docs results) and ties it to a usage pattern. This goes beyond the schema's bare description by providing context and source.

  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 extracts code examples from a specific document ('Extract code examples from a specific document you already found'). It differentiates from siblings by emphasizing a contextual, document-specific approach vs. broad search, and references search_docs integration.

  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?

  Explicitly provides a workflow: 'Use after search_docs', a usage pattern with step-by-step instructions, and highlights it's perfect for AI agents drilling down after initial search. This gives clear when-to-use guidance and distinguishes from search_docs or get_doc.

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

• get_statsA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the transparency burden. It discloses the exact output fields and database scale, setting expectations for what the tool returns. It clearly implies a read-only operation without stating it explicitly, but no side effects or hidden behaviors are expected for a stats tool.

  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 well-structured with clear sections (DATABASE SCALE, WHAT YOU GET, WHEN TO USE) and bullet points, making it scannable. It is slightly verbose with details like exact document count and model specs, but every section serves a purpose and the key info is 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 zero-parameter tool with no output schema, the description fully covers what the tool does, what it returns, and when to use it. It even notes the scope of the database, giving the agent sufficient context to decide if this tool is needed.

  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 baseline is 4. The description adds context about what the output means (e.g., sampleTitles are for 'understanding content types'), which is sufficient given no inputs are needed.

  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 is a 'DATABASE OVERVIEW' and a 'health check', providing a specific purpose that distinguishes it from siblings like search_docs and get_doc. It lists what users 'get' (totalDocuments, model, dimensions, sampleTitles), making its function concrete.

  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?

  An explicit 'WHEN TO USE' section lists four distinct scenarios (first interaction, debugging, context setting, health check), giving clear guidance on when to invoke this tool. While it doesn't explicitly mention alternatives, it frames usage as 'before searching', implying a complementary role.

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

• get_docA
  4.7/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses behavior via content richness (full text, code blocks, metadata), batch limits (up to 10 IDs), and return fields. However, there is a minor inconsistency: 'unlimited size' vs. 'up to 18K+ characters', which could confuse agents about actual limits. Still, it provides substantial behavioral context.

  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 well-structured with clear sections and emoji headers, making it scannable. It is longer than strictly necessary for one parameter, but each section (content richness, usage patterns, what you get, strategy) earns its place by providing actionable guidance. Slight verbosity prevents a perfect score.

  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?

  Given the tool has one parameter, no output schema, and no annotations, the description covers all necessary bases: return fields (title, url, content, contentLength, codeBlocks), usage patterns, batch limits, and integration with search_docs. It is fully self-contained for an agent to decide when and how to invoke it.

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

  Parameters5/5

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

  The description adds significant meaning beyond the schema by explaining the union type in plain language: 'Pass string ID for one document' vs. 'Pass array of up to 10 IDs for comparison'. It also clarifies that the ID comes from search_docs results and gives usage context, which the raw schema description lacks.

  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 opens with a specific verb and resource: 'Get complete document content' with 'DEEP DIVE' and 'unlimited size'. It clearly distinguishes itself from siblings like search_docs by positioning itself as the follow-up tool for full documents, and from get_code_examples and get_stats by focusing on complete 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?

  Explicit usage patterns are provided, including single document, batch analysis, and a clear follow-up strategy after search_docs. It says 'Use after search_docs to get complete details of promising results' and 'Get full documents when search_docs snippets look promising but lack detail', which directly names the alternative tool and the contextual trigger.

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

• search_docsA
  4.9/5.0
  Behavior5/5

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

  With no annotations provided, the description fully carries behavioral disclosure. It reveals that related results are enabled by default (3-6 docs), that semantic matching uses existing embeddings with no extra API calls, that relevance thresholds and related-doc similarity adaptation occur, and that includes framework-aware connections. This goes far beyond a basic search description.

  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 long but highly organized with clear sections, examples, and emoji signposts. It is front-loaded with purpose and strategy. Some redundancy exists between the 'ENHANCED BY DEFAULT' section and the includeRelated parameter description, so it is not perfectly concise, but the density is justified by the tool's feature richness.

  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?

  Given no output schema, the description covers return semantics effectively: relevance score bands, related-document counts, and a concrete example of the related mode result structure. It also addresses the full workflow with siblings and parameter trade-offs, making it complete for an AI agent to select and invoke the tool correctly.

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

  Parameters5/5

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

  Schema coverage is 100%, so the baseline is 3, but the tool description adds substantial value beyond the schema: it explains how to interpret relevance scores (60%+, 50-59%, etc.), gives query examples matching the format, and describes practical limit/minSimilarity settings. The includeRelated behavior and showCodePreview integration with get_code_examples are also elaborated beyond raw parameter docs.

  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 opens with 'SEMANTIC SEARCH through 16,253 Apple documentation pages with intelligent relevance scoring,' which clearly names the verb, resource, and unique value. It distinguishes from siblings by explicitly positioning search_docs for exploration versus get_doc for detailed analysis and get_code_examples for code extraction.

  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?

  Provides a detailed SEARCH STRATEGY with broad-to-narrow iteration, specific limit recommendations, query examples with good and bad patterns, and explicit alternatives (get_doc, get_code_examples). The workflow line 'Use search_docs for exploration → get_doc for detailed analysis → repeat' makes when-to-use unmistakable.

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