inspo

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

Annotations already cover the safe, read-only, idempotent nature of the tool, so the description's burden is lower. It adds useful behavioral context by stating that it returns per-site breakdowns plus shared traits, which goes beyond the simple 'compare' framing and clarifies the output style without overpromising.

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?

One dense sentence that front-loads the core action and scope, then immediately states what the agent will get back. No filler, no repetition of schema fields, and the house-style purpose is included without bloat.

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 one parameter, full schema coverage, and safety annotations, the description is nearly complete. Since there is no output schema, it appropriately summarizes the return shape ('per-site breakdowns plus what they share'), which is enough for an agent to invoke the tool and calibrate expectations, though a bit more structure would elevate it further.

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 `slugs` has 100% schema description coverage, including examples and range constraints, so the description does not need to add much. It adds context about what the slugs represent ('captured sites') and what comparison dimensions are used, but that is tool-level context rather than deeper parameter semantics.

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 ('Compare'), names the exact resource ('2-4 captured sites'), and lists the comparison dimensions (palette, typefaces, macrostructure, scales, etc.). It also distinguishes itself from sibling tools by framing the output as a house-style triangulation across references, which is unique among the listed siblings.

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 communicates when to use the tool: when you have 2-4 captured sites and want to triangulate a house style. It does not explicitly name alternatives or exclusions, but the context is unambiguous and leaves little inference for an agent deciding whether to call this tool.

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 destructiveHint false, so no safety concerns remain. The description adds valuable behavioral nuance beyond annotations: closeness is measured in OKLAB distance and means color-family similarity, not merely same hue. This meaningfully shapes agent expectations about match quality.

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; the core behavior and matching metric come first, followed by the exact use case. Every clause contributes 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?

The description, combined with rich parameter docs and safety annotations, is largely sufficient for selecting and invoking the tool. There is no output schema, and while the detail parameter hints at row contents, the description could more explicitly state the shape of the result set; overall, the gaps are minor for a read-only search 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 high (80%) and parameter descriptions already explain hex formats, tolerance defaults, detail levels, and maxTokens trimming. The description adds some interpretive context around hex matching (OKLAB distance, color family), but most parameter meaning is already carried by the schema, so the baseline of 3 is appropriate.

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 clearly defines the tool as returning real sites whose extracted palette is near a given hex colour, with an explicit color-matching nuance (OKLAB distance, same family not just hue). It does not explicitly contrast against siblings like find_similar or search_screens, but the color-specific language and brand-color use case make the tool's purpose unambiguous.

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 final sentence gives a clear trigger: 'Use when a brief names a brand colour.' This provides solid contextual guidance, though it does not state when not to use the tool or name alternative siblings, so it stops short of full exclusionary guidance.

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 convey read-only, idempotent, non-destructive behavior. The description adds useful behavioral context by highlighting that results are real sites and that each result may include a per-element crop when one exists. It also positions this as an example-finding tool, not a code-generation tool. 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: two sentences, front-loaded with the core purpose and followed by a useful routing note to a sibling. However, the long parenthetical enum list repeats the schema's type values, so it is not perfectly economical.

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 complex tool with 11 parameters and no output schema, the description provides only a high-level purpose and one sibling handoff. It does not clarify result shape, ranking behavior, how filters combine, or how this tool relates to the other close siblings like find_reference_components and search_screens. The schema compensates partially, but the description leaves meaningful gaps.

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 describes type, vibe, color, style, device, pageType, and maxTokens in some detail, covering 64% of parameters. The description does not add meaningful parameter semantics beyond listing the component types inline, which duplicates the type enum. Parameters like mode, limit, industry, and macrostructure are left to schema enums without additional context.

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 verb and resource: find real sites featuring a UI component, with a per-element crop where available. It also explicitly contrasts with get_reference_jsx. However, it does not differentiate itself from the similarly named sibling find_reference_components, leaving some ambiguity about which of those two to choose.

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 gives one clear usage rule: use get_reference_jsx when copy-pasteable code is needed instead. It also implies use for real-site examples with crops. It does not cover when to choose find_reference_components, find_by_color, or find_examples_for_macrostructure over this tool, so the guidance is partial rather than complete.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral details about token trimming ('Trims lower-ranked results and thumbnails; the top result and all URLs survive'), which informs the agent about response size and data retention. 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 only two sentences, front-loading the core purpose and then adding the input format clarification. It is concise and without fluff. However, it could have included a brief mention of the output format or example usage, but the current structure is efficient and focused.

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 tool has 5 parameters and no output schema. The description covers the essential purpose, when to call it, and input flexibility. It also discloses token trimming behavior. It does not describe the response format, but given the lack of an output schema and the tool's read-only nature, this is acceptable. The description is complete enough for an agent to invoke it 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 description coverage is 80% (4 of 5 parameters have descriptions). The description adds the clarification that the 'name' parameter accepts both slugs and display names, which supplements the schema's examples. However, it does not elaborate on other parameters beyond what the schema already provides, so it adds limited semantic value beyond the structured documentation.

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 clearly states the tool's function: finding real sites that exemplify one of the 19 named macrostructures. It specifies the resource (sites), the action (find), and the input format (slugs or display names). It also gives context on when to call it ('at the macrostructure-pick step'), which differentiates it from sibling tools like find_similar or find_by_color.

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 explicitly says to call it at the macrostructure-pick step, providing a clear trigger. It also clarifies the accepted input forms (slugs or display names), which is helpful for correct invocation. However, it does not explicitly mention alternatives or when not to use this tool, leaving some ambiguity relative to sibling tools like find_similar.

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 annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context by defining the return shape (an index of id, label, macrostructure, note) and clarifying that this tool does not return source code, which is a separate call.

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 two tight sentences with no filler. It front-loads the tool's purpose and output fields, then immediately gives the follow-up action, making every sentence earn its place.

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 simple read-only index tool with optional filters, the description plus schema cover the invocation and return shape well. The only minor gap is the lack of explicit statement about default behavior when no parameters are provided, though the schema does mention 'Omit to scan all types'.

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. The description reinforces the macro concept and category context but does not add meaningful parameter-level detail beyond what the input schema provides, so the baseline 3 is appropriate.

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 resource ('canonical reference components'), states that it returns an index with id, label, macrostructure, and note, and lists the archetype categories. It differentiates itself from get_reference_jsx by explicitly saying that tool provides the source, so an agent can tell the two apart.

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 gives a clear usage flow: pick a reference component from this index, then call get_reference_jsx(type, id) for the source. It does not explicitly enumerate exclusion criteria or contrast with other siblings like find_components, but the intended workflow is unambiguous.

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 annotations (read-only, idempotent, non-destructive), the description reveals the ranking mechanism, the fallback when embeddings are unavailable, and the one-result-per-site deduplication. It does not state the output shape, but no output schema exists and the safety profile is already covered by 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?

A single 25-word sentence packs the core behavior, criteria, fallback, and dedup rule with no filler or front-loading issues.

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 5-parameter read-only tool, the description covers the essential selection/ranking facts and the schema documents the more complex parameter semantics. It is missing any explicit 'when to use vs alternatives' guidance and an indication of result structure, but an agent can still invoke it correctly from the slug and limit params alone.

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 description's only parameter-related signal is 'One result per site,' which slightly clarifies the sameSite default, but it does not explain slug, limit, detail, or maxTokens beyond the schema. With schema coverage at 60% and the remaining params self-explanatory (slug/limit), a 3 is fair.

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 phrasing 'A screen's nearest design neighbours' names the exact resource (screens) and operation (find similar/neighbours), and the ranking criteria ('design-similarity embeddings... else by macrostructure / industry / style overlap') remove ambiguity about what 'similar' means. This distinguishes it from adjacent siblings like find_by_color or find_components without needing to inspect their 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?

The description implies the tool is for retrieving similar screens from a starting screen, but it does not explicitly state when to use it over compare, recommend, or search_screens, nor any exclusions. The only indirect guidance is 'One result per site,' which hints at deduplication behavior rather than routing.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by specifying that the response includes the editor's blurb and an ordered screen list, which goes beyond annotations. No contradictions 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?

A single, tightly worded sentence that immediately conveys the verb, resource, and key included content. 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 simple read-only fetch tool with a fully documented schema, the description plus schema covers the purpose, parameters, and basic return content. The description explicitly mentions the ordered screen list and editor's blurb, which is sufficient given no output schema. The minor 'issue' vs 'collection' wording does not impair understanding.

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%, with each parameter (slug, detail, maxTokens) fully described, including enum semantics and trimming behavior. The description adds no parameter-specific information 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?

States a specific verb ('Fetch') and a specific resource ('one issue by slug'), and specifies what is included ('editor's blurb and ordered screen list'). This clearly differentiates from sibling tools like list_collections (listing) and get_screen (fetching a screen).

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 usage when you need a single collection by slug, but does not explicitly state when to use this tool vs alternatives or when not to use it. No exclusions or alternatives are named, leaving the usage context implicit.

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 read-only, idempotent, open-world behavior. The description adds meaningful behavioral context by disclosing that thin captured tokens are supplemented by a live fetch of the source and that `live=false` skips the network round-trip. This goes beyond the annotation baseline without contradicting it.

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

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

The description is compact and front-loaded: the first clause states what the tool returns, followed by a concise list of contents, then the key behavioral option. Every sentence earns its place with 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, idempotent tool with a fully documented schema and rich annotations, the description gives enough context: what is returned, the live-fetch behavior, and how to skip it. No output schema exists, but 'full DESIGN.md' adequately conveys the return shape.

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 100%, so both `slug` and `live` are already well documented in the input schema, including the behavior of `live=false`. The description adds no new parameter-level meaning beyond what the schema provides, so the baseline score 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 clearly identifies the resource as 'The full DESIGN.md for one screen' and enumerates its contents (fonts, palette, CSS variables, tech, colour roles, type ramp), making it easy to distinguish from siblings like get_screen or get_collection. It does not explicitly contrast with a sibling, but the specific scope is unambiguous.

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 usage for retrieving a screen's design system details, but gives no explicit guidance on when to choose this tool over siblings such as get_screen or get_reference_jsx. It only explains the live-fetch behavior, which is about parameter handling, not tool selection.

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, idempotent, and non-destructive behavior. The description adds useful context beyond those hints: the tool requires zero input and explains the consequence of using an invalid filter value elsewhere. This aligns with the closed-world annotation and gives an agent actionable behavioral expectations.

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 efficient. It front-loads the core value, lists relevant filter categories, and adds usage guidance in a single extra sentence. Every sentence earns its place with no 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 zero-input lookup tool with rich annotations, the description provides enough information to call it correctly: what it returns, that no input is needed, and when to use it. It does not specify the exact output structure, but that is a minor gap given how simple and focused the tool is.

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?

There are no parameters, and schema coverage is trivially complete. The description reinforces this with 'Zero input.' No parameter documentation is needed, so the baseline of 4 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 clearly identifies the resource (accepted filter values) and the main point: this tool returns the full vocabulary of filters. It lacks an explicit verb like 'list' or 'retrieve,' and it does not explicitly distinguish itself from siblings, but the resource is unique enough that an agent can infer its purpose.

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 explicitly says to call the tool when unsure about a filter valueches and warns that an out-of-vocabulary value errors. There is no mention of when not to use it or alternatives, but no sibling performs the same function, so the guidance is clear and sufficient.

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 destructiveHint, so the safety profile is covered. The description adds meaningful behavioral detail: the result is a full canonical JSX source, includes a header stamp with macrostructure/theme/states, and is designed for copy-paste customization.

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 focused sentences with no redundant phrasing. The core value proposition is front-loaded, and the usage-oriented note ('Copy-pasteable; tweak tokens') earns its place without bloat.

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 simple two-parameter, read-only, non-destructive tool with full schema coverage)Skip? The description fully explains what the agent gets and how to use it; no output schema is needed because the return is described as JSX source. Nothing essential is missing.

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%, with id explained as 'Reference id within that type' and type as a categorized enum. The description adds no additional parameter-level detail, so the baseline of 3 applies: the schema already carries the semantic weight.

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 ('get') and resource ('full canonical JSX source for one reference component'), and adds a concrete detail about the 'header stamp naming its macrostructure / theme / states'. This clearly distinguishes it from sibling tools like find_reference_components or compare.

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 a clear use case: retrieve complete component source to copy and tweak for a target brand. However, it does not explicitly state when to prefer this tool over siblings like find_similar or find_examples_for_macrostructure, nor does it mention any 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 read-only, idempotent, and non-destructive hints. The description adds meaningful behavioral context by stating exactly what the 'full record' contains, which is more than the schema or annotations alone provide. No contradiction or missing side effects.

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?

One sentence, front-loaded with the action and identifier method, then a compact list of returned contents. No fluff; every word earns its place.

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?

Although there is no output schema, the description enumerates the main ingredients of the full record (viewport variants, palette, fonts, tech stack, designer credit). This gives an agent enough to understand roughly what it will get. It could be slightly more explicit about error cases or structure, but it is sufficient for a single-parameter getter with annotations covering safety.

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 schema has 100% coverage for the single 'slug' parameter, so the baseline is 3. The description only says 'by slug' and adds no extra meaning beyond the schema's own example. No compensation is needed because coverage is already complete.

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 verb ('Fetch') and resource ('full record for one screen by slug') and enumerates the content fields (viewport variant, palette, fonts, tech stack, designer credit). This is distinct from sibling tools like search_screens or get_collection, so an agent can differentiate it without opening the schema.

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 'by slug' clearly implies when to use it: when you know the exact slug for a single screen. It has a clear usage context, but it does not explicitly mention alternatives or when NOT to use it, stopping short of a 5.

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 convey read-only, idempotent, and non-destructive behavior. The description adds worthwhile context beyond that: the response shape (ordered flow with metadata), the directory behavior with no arguments, and that a screen slug can substitute for a site slug. 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?

Three short sentences with zero waste. The core resource and ordering concept are front-loaded, and the mode distinction is stated plainly. The illustrative phrase 'how a real product sequences its pages' is interpretive but compact and helpful.

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 tool with no required parameters and no output schema, this description is complete: it explains both invocation modes, what results look like, and the key ordering/metadata features. Nothing essential for calling the tool correctly is missing.

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%, giving baseline 3. The description adds value by clarifying that 'limit' only applies in directory mode and that siteSlug accepts both site and screen slugs, which effectively disambiguates parameter meanings beyond schema text.

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 resource ('a site's captured pages') and details its content: an ordered flow with titles, northstars, and thumbnails. It also distinguishes itself from sibling tools like get_collection or get_screen by defining the flow-oriented purpose and the directory mode.

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 gives clear mode guidance: omit arguments to get a directory of flow-capable sites, or pass a site or screen slug to get the page flow. It does not explicitly name alternatives for exclusion, but the mode-based conditions are concrete enough for an agent to apply.

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 read-only, idempotent, and non-destructive behavior, so the description needs only minimal additional disclosure. It adds the 'editor-curated' scoping and thematic-browsing intent, but does not describe return format or pagination. Given annotations cover the safety profile, 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.

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

The description is two sentences with no filler. The primary purpose is stated first, followed by a concrete usage example, making it front-loaded and efficient.

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 zero-parameter, read-only listing tool, the description is complete. It states the scope (editor-curated issues), the use case (thematic browsing), and examples. No output schema means the agent may not know the return format, but for a list tool this is a minor gap; annotations cover safety.

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?

There are zero parameters, and schema coverage is 100%, so the baseline is 4. The description adds semantic context (thematic browsing examples) that enrich the tool's purpose beyond the empty 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?

Clearly states the verb 'list' and the resource 'every editor-curated issue', and provides concrete examples ('Editorial Layouts', 'Dark Product Pages') that distinguish it from sibling tools like get_collection or find_components. This is specific and immediately understandable.

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 explicitly frames the use case as 'thematic browsing' with examples, and the context of sibling tools (get_collection, find_components) implies alternatives. While it doesn't state when-not-to-use, the open-world and idempotent annotations plus the clear purpose make the usage context unambiguous for an agent.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe, non-mutating call. The description adds valuable context with 'No LLM call' (clarifying it's deterministic and fast) and describes the response structure in some detail (the 'evidence' packet and detail-level options). However, it doesn't go deep into return format specifics beyond the brief list; given annotations cover the safety profile well, the added context is moderate but not exhaustive.

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 dense with information. It front-loads the key action ('Orchestrator - start here') and then lists the main outputs in a single breath. It avoids redundancy, uses clear terminology, and every sentence adds value – from the deliverable list to the skip condition to the 'No LLM call' note. It's well-structured for an agent to parse quickly.

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 tool's complexity (9 parameters, 7 enums, rich output list) and no output schema, the description covers the essential behavioral contract well: what it returns, how to skip the pick step, and the detail-level modes. It also mentions the 'evidence' packet and reference component sourcing. However, it doesn't explain how parameters interact (e.g., how vibe and color combine) or the exact semantics of 'paper band / display class / accent hue' – but that might be over-specification. It's complete enough for most use cases.

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 each of the 9 parameters is already described in the schema. The description adds context about the overall response and how detail affects the output ('concise' vs 'full'), but it doesn't add meaning to individual parameters beyond that. For instance, the 'vibe' and 'color' parameters are self-explanatory from their enums and descriptions. The baseline 3 is appropriate because the description adds some cross-parameter context but the schema does most of 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 starts with 'Orchestrator - start here for a brief' which clearly identifies this as the entry point and its primary purpose. It enumerates the specific deliverables (macrostructure pick, exemplars, reference components, palette suggestion, evidence packet), making it distinct from sibling tools like find_components or get_design_system. The verb 'recommend' combined with 'start here' leaves no ambiguity about its role.

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?

Explicitly says 'start here for a brief' and the 'One call returns...' enumerates what the agent gets. It also states 'Pass a macrostructure to skip the pick step' – a clear condition for when to simplify the call. While it doesn't explicitly name alternatives, the instruction 'source via get_reference_jsx' points to a sibling for a follow-up step, and the overall description makes it obvious this is the first call in a workflow compared to sibling tools like compare or find_similar.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile, so the bar is lower. The description adds the return format (palette, fonts, components, image URLs). Behavioral details like token trimming and the fold-by-fold autopsy live in the detail/maxTokens schema descriptions, not the main description. No contradiction with annotations, but the description adds only modest behavioral context beyond the safety flags.

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 efficient sentence that front-loads the verb and resource, then states the return payload. Zero filler, every clause earns its place. The description is appropriately brief given the schema carries the parameter documentation.

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 15 parameters and no output schema, the description carries more burden than it currently handles. It does state what is returned, and the schema descriptions compensate for filter semantics. However, it does not explain how multiple filters combine (AND vs OR semantics), nor does it route to the correct sibling. The schema is rich enough that this is adequate but not complete for a search tool of this complexity.

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 93%, so the baseline is 3 even though the description itself adds no parameter-specific meaning. The schema descriptions are individually rich (e.g., paperBand notes it is more reliable than mode, maxTokens explains trimming rules). The description adds the return-format context but nothing about parameter semantics, which is acceptable given the high schema coverage.

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 ('Search') and resource ('archive of real website screenshots'), and names the return content (palette, fonts, components, image URLs). The purpose is clear, but it does not differentiate from similar siblings like find_by_color, find_components, and find_similar, which are also search-like operations. The return format hint partially disambiguates but leaves room for 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 gives no guidance on when to use this tool versus the many siblings (find_by_color, find_components, find_similar, recommend, get_screen). No exclusions or alternative routing is provided. The rich schema descriptions hint at filter semantics but the description itself offers zero usage direction, which is a notable gap for a tool with 14 search-like siblings.

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