Server Quality Checklist

Tool Scores

• hig_getA
  3.6/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety. The description adds the output format (Markdown) and clarifies accepted input types, which is useful but does not go beyond basics like error behavior, acceptable given the 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?

  Two sentences with the core action front-loaded and the input specification clearly stated in the second sentence. No redundant or vague language.

  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?

  For a single-parameter read-only tool with no output schema, the description covers what it does, what it returns, and how to specify the topic. It omits error handling details, but those are minor for this simple scope.

  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 schema already describes the topic parameter with examples and coverage is 100%, so the baseline is 3. The description adds mention of developer.apple.com URLs and repeats slug examples, but adds little new semantic meaning beyond the schema.

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

  Purpose4/5

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

  The description clearly states 'Fetch one Human Interface Guidelines page as Markdown', specifying the verb and resource. It does not explicitly differentiate from sibling tools like hig_search or hig_toc, but the purpose is unambiguous.

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

  Usage Guidelines3/5

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

  The description instructs to pass a slug, title, path, or developer.apple.com URL, which guides input usage. However, it does not mention when to use this tool over alternatives, leaving the choice implied (e.g., use when you have a specific page identifier).

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

• hig_listA
  3.6/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is clear. The description adds that it lists topics and can be filtered by section, but it doesn't disclose details like whether the list is ordered, paginated, or if it returns full objects or just summaries. With annotations covering key behaviors, a 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.

  Conciseness5/5

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

  The description is a single, concise sentence that front-loads the main verb and resource, then adds the optional parameter. Every word earns its place; no filler or repetition.

  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?

  For a list tool with one optional parameter and no output schema, the description is sufficient. It covers the purpose and the filter, and combined with annotations (read-only, open-world), an agent has enough to call it. The only minor gap is not describing the return format, but that's minor given the simplicity.

  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 schema already documents the 'section' parameter with examples. The description adds the context that the section filters the list and lists possible values, which is slightly beyond the schema's 'e.g.' but still minimal. Baseline 3 is correct since the schema does the heavy lifting.

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

  Purpose4/5

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

  The description states a clear verb ('List') and resource ('HIG topics'), and it mentions it can be optionally limited by section, which helps distinguish from sibling tools like hig_get. However, it doesn't explicitly differentiate from hig_toc, which might also list topics, so it's clear but not fully differentiating.

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

  Usage Guidelines3/5

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

  The description implies when to use this tool (to list topics, optionally filtered by section), but it doesn't provide explicit guidance on when to use alternatives like hig_search or hig_get. It mentions the optional section filter, which gives some context for usage, but lacks exclusions or alternatives.

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

• hig_searchA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds that it accepts natural-language queries and can filter by topic/component/pattern, but it does not disclose details like result ranking, pagination, or how the search handles broad queries. This is acceptable given the annotations, but not rich 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.

  Conciseness5/5

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

  The description is a single, focused sentence that front-loads the action and resource, then provides concrete examples. Every word earns its place; no filler or redundancy.

  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?

  For a search tool with full schema coverage and read-only/idempotent annotations, the description is nearly complete. It could mention that results are returned as a list or that the query is free-form, but the examples already convey that. The lack of an output schema is not a gap because the description's job is not to explain return values.

  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 schema already documents all three parameters (query, limit, platform). The description adds the notion of natural-language queries and examples, but it does not add significant meaning beyond the schema. Baseline 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 states a specific verb ('Search') and resource ('Apple's Human Interface Guidelines') and clarifies the scope with examples of topics ('touch targets', 'tab bars', 'Liquid Glass'). It clearly distinguishes this from sibling tools like hig_get or hig_toc by indicating it is a search operation over the guidelines.

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

  Usage Guidelines4/5

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

  The description implies when to use this tool: when you have a topic, component, pattern, or design question. It does not explicitly state when not to use it or name alternatives like hig_get or hig_toc, but the examples and phrasing provide clear context for a search-oriented use case.

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

• hig_tocA
  4.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds that it returns the full table of contents with major sections, which is useful but not deeply detailed. No contradictions.

  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?

  A single, clear sentence with no waste. It front-loads the core action (return) and the resource (table of contents) followed by a parenthetical list of sections. Ideal length for a zero-parameter tool.

  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?

  For a read-only, zero-parameter tool with openWorldHint and idempotentHint, the description is complete enough. An agent knows exactly what to expect from the call. No output schema, but the description implies a structured list of sections, which is sufficient.

  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 0 parameters)Skip means there's nothing to explain beyond the schema. With 100% schema coverage and no params, a baseline 4 is appropriate, and the description doesn't need to add parameter details.

  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 returns the full HIG table of contents and lists the main sections. This is a specific verb and resource, distinguishing it from siblings like hig_search, hig_get, and hig_list.

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

  Usage Guidelines4/5

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

  The description implies this is the tool to get an overview of the entire HIG structure, contrasted with siblings that likely search or retrieve specific items. It doesn't explicitly state when not to use it, but the context is clear. No exclusions are mentioned.

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