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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the risk profile is covered. The description adds useful behavioral context beyond annotations: the result is provenance-aware ('Apple's vs. community/Figma-derived') and includes a checklist. 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.

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

The description is front-loaded with a one-sentence purpose, then a dense but non-redundant list of covered guardrails, and clear Args/Returns sections. Every sentence earns its place and there is no 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?

For a read-only, single-purpose lookup tool, the description covers inputs, selection semantics, and return contents. An example input/output would be a small enhancement, but the output schema and annotations already provide enough structure.

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?

With 0% schema description coverage at top level, the description compensates by explaining both params.context ('where the material is applied') and params.platform ('selects blur budget') with valid values. It adds selection semantics that are not obvious from the schema alone.

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 states a specific verb ('Return') and resource ('Liquid Glass guardrails'), then names the exact constraint categories it covers. It is clearly distinct from sibling tools like hig_get_tokens, hig_swiftui, and hig_fetch.

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 use when checking Liquid Glass design budgets and mentions 'agents routinely get wrong', but it never explicitly says when to choose this tool over alternatives or when not to use it. Sibling differentiation is left to inference.

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?

Annotations already declare readOnlyHint, idempotentHint, and nondestructive behavior; the description adds meaningful behavioral context beyond that: the returned text is for grounding only, the backend is overridable via HIG_SOSUMI_BASE, and the return value includes source and canonical URL details. 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.

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

The description is compact and well-structured: a clear purpose sentence, a short context sentence, a licensing restriction, an environment override, then Args and Returns sections. Every sentence earns its place, and the structure is scannable for an agent.

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 single-read-only-parameter tool with annotations covering safety and a schema covering the input, the description supplies everything else needed: return shape, source behavior, and licensing constraints. There is no significant invocation-relevant gap.

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 documents path with examples such as 'materials' and '/design/human-interface-guidelines/color'. The description's Args line restates the same meaning ('HIG slug, /design/... path, or full developer.apple.com URL') with little additional semantic value, so the baseline schema coverage is doing the work.

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 opens with a specific verb and resource: 'Fetch current HIG prose as clean Markdown via sosumi.ai.' It also distinguishes the prose-fetching role from token retrieval with 'so this one server covers both tokens and prose', making sibling differentiation clear.

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 clearly implies this tool is for HIG prose, not tokens, and gives explicit handling guidance: 'summarize and cite the canonical Apple URL, do not reproduce it wholesale.' It does not explicitly name sibling alternatives as exclusions, but the 'tokens and prose' contrast gives practical selection context.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses useful behavioral details: tokens carry provenance via 'src' tags, 'verify':true flags mark values needing OS confirmation, and semantic colors are dynamic and should be referenced by name rather than hardcoded as hex. This adds meaningful context for how the returned data should be interpreted and used, without contradicting annotations.

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 compact and well-structured: a clear one-line purpose, a short behavioral/provenance paragraph, and a concise Args/Returns block. Every sentence contributes substantive information, and the most important statement is front-loaded. There is no filler or redundancy.

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 read-only, idempotent getter with a single enum parameter and an output schema, the description is nearly complete. It covers the return type, provenance behavior, dynamic color caution, and category options. It could be slightly more explicit about what 'all' returns, but the presence of an output schema and annotation hints makes this a minor gap.

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 single parameter is already well-defined by the schema's enum and description, and the tool description repeats the allowed values without adding deeper meaning about what each category encompasses. It does not explain nuances like what 'typography' or 'materials' includes, but the param is self-explanatory and the schema provides enough information for correct invocation.

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 opens with a specific action and resource: "Return curated Apple HIG design tokens for a category." This clearly states what the tool does and the category parameter makes the scope explicit. It does not explicitly contrast itself with sibling tools, but the resource (design tokens) is distinct enough from hig_check_liquid_glass, hig_swiftui, and hig_fetch to avoid confusion.

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 choose this tool over alternatives, nor does it mention exclusions or prerequisites. It only documents the category argument and return value. Usage context is implied by the tool name and description, but there is no explicit routing or comparison to sibling tools.

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?

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: unstable Liquid-Glass-era modifiers are flagged verify:true because names shift between betas. This discloses uncertainty semantics not present in structured fields.

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?

Front-loads the core action, then uses clean Args/Returns structure. The Liquid-Glass caveat earns its place as it changes how the agent treats output. Slightly verbose but no filler sentences.

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?

An output schema exists, so the Returns line is surplus but harmless, and annotations cover the safety profile. The only real gap is the full set of 14 component names, which would remove trial-and-error for the single parameter.

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 reported at 0%, so the description must carry the parameter meaning, and it largely does: names the parameter, gives example values (button, tab_bar, sheet), states the count (14), and explains that omitting it lists all. It stops short of enumerating all 14 valid values, leaving some guesswork.

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?

States a specific verb+resource: map a HIG component to its SwiftUI API and token references. Clear and specific, but differentiation from the overlapping sibling hig_get_tokens (also token-oriented) is only implicit — the description names hig_fetch as a verification path, not as the distinct alternative.

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?

Gives concrete when-to-use guidance: verify:true entries should be confirmed via hig_fetch or Xcode before shipping, and omitting component lists all. Names an alternative tool and the condition selecting it, though it does not cover exclusions against hig_get_tokens/hig_check_liquid_glass.

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