Design Lounge

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

The description is highly effective at detailing the underlying methodology, such as checking for content that reads 'without JavaScript,' which is a critical behavioral trait beyond simple annotation. It provides a comprehensive view of the technical depth of the audit process.

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 extremely verbose. It reads like a comprehensive feature checklist rather than a summary, listing every single element (headings, canonical, JSON-LD, etc.). While comprehensive, the excessive length sacrifices conciseness.

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 complexity of modern search and AI indexing, this description is maximally complete. It covers technical structure, content requirements, and indexing signals, providing a complete picture without relying on any external documentation.

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?

Although the schema provides 100% coverage, the description adds semantic context by detailing how those parameters are processed; for instance, it specifies that the tool analyzes `robots.txt` and `sitemap`—processes that occur when the `url` parameter is input.

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 is extremely specific, defining its purpose across three distinct technical categories (SEO, AEO, and GEO). It goes far beyond a simple summary by listing precise elements like 'robots.txt for search and AI crawlers' and 'JSON-LD,' making it immediately clear what the tool accomplishes.

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?

While it does not explicitly name when *not* to use the tool compared to its siblings, the extensive detail about the specific types of audits (e.g., checking alt tags, share cards, and server-rendered text) clearly segments its usage for content/structure auditing, implicitly narrowing its scope against other 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?

The description adds crucial context by specifying *what* the audit looks for, listing concrete examples like 'stock copy, em dashes, buzzwords,' and 'drift from the locked kit.' This adds operational knowledge that goes beyond the abstract 'readOnlyHint' annotation.

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 definition is dense but highly efficient; every phrase contributes to defining the scope of the tool. The most critical information (what it looks for and how it operates) is front-loaded.

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?

The description is very complete in its lack of an output schema, providing all necessary context about the nature of the audit and the inputs required. It leaves no ambiguity about the tool's specific domain (design forensics).

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?

Despite a moderate schema coverage of 60%, the description provides semantic meaning by detailing which specific design elements are checked for 'drift' (e.g., 'faces, colours, radius, shadow'). This guides the agent on the underlying design constraints of the audit.

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 title and description clearly define the tool's purpose: finding 'AI giveaways' by identifying specific design 'tells' associated with generative AI. It distinguishes itself from standard audit or search tools by focusing on pattern recognition for synthetic content.

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 a clear operational guideline by stating that the tool is 'Static by default' and that 'render=true' enables deeper, 'measured checks.' This helps the agent understand the difference in complexity or thoroughness between basic and detailed audits.

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 establish this is a read-only, closed-world operation, so the description doesn't need to re-establish safety. It adds one genuinely useful behavior: mood-based ranking applies only to themes and pairings. It does not disclose what is returned (names only? ids?), whether ordering is defaulted, or how limit interacts with results.

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?

Two tight sentences, front-loaded with the core listing capability, and the enumeration is directly useful prose even if it overlaps the enum. No filler or hedging.

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 browse tool with no output schema and 0% schema description coverage, the description leaves meaningful gaps: the return shape, the meaning of `mode` (light/dark filtering?), and limit behavior/defaults. It is adequate to start a call but not fully self-sufficient.

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 coverage is 0%, so the description has to carry parameter meaning. It does add real semantics for mood (concrete example values, and the crucial constraint that it ranks only themes/pairings) and partially explains `what`. But `mode` and `limit` are never mentioned in the description and are undocumented in the schema, leaving half the parameters opaque.

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?

A concrete verb ("List") plus the exact resources it enumerates, which distinguishes it from the singular get_* siblings (get_theme, get_family, get_pairing). However, the prose list omits the enum values "motion" and "scales" that the schema actually accepts, so the stated scope is slightly narrower than the tool's real scope.

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 second sentence implies how to use the mood parameter (ranking themes/pairings), giving some usage context. But it never states when to choose browse_library over get_theme/get_family or search_pieces, and gives no exclusions or prerequisites.

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=true and openWorldHint=false, so the safety profile is covered. The description adds that it returns 'problems and the Unlike line', which tells the agent the output is a verdict rather than a bare boolean. It does not explain what happens with an empty history, how strict the checks are, or where history comes from (that detail lives only in the schema).

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?

It is compact and front-loads the check itself, with no filler sentences. But the single semicolon-chained sentence packs four distinct rules and three undefined domain terms together, making it hard to parse rather than genuinely concise.

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 an 11-parameter tool with no output schema, the description leaves important things unexplained: what a 'recipe' is (the only required input), what 'the sheet' and 'Unlike line' mean, and what the returned 'problems' look like. An agent can infer the spirit of the check but not how to correctly supply the required input or interpret the result.

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 coverage is low at 27%, but the description does pick up much of the slack by naming how direction, hero, effect, work, footer, shape, and frame are each compared, giving real semantic grounding to seven of the eleven parameters. The required 'recipe' parameter and 'product' are never explained, and the 'history'/'reuse' behavior is left entirely to the schema.

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 this is a uniqueness check and enumerates the specific comparison rules (direction/hero/effect vs recipe, two of hero/work/footer vs related group, shape vs last two, frame vs last three), which is concrete. However, it is framed in unexplained domain jargon ('Recent picks', 'the related group', 'the sheet', 'Unlike line') and never differentiates itself from siblings like pick_direction or the audit_* tools.

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?

There is no statement of when to call this versus pick_direction, get_recipe, or audit_slop, and no preconditions (e.g., must a pick exist first?). The schema's 'reuse' field hints at an alternate mode, but the description never tells the agent when that mode applies.

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 establish this is a safe, closed-world read (readOnlyHint=true, openWorldHint=false). Beyond that, the description usefully discloses the shape of the payload (rule categories plus their locking rationale) and a precedence rule relative to a brief, but says nothing about behavior on a missing/invalid id or what form the rules come back in.

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?

Two short sentences with zero filler, and the payload contents lead. The phrase 'the sentences that lock them' is evocative but underspecified rather than verbose, so the terseness costs clarity without saving much length.

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?

With no output schema and no parameter documentation, the description is the only source of return-shape information, and it only gestures at the payload ('rules ... and the sentences that lock them') without structure. For a lookup tool in a dense family of get_* siblings, it leaves the agent guessing about the id format and the response layout.

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 0% and the single 'id' parameter is an undocumented bare string. The description never clarifies whether the id is a family name, slug, or generated identifier, so it fails to compensate for the coverage gap despite the parameter being required.

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 enumerates what a family contains (radius, button style, density, shadow, plus the rationale sentences), which implies a retrieval of that record, but it never states the verb or that it returns a family by id. It also gives no signal distinguishing it from siblings like get_theme, get_recipe, or get_piece that presumably return related design artifacts.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no routing to any of the 17 sibling tools. The precedence statement ('the family wins over a brief') is about downstream conflict resolution, not about when an agent should call this tool rather than get_theme or get_recipe.

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 and closed-world, and the description adds real behavioral detail beyond them: default icon dimensions, the listing fallback when names are omitted, and the 'missing:' sentinel for unknown names. The recovery instruction (follow Icon and nav in components.md, never an emoji) is unusually useful guardrail context.

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?

Three short sentences, front-loaded with the core purpose. However the phrasing is telegraphic ('Missing names come back as missing:') and the trailing components.md instruction is compressed to the point of ambiguity about what 'nav' means.

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?

With no output schema, the description does explain the return shape (SVG), the list mode, and the missing-name sentinel. It still leaves gaps on output ordering, whether results are grouped, and how group and names interact, which matters for a two-parameter lookup tool.

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 0%, so the description must carry parameter meaning. It explains 'names' (lookup by name) and that 'group' drives the listing mode, but it never states whether group also filters when names are supplied, nor what a group string should look like.

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?

Names the resource (Lounge Icons), the return format (SVG), and the lookup key (by name), plus concrete rendering defaults (24px, stroke 1.75). It is clearly distinguishable from siblings like get_piece or browse_library, though it never explicitly contrasts with them.

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 no-names case is covered ('lists them by group'), so the agent knows two modes of invocation. There is no guidance on when to use this versus browse_library or get_piece, and no statement of what happens in the group+names combination case, so the agent must infer.

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=true and openWorldHint=true, so the safety profile is structured. The description contributes by disclosing what the response actually contains (CSS variables, import line, numbers face, cautions) — the 'numbers face' and 'caution' details are real added context an agent would not get from the schema. It stops short of describing failure modes for a bad id or how the image specimen is returned.

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?

A single compact sentence with zero filler, and the most valuable content (the CSS contract) is front-loaded. The grammar is clipped to the point of being slightly obscure — 'its numbers face' takes a beat to parse — which costs it the top mark.

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?

There is no output schema, so the description must carry the return shape, and it does name the key fields an agent will get back. It omits error behavior for an unresolvable id and the relationship between the image flag and the returned content, leaving gaps for a two-param read tool with an open-world hint.

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 100%, so the id (pairing id, name, or Lounge link) and image (attach specimen, default true) parameters are already fully documented. The description adds no parameter-level meaning, nor does it note that the specimen attachment can be toggled. Baseline 3 applies when the schema does the heavy lifting.

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 enumerates the contents of the returned payload (Google Fonts import, --font-display, --font-text, mono, numbers face, cautions), which tells an agent what this resource is. However, it is a noun fragment with no verb and never states the operation (fetch/lookup by id), so the purpose is inferred rather than stated. The 'pairing' resource is distinctive enough against siblings like get_family or get_theme, but no explicit differentiation is offered.

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 only usage hint is the trailing phrase 'before you write', which weakly implies this is a lookup to run ahead of writing CSS. There is no explicit when-to-use, no exclusion, and no mention of the sibling tools (check_pick, audit_slop, get_family) an agent might otherwise choose.

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 cover the read-only safety profile, and the description adds real behavioral detail beyond them: the default truncation at "Optional below this line", what full=true unlocks, and what demo=true unlocks. It does not describe output size (e.g., how large the HTML source can be), but the defaults and expansion behavior are well disclosed.

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-loaded with the payload contents, then the default/flag behavior. Sentences are dense and telegraphic but each carries information; the trailing colour/font instruction is slightly out of place for a retrieval tool description but still actionable.

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?

No output schema exists, so the description must characterize the return — it does so with a concrete content checklist plus the truncation default. Complete enough to call correctly; only the absence of id-source guidance (how to get a valid piece id) leaves a small 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?

Schema coverage is 50% (id and full lack descriptions), so the description must compensate — and it does, explaining full=true and demo=true in terms of what content is added. The image parameter's default is only carried by the schema, and id semantics are assumed rather than stated.

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 ("spec for one piece") and enumerates what the brief contains (structure, counts, sizes, motion timing, states, hit targets, acceptance checklist). It is clearly distinct from search_pieces/get_family, though it never names those siblings explicitly.

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?

Usage is implied: fetch when you already have a piece id and need the spec. There is no explicit when-to-use vs when-not, and no mention of using search_pieces to obtain the id or get_family to see the surrounding 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?

Annotations only declare readOnlyHint and openWorldHint=false, so the description carries the rest. It usefully discloses that each direction reports whether recent history blocks it, which tells the agent the output is history-dependent — real behavioral value. It still doesn't explain what 'blocked' means operationally or how the caller's history versus the local history file interact.

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?

Two short sentences with no filler, and the output shape is front-loaded. But the compression goes too far — parenthetical jargon ('a recipe (start)', 'a complete look') substitutes for plain explanation rather than saving space.

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, three-parameter tool with no output schema, the description does sketch the return structure and flags the history-dependent behavior, which is the main thing an agent needs. The undocumented 'product' parameter is the notable remaining 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?

Schema coverage is 67%, and the description adds nothing about any parameter. The 'product' parameter is undocumented in both schema and description, and the interaction between the caller-supplied 'history' array and the local ~/.design-lounge/history.jsonl is left unexplained in the description.

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 it retrieves a recipe along with its 'directions' and enumerates what a direction contains (theme, pairing, family, hero, effect, work, footer), so the resource is identifiable. However, the framing ('a recipe (start)', 'a complete look', 'directions') is domain jargon and never clarifies how this differs from siblings like get_theme, get_pairing, or browse_library.

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?

No statement of when to call get_recipe versus browse_library, start_design, or pick_direction. The only routing hint ('browse_library what=recipes lists the ids') lives in the schema, not the description, so the description itself offers no usage guidance or exclusions.

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=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context by explaining the returned payload (CSS roles plus the paired mode) and explicitly limiting the scope to colour. It does not describe response structure or the effect of the image parameter, but it adds real value beyond 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?

Two compact sentences with no filler: the first front-loads what is returned, the second immediately sets scope boundaries. Every phrase contributes useful information.

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?

With no output schema, the description does a good job naming the returned CSS categories and the paired-mode theme. It is nearly complete for an agent deciding whether to call it, though it could say more about the response shape or the image board attachment.

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 100%, so both parameters are already documented: id accepts a theme id/name/Lounge link, and image controls whether a role board is attached. The description adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies.

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 exactly what get_theme returns: a theme's full CSS across named role categories plus the matching theme for the other mode. The final sentence sharpens the scope by excluding fonts, radius, and shadow, which makes it distinguishable from siblings like get_pairing and get_family.

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?

It clearly signals the boundary: use this for colour CSS, while fonts come from the pairing and radius/shadow from the family. That effectively routes the agent toward get_pairing and get_family for the excluded attributes, though it does not explicitly say 'use X instead' or state when not to call get_theme.

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 cover read-only and closed-world behavior, so the safety profile is clear. The description adds the deterministic tie-break formula, but does not explain the role of the count parameter, output shape, or error behavior.

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 a single efficient sentence with the core computation front-loaded. Its compactness is appropriate, though the external rule reference makes it more cryptic than necessary.

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 helper with no output schema and 0% schema description coverage, the description leaves important gaps: it does not explain the count parameter or the return value. It is also dependent on an external 'rule 5' context that an agent may not have.

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 0%, so the description must carry parameter meaning. It explains that letters in the name are summed by alphabet position, but the count parameter is never mentioned, leaving one of two parameters opaque.

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?

It states a specific computation: alphabet-position sum modulo the number of fitting directions, used as a tie-break. That identifies the operation and its role in the pick-direction workflow, though it relies on an external rule reference and does not explicitly distinguish the helper from siblings like pick_direction or check_pick.

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 phrase 'the tie-break from rule 5 of Pick a direction' implies when the tool is relevant, but it never states when to call this instead of pick_direction/check_pick, nor when not to use it. The usage context is implied rather than spelled out.

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 readOnly and closed-world annotations, the description discloses meaningful behavior: calm words narrow to quiet/editorial/sharp families, history blocks recent directions/heroes/effects, the group check blocks two-of-three matches, and the name number breaks ties. It still omits what the tool returns or how errors are surfaced.

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, but it is not front-loaded: it opens with rule numbers and a dense semicolon chain rather than a plain statement of the operation. The content is relevant, but the structure makes the agent parse jargon before understanding the action.

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 rule-based selection tool with five parameters and no output schema, the description should explain the return value and clarify the referenced rules. Instead it assumes external knowledge of rules 1-5 and never says what the tool produces after applying them.

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 80%, so the baseline is 3. The description adds useful meaning for `calm`, `history`, `product`, and `fitting`, but it never explains the required `recipe` parameter, leaving a critical gap.

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 names a specific operation: applying rules 3-5 and recent-picks/group checks to narrow and choose directions, with the agent judging which directions fit the subject. This is more specific than a tautology, but it does not clearly distinguish the tool from related siblings such as check_pick or get_family.

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?

There is implied workflow guidance: the agent is told to judge fitting directions under rules 1, 2, and 4 and pass them as `fitting`. However, it never states when to use this tool versus alternatives, nor does it name exclusions or 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavior: the valid file set, section-only retrieval, and that outline=true lists headings. It does not mention error behavior for invalid files or headings, so it remains adequate rather than rich.

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 purpose is front-loaded in the first sentence, followed by the necessary file enumeration and section/outline behavior. The file list is dense but earns its place because the schema does not enumerate values. Minor restructuring could improve scanability.

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 documentation reader with no output schema, the description covers the key inputs and the outline mode. Annotations already handle the safety profile. It leaves the exact return shape for section reads implicit, but otherwise gives enough to call the tool correctly.

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 coverage is 0%, so the description must carry parameter meaning, and it does: it enumerates valid file values, gives heading examples for section, and explains outline=true. It still omits details such as whether outline defaults to false or how heading matching works, which keeps it from a 5.

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 uses a specific verb and resource: read a method file or one section of it. It enumerates the available method files, making the scope concrete. It does not explicitly distinguish itself from guidance-oriented siblings like get_recipe or start_design, so it stops short of a 5.

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 explains how to request a section or an outline, but it does not say when to use this tool instead of alternatives such as browse_library or get_recipe. There is no when-not guidance, so the agent must infer the selection criteria.

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 and openWorldHint, so the safety profile is covered. The description adds real value: rendering is conditional on Chromium availability, viewports are 1280×800 and 390×844, screenshots are saved, and output is scores plus fails-with-evidence-and-fix. It does not say what happens when Chromium is absent or how the kit is resolved, but with annotations present this is acceptable.

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?

A single dense sentence, front-loaded with the tool's purpose and then the check categories, ending with what it returns. No wasted sentences, though the jargon ('kit drift', 'the Look fails', 'AEO, GEO') will not parse for every 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?

No output schema exists, and the description compensates by stating the return shape (scores, fails first, evidence and fix). For a 7-param, nested-schema tool it is largely complete, with the main gap being how the three input sources (url/html/file) and kit resolution interact.

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 coverage is 86%, so the schema already documents most parameters, setting the baseline at 3. The description's mention of viewports and screenshots lightly illuminates render/images/out_dir but adds no precedence rules for url vs. html or kit sourcing beyond what the nested schema already states.

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?

Opens with a specific verb-plus-resource ('The all-in-one check for a built page') and enumerates the check categories: look/kit drift, SEO, AEO, GEO, and a rendered accessibility pass. It is clearly broader than the audit_search/audit_slop siblings, though it never names them to make the boundary explicit.

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?

Usage is only implied by 'all-in-one check for a built page' and the conditional note about Chromium availability. There is no explicit when-to-use vs. audit_slop or audit_search, and no guidance on choosing url vs. html vs. file input.

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=true and openWorldHint=false, so the safety profile is covered. The description adds useful context about the return payload (ids, summaries, demo links), but says nothing about result caps, ranking, or empty-result behavior beyond what annotations imply.

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?

Three tight sentences with no filler; the corpus scope and searchable fields are front-loaded, and the follow-up tool is stated last where it belongs.

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?

No output schema exists, but the description compensates by stating the return shape (ids, summaries, demo links) and the natural next call. For a read-only search tool with six mostly optional params, this is close to complete; only the undocumented filter params keep it from a 5.

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?

At 50% schema description coverage, the description only loosely compensates: "by words (job, component, style, tag) and filters" hints at the query and filter params, but limit, style, and platform remain undocumented in both places. The semantics for half the parameters are left to inference.

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?

Names a specific verb (Search) and resource (piece briefs), states corpus size (543), enumerates the searchable fields (job, component, style, tag), and describes what comes back (ids, summaries, demo links). It also names the sibling get_piece as the follow-up, so an agent can separate discovery from retrieval without opening schemas.

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?

"Then get_piece for the brief" gives an explicit two-step workflow and routes the agent to the correct retrieval tool. It does not, however, say when to prefer this over browse_library (browsing by category) or search_wada, and gives no exclusion conditions.

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=true and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral note – results are lines to be taken whole, with a header explaining role mapping – but says nothing about how many lines return or how limit behaves.

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?

Three short sentences, front-loaded with purpose, then constraints, then output handling. The final sentence is slightly cryptic but short; every sentence carries information rather than padding.

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?

There is no output schema, and the description only hints at return shape (whole lines plus a header for role mapping). It never explains whether multiple matches return, how limit interacts with the 348-set, or which searches are exclusive. Adequate but with clear gaps for a 3-param lookup tool.

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 coverage is 33%: `near` is documented as a hex, but `query` and `limit` are bare. The description compensates partly by illustrating query values ('russet, slate, "dark warm"'), which adds real meaning, while limit is left to inference from the schema's 1-30 bounds.

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 resource (Sanzo Wada's 348 combinations) and specific retrieval modes: by colour or material word, or nearest hex. It's clearly a palette lookup, distinguishable from siblings like get_theme or search_pieces, though it doesn't name an explicit 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?

It gives explicit when-to-use conditions: 'Only for Free colour, a brand board no theme fits, or colours they asked for.' That functions as both a use condition and an implicit exclusion, steering agents away from themed boards without naming the sibling to use instead.

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=true and openWorldHint=false, and the description is consistent with them while adding real context: it reads the local project folder and recent picks, then returns a brief to fill and a tool-by-tool step list. That tells the agent both the side-effect profile and the shape of the response, which annotations alone would not. It does not say what happens when no recipe ranks well or how large the returned step list can be.

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?

A single front-loaded sentence that opens with the critical routing instruction before describing mechanics — good ordering with no filler. The parenthetical "(flow, mode, named style, calm words)" spends words on jargon that does not resolve into actionable 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?

For a 3-parameter, no-output-schema tool, the description supplies the missing return-value information (a brief and a step list naming tools) and the workflow position (call first, then follow the steps). What remains underspecified is the opaque "method" vocabulary and the behavior when the request is ambiguous or no recipe fits.

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 100%, so all three parameters (request, product, history) are already documented in the schema. The description gestures at them ("reads their request," "the recent picks") but adds no format, size, or precedence guidance beyond what the schema provides, so the baseline of 3 applies.

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 names a specific role — an entry-point planner that parses a design request, ranks recipes, reads project context, and returns a brief plus an ordered step list naming the tools to use. That is far more than a restatement of "start a design." It loses a point because "reads their request the way the method does" and "calm words" reference an internal method the agent has no definition for.

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?

"Call first for any new website, app, screen, or UI" is an explicit routing rule that places this ahead of siblings like pick_direction, get_recipe, or browse_library. It does not state a when-not condition (e.g., resuming existing work or iterating on a page), so it stops short of full when/when-not coverage.

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 establish readOnlyHint and openWorldHint, so the description adds real value on top: it declares the extraction is fact-only, that missing fields are reported back, and that ratings/reviews/prices are never fabricated. That anti-hallucination contract is exactly the kind of behavior an agent needs and cannot get from 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?

Front-loaded with the deliverable, then the field list, then the guardrails — the strongest behavioral claim ('never invents') lands last but is memorable. It's dense with no filler, though the semicolon-chained clauses read a bit compressed.

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?

No output schema exists, so the description carries the return-value burden — and it does, saying the output is JSON-LD plus a list of fields that could not be found. Combined with the fact-only guarantee, an agent knows what to expect; only the exact envelope shape is unspecified.

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 coverage is 75%, so most parameters are documented in the schema itself, and the description adds nothing about url vs html precedence, optional name, or how `type` overrides detection. It mentions the supported entity types, which loosely maps to the `type` parameter, but no format or defaulting detail beyond what the schema says.

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 concrete deliverable: JSON-LD structured data generated for a page, enumerating the entity types and fields it covers. It's specific enough that an agent knows exactly what comes back, though it never names a sibling to distinguish itself from (e.g. review_page or audit_search).

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?

Usage is only implied — the description makes clear you supply a page and get markup, but there is no explicit 'use this when…' vs an alternative, and no stated prerequisites beyond 'public URL' from the schema. An agent can infer the context but is not guided between this and any related auditing tools.

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