Better Design

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

Annotations already establish readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds real behavioral value beyond that: the transformation rules (routes become screens, nested routes become flows, components/API routes/hooks join the matching step) and the fact that output is JSON destined for .better-design/feature-map.json.

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 dense sentences, front-loaded with what the tool produces before the mapping rules and the input instruction. No filler; every clause carries 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 and a fairly involved transformation, the description does explain what the JSON represents and where it goes, and annotations cover the safety profile. It stops short of describing the returned structure or size limits, which would fully close the loop.

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, including the `git ls-files` sourcing and the product name. The description reinforces the exhaustiveness requirement ('pass every path') but adds no syntax or format detail the schema lacks. Baseline 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 (drafts/builds a map) and resource (product features and flows) and identifies its input source (repository file list) and output destination (.better-design/feature-map.json). This cleanly separates it from the sibling read-feature-map (reads) and update-feature-map (edits).

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

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

Gives clear operational context: pass every path from `git ls-files` as `files`. The draft-vs-read-vs-update distinction against siblings is implied by the verb rather than stated, and there are no explicit when-not conditions, so it falls 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?

Beyond the readOnly/idempotent/closed-world annotations, it discloses the return shape ('each finding with a severity and a suggested fix'), the side effect of surface=slide (withholds a pass pending screenshot review), and an explicit capability limit ('a pass is not visual approval'). That is substantially more than the annotations carry.

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

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

Front-loads the three tests before the input guidance and return description, with almost no filler. The closing sentence about 'Better Design runs the checks itself and calls no other API' is slightly opaque and arguably does not 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?

With seven parameters, no output schema, and a nuanced mode switch (screen vs slide), the description covers inputs, the one enum's behavioral effect, the return content, and the tool's limits. Nothing needed to call it 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: knownTerms is framed as 'words the audience already knows' so they aren't flagged, and surface='slide' is tied to the density test. It also clarifies the copy-vs-markup input choice that the schema only implies via the code 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?

States a specific verb and resource ('Checks interface copy for clarity') and enumerates the three tests it applies, so an agent knows exactly what the tool evaluates. No sibling tool covers copy comprehension, and the description makes that scope 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?

Explains what to pass ('the headline, body and action labels, or the markup') and when a variant applies (surface: 'slide' adds a density test). It also sets a clear exclusion ('reads text only, not screenshots or visual hierarchy'), though it never routes the agent to a sibling for the visual-review case it declines.

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 (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), the description discloses asynchronous background generation taking 1–3 minutes, a per-call credit cost, the no-op fallback behavior, and that anyone holding the registry/preview URL can view generated source and previews. These are non-obvious operational and privacy traits the schema and annotations cannot convey.

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?

Purpose and immediate output are front-loaded in the first sentence, followed by async timing, the follow-up tool, per-parameter semantics, cost, and visibility. Every sentence carries distinct information with no filler or repetition.

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, yet the description covers return values (project id + URL), async behavior, the status-check follow-up, all four parameters' interactions, cost, and the degenerate no-op path. An agent has everything required to invoke and follow up 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 already 100%, so the baseline is 3; the description adds genuine meaning on top by defining the mutual-exclusion rule (brandCss overrides/ignores baseDesignSystemId and why) and the semantics of the no-parameter case. It stops short of exhaustively restating each field, which the schema already covers.

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 gives a specific verb and resource ('Starts generating a custom design system from a description of the product and its look') and states the immediate return ('project id and project URL'). It also implicitly separates itself from find-design-system (which returns matches) and get-design-system-status (which reports progress), so an agent can route correctly 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?

It explicitly names the alternative tool (get-design-system-status) for the follow-up step and spells out the negative case: 'With none of the three, it generates nothing and returns the top catalog matches to show the user.' Each of the three conditional parameters is tied to a concrete user-selection scenario, which is exactly the when-to-use guidance needed.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral context: the two-phase, state-dependent call protocol and the privacy-relevant fact that 'the server never receives the recording itself'. Those are the details an agent needs to operate the tool correctly and are not derivable from annotations or 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?

Three sentences, front-loaded with the core action, then the call protocol, then the data-handling note. The middle sentence is a dense comma list of return values, but every element is informative and nothing is redundant 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?

With no output schema, the description carries the return-value burden and does so for both call modes, listing crop chrome, beat start times, camera target, and Remotion code. For a tool with a deeply nested `measurements` object, slightly more on what the probe script measures or how to round-trip its output would round this out, but coverage is strong.

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% and the description explains the pivotal `measurements` parameter beyond the schema's one-line note — it clarifies that omitting it yields the measurement script and supplying it yields the cut, which is the real semantics of that field. It adds nothing for `fps` or `maxBeats`, but those are low-complexity scalar settings with schema defaults.

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 ('cuts a screen recording into beats') plus the product context (a Remotion film) and the concrete outputs (crop chrome, beat start seconds, camera direction, Remotion code). This is clearly distinguishable from siblings like render-video-frames or plan-video, which do not analyze a recording's 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 effectively documents the required two-step workflow: the first call (no measurements) returns a probe script, the second call (with measurements) returns the cut. That sequencing is critical usage guidance an agent could not infer. It stops short of explicitly routing against alternatives or stating exclusions, so it is not 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds meaningful behavior beyond that: it parses a specific file, returns two pieces of information, and defines the empty case ('reports that none is recorded'), which is exactly the fallback an agent needs.

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 leads with the action and resource before the return behavior. No filler, though the sentence is long and could be split for scannability.

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 carry the return contract, and it does: library used, icons installed, and the none-recorded fallback. Since there are no required parameters and the optional one is fully documented in the schema, little else 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 coverage is 100% and the schema already instructs the agent to read the file from disk and omit the field if unreadable. The description adds no syntax or format detail beyond the schema, so the baseline of 3 for fully-documented schemas 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 and resource: reads the `.library.json` file and returns the used icon library plus installed icons, or reports none. This is distinguishable from install-icons and find-icon-library. It stops short of explicitly naming how it differs from the sibling find-icon-library, which keeps it at 4.

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 'an earlier icon install left in a project' implies this is a pre-install/pre-check step, giving implied usage. However, it never states when to prefer this over find-icon-library or install-icons, nor any exclusion conditions. Usage is left to inference.

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

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

Annotations already cover the safe read-only, idempotent profile, so the bar is lower. The description adds real behavioral context beyond them: the return payload, accepted color formats (hex, rgb, hsl, named, oklch), supported blocks (:root, .dark, @theme), and the important constraint that the server cannot read files.

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?

Four front-loaded sentences with no filler: purpose and return value first, then accepted inputs, then the merge behavior and the file-access constraint. Slightly dense but every sentence carries 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 correctly describes the return shape, and it discloses the key operational constraint (no file access). Missing only explicit routing against sibling tools, which keeps it short of 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?

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning — it clarifies what kinds of sources can be merged (including computed styles from a live page) and which color notations/blocks are accepted. The schema even defers to the description for how to gather each source kind.

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 (reads/extracts) and resource (design tokens from CSS) and enumerates the exact outputs — semantic palette, radius, fonts, shadow scale, and an oklch token sheet. The line 'the server cannot read files, so the caller passes the text' implicitly separates it from the URL-based sibling extract-from-url.

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 the input mechanism (caller passes text; sources merges inputs) which implies when the tool applies, but it never states when to prefer this over extract-from-url, find-design-system, or create-design-system. Usage is inferable rather than explicit.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds genuinely new operational context: it renders in a headless browser, reads stylesheets, calls no other API, and takes 10–45 seconds per call. The latency disclosure in particular is valuable for call planning. It stops short of describing failure modes for pages it cannot render.

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 sentences, front-loaded with the core action and each carrying distinct information (what it reads, that it is browser-like and self-contained, and how long it takes). No filler, though the sampling enumeration is dense.

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 correctly names the return value (an oklch token sheet) and notes truncation via maxTokens is handled in the schema. Annotations carry the safety profile and latency is stated, so an agent has nearly everything needed; only sibling disambiguation and public-page-only restrictions are unstated.

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 (url, name, maxTokens) are already documented with constraints and defaults. The description only reinforces that the target must be a 'public' page; it adds no syntax, format, or defaulting detail beyond the schema, so the baseline 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 gives a precise verb+resource ('fetches a public web page... returns the brand as an oklch token sheet') and enumerates exactly what it samples (colors, fonts, radii of body, headings, links, buttons, inputs, cards). It does not, however, differentiate itself from the very similar sibling 'extract-design-system' (or 'find-design-system'), so an agent cannot tell the two apart from the text alone.

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 when-to-use guidance and no mention of alternatives, despite several close siblings ('extract-design-system', 'find-design-system', 'create-design-system', 'preview-design-system'). The agent is left to infer that this tool is for live-site extraction while the others handle stored/created systems.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the capture happens in Better Design's own browser at three fixed widths, and the output is a deployment-tied receipt reporting specific fault categories. It stops short of mentioning auth requirements or failure behavior, so not a 5.

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 dense sentences with no filler; the capture-and-compare action is front-loaded and the return content follows. Slightly long and jargon-heavy ('Better Design's own browser'), but every sentence carries 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?

For a complex tool with 7 params (6 required) and nested objects, and no output schema, the description carries the return-value burden well by explaining what the receipt reports. It is not fully complete: it omits required-input meaning, prerequisites, and how the comparison inputs relate to one another.

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 71%, so the baseline is around 3. The description maps conceptually to several inputs (submitted source, data, components, the public HTTPS URL), but it does not explain screen, knownTerms, or the required shape/constraints of fixture and componentSources beyond what the 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?

The description names specific verbs (captures, compares, returns) and a concrete resource (deployed dashboard) with notable scope detail (390/1440/1728 px widths). It clearly conveys what the tool does, but it never distinguishes itself from the similarly named sibling review-dashboard-structure, so an agent cannot easily tell the two apart from text alone.

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, when-not-to-use, or alternative-selection guidance. The description implies it is a final verification step ('finalize'), but it never states prerequisites, ordering, or how it differs from review-dashboard-structure.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld=false, so safety is covered. The description adds genuinely new behavioral context by disclosing the return shape: ranked matches, each with a preview link, which no structured field provides.

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 sentences, zero filler, and the capability statement is front-loaded before the usage trigger. Nothing here could be cut without losing 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?

For a one-parameter read-only search tool with no output schema, the definition covers what it searches, what it returns, and when to reach for it. Combined with the annotations, an agent has everything needed to call 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 coverage is 100% and the single query parameter is already documented with examples. The description's "by industry, personality or a description of the interface" loosely restates the accepted query dimensions but adds no format or syntax detail beyond 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?

States a specific verb and resource (searches the design-system catalog) plus what it returns (ranked matches with a preview link). It is clear what the tool does, but it never explicitly distinguishes itself from nearby siblings like find-icon-library, get-inspiration, or extract-design-system.

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?

"Use it when the user wants a design system or a visual direction for an app, site, page, dashboard or presentation" gives a concrete triggering condition. There are no stated when-not conditions and no named alternatives, so it stops 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 declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint=false, so safety is covered. The description adds the return behavior ('closest matches with a note on each library's style'), which is useful, but says nothing about ranking, result count, or empty-match 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?

A single front-loaded sentence that names the action, the dimensions, an illustrative example, and the return shape without any wasted words.

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 one-parameter read tool with no output schema, the description covers input framing and a rough sense of the return. It could say more about match ranking or result count, but nothing essential to invoking it 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 coverage is 100%, so baseline is 3, but the description adds a concrete example value ('minimal clean professional') that clarifies the free-text nature and expected granularity of the query beyond the schema's generic 'Style description or personality traits to match.'

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 ('Searches') and resource ('icon libraries') plus the matching dimensions (style, mood, use case). Clear on its own, but it does not distinguish itself from near siblings such as find-icons or detect-icon-library, which an agent must disambiguate by other means.

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 when the tool is useful (matching libraries by style/mood/use case), but gives no explicit when-to-use, prerequisites, or alternatives. With detect-icon-library and find-icons present, the absence of routing guidance is a real gap.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive). The description adds behavioral context beyond them: it returns icon names that exist in the target library, and both the query phrasing and `variant` affect ranking/ordering of 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?

Three tight sentences, front-loaded with the core action and result, then ranking guidance and the libraryId provenance. 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?

With no output schema, the description appropriately states what is returned (icon names) and how ordering works. It does not mention result-count limits or pagination, which is a minor gap for a 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 coverage is 100% so the baseline is 3, but the description adds real semantic value: query should be a single noun for best ranking, and variant promotes matching names to the front rather than filtering. This exceeds what the schema fields convey.

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+resource: 'searches one icon library for icons by concept and returns icon names.' It distinguishes itself from the sibling find-icon-library by scoping to a single library and noting it consumes a libraryId from that other tool.

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 concrete usage advice ('A single noun, such as "inbox", ranks best') and explains how `variant` changes ordering, plus where to get libraryId. It stops short of explicitly stating when not to use it or naming the follow-up install-icons step.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real value by disclosing what the payload contains and, importantly, that it reflects user-tuned overrides rather than defaults – a behavioral distinction no annotation conveys.

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, verb front-loaded, with a compact colon list rather than prose padding. Every clause carries information; only mild criticism is that the field enumeration could be trimmed without losing 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?

With no output schema, the description must carry return-value information, and it does name the key fields returned. It stops short of describing response shape, empty/unpopulated cases, or behavior when projectId is unknown, but for a one-parameter read tool with full annotation coverage this is close to 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 description coverage is 100% for the single projectId parameter, which already documents that it comes from create-design-system. The description adds nothing about the parameter, so the baseline 3 for fully-documented schemas 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 and resource ('Returns the design config saved on a generated project') and enumerates the content: color tokens, radius, fonts, icon library, layout density. The 'saved on a generated project' scoping does substantial work separating it from siblings like extract-design-system or get-design-system-kit, though it never names an alternative outright.

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 phrase 'values the user tuned on the project page' hints this is the read-back counterpart to set-design-config, but there is no explicit when-to-use, no prerequisites, and no named alternative for the case where the caller wants the original (untuned) design system.

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, so the safety profile is covered. The description adds genuine value beyond that by disclosing the concrete artifact each target yields (shadcn install command, Liquid theme files, W3C tokens document, slide files plus a render script that writes PNGs) — notably the side-effecting render script, which the annotations do not 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?

Front-loaded with the core purpose, then a dense enumeration where each target clause earns its place by mapping an enum value to an artifact. It is long but nearly waste-free; the only flaw is that two clauses describe targets the schema does not accept.

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?

Output schema, rich annotations and 100% schema coverage mean return values and safety need not be re-explained, and the description covers targets and the component-narrowing case. But it omits projectId/designSystemId semantics entirely and, more seriously, promises mobile targets the schema forbids, so it is not fully coherent for a 5-parameter 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 100%, so the baseline would be 3, but the description actively contradicts the schema: it advertises 'react-native' and 'swiftui' targets that are absent from the target enum, and says 'component' narrows 'the React install' while the schema's component parameter is scoped to inspecting source code. This makes the description misleading about valid parameter values.

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 and resource ('Returns the build kit for a catalog design system or a generated project') and immediately distinguishes itself from siblings like preview-design-system and extract-design-system by enumerating exactly what each target produces. An agent can pick this tool without opening any 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?

Gives per-target selection conditions ('react' for any host with filesystem + terminal, 'html' only for inline chat canvases), which is real when-to-use guidance rather than restating the name. However it offers no explicit when-NOT-to-use or alternative-tool routing (e.g. vs preview-design-system), and the enum mismatch below undercuts the guidance for mobile targets.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds valuable behavioral context beyond that: it is a polling-style tool whose returned content differs by state (stage while running, preview URL and install command when done). It does not mention rate limits or caching for repeated polls.

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 purpose followed by state-dependent returns. 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?

With an output schema present, the description need not enumerate return fields, and it succinctly notes the two states the output can take. It omits mention of failure/error states or how long generation typically takes, which would help an agent decide polling cadence.

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% and the single projectId param is fully documented in the schema, including its origin (returned by create-design-system). The description adds nothing further about the parameter, so the baseline 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+resource (reports progress of a design system) and ties it directly to the sibling that creates it (create-design-system). It clearly distinguishes polling/status checking from creation and from other design-system siblings like find-design-system or preview-design-system.

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 names create-design-system as the origin of the resource, which tells the agent when this tool is applicable. It implies the polling pattern (while generation runs / when finish) but does not state when NOT to use it or what alternative to poll with.

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 openWorldHint=false, so the safety profile is covered. The description adds that the guide's content spans choosing the object, parts, camera and depth, lines, card and motion, kit and review, which is content framing rather than behavioral disclosure. It does not mention rate limits, token costs beyond the schema, or response format.

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?

Purpose is front-loaded in the first clause with the invocation hint last, and there is no filler. The mid-sentence enumeration of guide sections is a long run-on list that could be trimmed, keeping it just short of a 5.

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-required-parameter retrieval tool with full schema coverage and annotations covering the safety profile, the description supplies the domain scope, the section list that stands in for return content, and the topic/query/index invocation modes. It does not address the maxTokens parameter or output size, which is a minor gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning by stating the fallback behavior: passing nothing returns the index of topics. That mode/selection logic is not derivable from the schema itself, so it earns above baseline.

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 and resource ('Returns Better Design's guide for ... isometric drawing of a small machine') and enumerates the guide's sections, which clearly separates it from its many get-*-guide siblings such as get-motion-guide or get-jig-guide. It does not explicitly name a sibling to contrast with, so it falls just 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?

It gives invocation guidance by naming the three modes ('Pass `topic`, `query`, or nothing for the index of topics'), which tells the agent how to call it. It says nothing about when to prefer this guide over e.g. review-illustration or get-inspiration, so there is no when/when-not 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/idempotentHint/destructiveHint=false, so the safety profile is covered. Beyond that, the description discloses the output form per collection (images, rebuilt HTML flows, screenshot sets) and the matching mechanism (word matches against flow names), which is real behavioral value not in the annotations. No rate limits or auth context, so not a 5.

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 paragraph, front-loaded with the core purpose before the per-type breakdown. It is efficient and every clause earns its place, though the run-on structure packs a lot into one sentence.

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 must carry return-value expectations, and it does so qualitatively for each type (images vs HTML flows vs screenshot sets). Combined with the 100%-covered schema, an agent has enough to invoke correctly, though concrete shape/count details of results are left implicit.

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 the baseline is 3, but the description adds cross-parameter relationships the schema states only per-field: that `platform` is app-screens-only, `category` is app-store-screenshots-only, and `query` applies to app-screens and html-flows. This mapping genuinely helps an agent combine parameters correctly.

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 and resource ('returns real reference designs from Better Design's library') and then enumerates the three collections selectable via `type`, each with its own characterization. An agent can tell it apart from the many sibling 'get-*' guide tools, which return guidance rather than reference designs.

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?

Explains how to select each `type` and which narrowing parameter (`query`, `platform`, `category`) accompanies it, giving clear selection context. It stops short of stating when to prefer this over alternatives or any exclusions, so it falls short of the explicit when/when-not bar.

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 safety is covered. The description adds some behavioral context (the tune-in-place panel is meant to be wired into the app being built; the standalone kit is the MIT Toolcraft starter) but says nothing about the return shape, how the setup code is delivered, or that the framework argument is ignored for two of the three kinds.

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?

Purpose is front-loaded and the three branches are enumerated in parallel, readable structure. It is somewhat verbose and re-covers ground already present in the enum descriptions, but no sentence is wasted.

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 carries the burden of explaining what comes back. It conveys the concept (a control panel, a starter kit, a variant canvas) but never specifies the form of the result — code text, files, install steps — leaving an agent unsure how to consume the response.

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 both enums fully annotated, so the baseline is 3. The description largely restates the schema's kind and framework definitions rather than adding new semantics (e.g., output differences per branch), so it adds little beyond what the schema already provides.

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 opening sentence gives a specific verb + resource ('Returns setup code for a jig') and the three kind branches are named concretely. It does not, however, differentiate itself from the many sibling get-*-guide tools (get-motion-guide, get-design-system-kit, get-widget-guide), so an agent has only the name and the 'jig' framing to distinguish it.

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 kind-by-kind explanation implicitly tells the agent which branch suits which user need, but the same mapping is already spelled out in the schema's enum descriptions. There is no explicit statement of when to reach for this tool versus the sibling guide tools, and no prerequisites 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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real context beyond that: maxTokens truncates guidance content, and scaffold and component ignore maxTokens because they always return whole files. It does not mention auth, rate limits, or formatting of the guidance output, but for a read-only guide this is solid.

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 core purpose is front-loaded in the first clause, followed by the mode semantics and a short provenance note. Three dense sentences with little waste, though the trailing registry sentence is the least load-bearing.

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 the job of explaining what each invocation shape returns and how truncation works. What is missing is workflow positioning relative to the video siblings, which matters given how many guide/plan/render tools exist, but everything needed to call this tool correctly is present.

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 the per-parameter docs already carry the load and the baseline is 3. The description earns the extra point by explaining mode interactions the schema does not: no arguments lists components, scaffold:true yields a whole project, component yields one component's source plus install command.

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 and resource: it returns best-practices guidance, brand/motion tokens, format profiles, and video components for building Remotion product demos in code. That is clearly distinguishable from most siblings, though it never names the adjacent video siblings (plan-video, render-video-frames) that an agent might also consider.

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?

'Start here when building a video' gives a genuine entry-point cue, and the mode sentences hint at when to use scaffold vs component vs no-argument listing. However, it offers no explicit routing against the other video tools in the sibling set (plan-video, render-video-frames), so the agent must infer the boundary itself.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine context beyond them: rules are keyed to severities, they are 'read against source', and a clean self-review does not constitute visual approval. It doesn't describe ordering or result size behaviour, which keeps it out of 5 territory.

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?

Four short sentences, front-loaded with what is returned before the usage hint and the parameter note. Nothing is padded, though the 'Pass `category` for one group' sentence earns little since the enum already carries that 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?

There is no output schema, so the description must convey the return shape, and it does: a set of rules tagged by severity across six named categories. Combined with the caveat about source-based evaluation, an agent has enough to call this correctly; only the alternative-tool guidance 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%, so both parameters are already documented, establishing a baseline of 3. The description restates the category filter ('Pass `category` for one group') and only loosely paraphrases maxTokens as 'limits the length of the response', which is actually less precise than the schema's note that required workflow guidance is always returned outside the budget.

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 and resource ('Returns Better Design's review rules for UI code') and enumerates the rule groups and their severity dimension, so the agent knows exactly what payload to expect. It stops short of distinguishing itself from near-neighbours like get-team-rules or get-ui-principle, which an agent could plausibly confuse with this tool.

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

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

Gives an explicit trigger condition: 'Use it when the user wants UI code reviewed.' It also adds an important qualifier that a clean self-review is not visual approval, which scopes expectations. However, it never names an alternative tool or a when-not condition, so sibling routing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the empty-input call returns an index of topics, and topic vs query select different lookup strategies. It is a knowledge read with no side effects, so no destruction/auth caveats are needed.

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 returned resource, then the invocation modes, then the usage trigger. Three tight sentences with no redundancy or filler; every clause carries information an agent needs.

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 lookup tool with no required parameters and no output schema, the definition covers content scope, invocation modes and usage trigger adequately. It could optionally note the maxTokens truncation behavior, but the schema already documents that parameter, so the gap is minor.

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 the per-parameter documentation is already in structured data, giving a baseline of 3. The description goes further by explaining how the parameters interact and what happens when none is supplied (the topic index), which is not captured by the individual schema descriptions.

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 ('Returns') plus the exact resource (Better Design's sales principles) and enumerates the covered topics: objection handling, champion preparation, feature-to-value mapping. The 'sales' framing clearly separates it from sibling knowledge tools like get-ui-principle and get-ux-principle without needing to open any 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?

Gives explicit triggering context: 'Use it when the user prepares a sales conversation or writes a sales asset.' That is real when-to-use guidance, and the three invocation modes (topic / query / nothing) orient the agent further. It stops short of naming a sibling alternative or stating a when-not condition, so it lands just below the top.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that the content is curated best-practice material with outbound documentation links, which is useful, but says nothing about truncation limits, content format, or coverage boundaries.

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 sentences, zero filler, front-loaded with what is returned before the invocation modes. The topic enumeration is dense but earns its length by letting the agent judge relevance without a round trip.

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 describe the return content (best practices plus doc links), and all three parameters are covered between schema and description. Minor gaps remain around returned format and truncation behavior, but nothing that would cause a mis-call.

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% with detailed per-parameter descriptions, so the baseline is 3. The description adds one genuinely non-schema behavior: passing nothing returns the topic index, which is invocation-relevant information the schema does not convey.

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 (returns best practices) and resource (Better Design's Shopify Liquid / Online Store 2.0 theme guidance) and enumerates the covered subject areas, which cleanly separates it from the other domain guides in the sibling set (get-swiftui-guide, get-motion-guide, get-jig-guide). An agent can identify the domain 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 final sentence tells the agent exactly how to invoke it in three modes (topic, query, or nothing for the index), which is real usage guidance. It does not state when to prefer this over sibling guides or when-not to use it, so it stops short of explicit alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds real value on top: it explicitly says the tool 'reads and writes nothing itself,' pre-empting confusion about the pull/push-to-App-Store-Connect commands it merely names. It clarifies that any side effects happen via user-run CLI, not through this tool.

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 sentences, front-loaded with the primary return content, followed by the referenced commands and the no-side-effects caveat. Dense but each sentence carries information; 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?

No output schema or parameters, so the description must characterize the returned content, which it does concretely (config file, screenshot folders, field limits, device sizes). Combined with annotations covering the safety profile, an agent has enough to call and interpret 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?

Zero parameters, so the baseline is 4 and there is no parameter surface to document. Schema coverage is 100% and nothing is required, so no compensating detail is needed.

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 (returns) and resource (how an App Store listing lives as files: store.config.json text, per-language/device screenshot folders, field limits, screenshot sizes). The content is distinctive enough that an agent can distinguish it from generic siblings like get-swiftui-guide or get-widget-guide, but it never explicitly contrasts itself with those 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 explains what the guide contains but never states when to consult it versus the many other get-*-guide siblings. Mentioning the `npx better-design listing` commands is descriptive content, not a usage condition or alternative-selection rule.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully discloses what kind of payload comes back (best practices plus Swift examples across three domains), but says nothing about caching, freshness, or how the truncation behavior interacts with the requested topic. Adequate but not 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?

Two sentences, no filler. The return contract is front-loaded in the first sentence and the invocation modes in the second, so an agent can act after reading the opening clause.

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 guide lookup with no output schema, the description covers subject scope and the empty-argument fallback, which are the two things an agent must know to call it correctly. Minor gaps remain around result freshness and how topic/query interact, but nothing blocking 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 coverage is 100%, so the baseline is 3. The description earns an extra point by documenting behavior the schema cannot express: passing nothing returns 'the index of topics', which is a meaningful mode distinction an agent would otherwise have to guess. It still leaves the topic-vs-query selection heuristic 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?

States a specific verb (Returns) plus the resource (best practices and Swift examples for SwiftUI interfaces) and enumerates the covered domains: layout/view composition, animation and gestures, Metal shader effects. It is clearly a documentation-retrieval tool, though it never distinguishes itself from adjacent guide siblings such as get-motion-guide or get-widget-guide, whose subject matter overlaps with 'animation and gestures'.

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 explains the three input modes ('Pass `topic`, `query`, or nothing for the index of topics'), which implies how to drive the tool, but there is no statement of when to prefer this guide over the sibling guide tools or when it is not appropriate. Usage is inferable rather than prescribed.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses the selective result shape and the fallback behavior when no rules exist ('returns an outline and the steps to draft them'), which an agent cannot infer 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?

Two sentences, front-loaded with the return value and its scope. The second sentence is a long run-on that could be tightened, but every clause (which rules are included, the empty-state behavior) 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?

No output schema exists, so the description carries the burden of explaining returns, and it does: it enumerates the four kinds of content returned and covers the no-rules case. Combined with annotations covering safety, an agent has what it needs, though it never states that all parameters are optional or what happens with partial input.

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 are already documented, including the dependency of parts/screen on projectId. The description restates the same project/screen/parts scoping without adding format or edge-case detail 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 gives a specific verb and resource ('Returns the Markdown rules the user's Better Design team wrote') and clarifies the scope (project guidelines, part rules, brand-wide bans, screen specs). It is distinguishable from set-team-rules/propose-team-rule by verb, though it never explicitly names a sibling like get-review-rules, so it falls short of full sibling differentiation.

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 implies the usage context (when building a screen, given project/screen/parts) and even describes the empty-state path, but gives no explicit when-to-use vs. when-not, no prerequisites, and no routing against the many related rule/design-system siblings. Usage is inferred rather than stated.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds a useful detail: maxTokens truncates content to fit. Otherwise it has no return-shape or error behavior notes, which is a modest but real gap.

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 sentences, front-loaded with what it returns and the topic list, then usage mode, then a caveat about maxTokens. Efficient and scannable, with no wasted clauses.

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 lookup tool with 100% schema coverage and no output schema, this is complete enough: the agent knows what comes back conceptually, how to select inputs, and when to invoke it. The remaining gap is lack of sibling disambiguation against other principle/guide tools.

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 schema already documents all three parameters, including aliases and recommended maxTokens range. The description reinforces the semantics of topic, query and maxTokens in-line, adding marginal value beyond the schema baseline.

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+resource: returns Better Design's visual design principles, and enumerates the covered topics (hierarchy, spacing, typography, color, etc.). It distinguishes itself from get-ux-principle and get-motion-guide in substance but never names those 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?

Gives a clear usage trigger ('use it when the user wants to know how an interface should look') and explains how to pick inputs (topic vs query vs nothing). It does not explicitly contrast with sibling principle tools like get-ux-principle or get-motion-guide, leaving the agent to infer the boundary.

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 readOnly, idempotent, non-destructive behavior, so the bar is lower. The description adds genuine extra context: maxTokens truncates the response, and omitting both params returns a topic index. It does not describe the shape of a returned principle, but the safety/behavioral profile is well covered.

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 sentences, front-loaded with what is returned before how to call it. The long topic enumeration is informative rather than padding, though it slightly bloats the first sentence. No wasted clauses.

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, zero-required-param lookup tool with no output schema, the description covers purpose, modes, topic scope and truncation. The only gap is what a returned principle actually looks like, which matters somewhat given there is no output schema to fall back on.

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 the baseline is 3, but the description goes further by explaining the cross-parameter routing logic (topic = one principle, query = situation search, neither = index) and restates maxTokens' limiting role. That is real meaning beyond the per-field 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?

States a specific verb (Returns) and resource (Better Design's UX principles) and enumerates the covered topics, so the agent knows the content domain precisely. However, it never distinguishes itself from the very similar sibling get-ui-principle (nor get-sales-principle/get-motion-guide), leaving real ambiguity about which of these to 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?

Gives a clear situational trigger: 'Use it when the user wants to know how an interface should behave or what its copy should say.' It also explains the three invocation modes (topic / query / nothing). It stops short of naming when NOT to use it versus the sibling principle tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive and non-openWorld, so the safety profile is covered. The description adds genuine behavior beyond that: an iterative fill-in-the-gaps flow and the contents of the returned brief (calculation accuracy, form behavior, search visibility, performance, privacy rules).

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 sentences, front-loaded with the core purpose, then the interaction model, then the alternate mode. Slightly dense in the final sentence but every clause conveys distinct information 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?

With no output schema present, the description must describe the return value, and it does: missing-details list followed by the brief with its rule categories. Combined with 100% schema coverage on 13 parameters, the definition is nearly self-sufficient; only the omission of truncation/response-size behavior (left to the maxTokens schema field) keeps it off 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?

Schema description coverage is 100% across all 13 parameters, so the schema already carries the parameter documentation. The description reinforces only the `format` enum meaning ('page-family' returns a brief for a family of pages built from dataset rows), which the schema also states. Baseline 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 and resource: 'Returns a build brief for an interactive widget on an article or landing page', and enumerates what the brief contains. The resource is unambiguous against sibling guide tools (get-jig-guide, get-motion-guide), but the description never explicitly distinguishes itself from those 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?

Gives clear invocation context: 'Pass what is known about the widget', implying partial input is acceptable, and the response tells the caller what is still missing. The page-family mode is scoped with a concrete example. No explicit when-not-to-use or named alternatives are given.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real behavioral context: the first call returns a script rather than findings, density checks only apply at desktop widths, and — most valuably — 'it measures geometry only, so a clean result is not visual approval', which caps the agent's interpretation of a pass.

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?

Four sentences, front-loaded with purpose followed by the workflow and the caveat. Every sentence carries information and nothing is redundant, though the second and third sentences are dense enough that a sub-clause could be trimmed.

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 two-phase, 5-parameter tool with an output schema and rich annotations, all the agent needs is present: what it does, the call sequence, what inputs the second call expects, and the limits of the result. Return values are covered by the output schema, so the description is complete.

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 baseline is 3. The description goes slightly beyond the schema by explaining what the states parameter actually contains (viewport widths, hover and focus states) and that density is checked against compact/comfortable/spacious, giving conceptual grounding the schema alone doesn't.

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 and resource — measures spacing in a rendered interface from DOM geometry — and states the deliverable: spacing faults with a correction for each. No sibling tool covers rendered spacing, and the two-call protocol is spelled out, so an agent can immediately tell what this does.

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 describes the workflow condition: call once without states to get the capture script, call again with captured states to get findings. That is clear usage context. It stops short of naming an alternative tool or an explicit when-not-to-use, so it is not a full 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds genuinely useful context beyond these: it returns files as text rather than writing them ('It writes no files'), which prevents an agent from assuming an install actually mutates the filesystem despite the 'install' name.

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 action and output shape, and closed with the two most important caveats (no file writes, parameter provenance). No sentence is wasted.

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 carries the return-value burden and does so adequately by describing the component-per-icon files and barrel index. It is slightly incomplete in that it only describes the tsx return shape and doesn't note the svg alternative, though the schema covers the format parameter.

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

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

Schema description coverage is 100%, so every parameter (names, format, variant, libraryId, targetDir) is already documented with meaning and examples. The description references libraryId and names but adds no syntax, defaults, or format nuance beyond the schema, so the baseline 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 a specific verb and resource ('Fetches the named icons from the public Iconify API') and details the exact output (one React component file per icon plus an index.ts barrel, as text). It also distinguishes itself from siblings by naming find-icons as the source of the names, clarifying that this is a preparation step rather than a search or write.

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 provides clear workflow context by stating it takes a libraryId and icon names 'from find-icons', which routes the agent to the upstream tool. It doesn't state explicit when-not conditions or name alternative installers, so it stops short of a full 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true, but the description adds substantial behavior the annotations cannot convey: a per-call cost (3 credits), an authentication requirement (Better Design API key with verified email), the generated outputs (page, PNG, PDF links returned at once), and that the links resolve/show once ready. This is exactly the extra context the annotations do not carry.

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 sentences, front-loaded with purpose, then generation behavior, then output/cost/auth. Each sentence carries distinct information and nothing is redundant. Slightly dense in the final sentence, but well structured.

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 usefully names the return values (page, PNG and PDF links) and the async "show the page when it is ready" behavior, plus cost and auth prerequisites. For a 12-parameter, non-idempotent generation tool this is nearly complete; only timing/retry semantics for the pending state are left implicit.

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 schema already documents all 12 parameters including optionality and lengths. The description references several inputs (company, website, offer, call-to-action link, design system) but adds no syntax, format, or constraint beyond what the schema states. 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?

States a specific verb ("Makes") and resource ("a hosted sales page ... with the same page as a one-page PDF"), which cleanly distinguishes it from siblings like make-social-image and plan-video. The scope (one account, catalog design system, source inputs) is concrete enough that an agent can identify the tool 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 description gives usage preconditions ("works only on connections that use a Better Design API key from an account with a verified email") and scoping ("for one account"), which is useful context. However, it never says when to choose this tool over alternatives such as make-social-image, nor any when-not conditions, so usage is only implied.

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?

Goes well beyond annotations by disclosing cost (2 credits per call), an authentication prerequisite (API key from a verified-email account), an async return behavior (links return immediately but resolve to the image when ready), and the auto-generated headline fallback. These are exactly the operational facts an agent needs before invoking.

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 dense sentences, front-loaded with the purpose, then behavior, then cost/auth constraints. The return-behavior sentence ('returns the page and PNG links at once, and they show the image when it is ready') is slightly awkward but still informative.

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 does so (page and PNG links, async readiness). With 7 params, 5 required, and a mutation with cost, the description covers the essentials an agent needs to call 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 100%, so the baseline is 3; the description adds cross-tool provenance for designSystemId ('from find-design-system') and clarifies headline is auto-written when omitted. Remaining parameters are only covered by the schema, not 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?

States a specific verb and artifact ('Makes a LinkedIn-size social image') plus the exact source inputs (company, website, offer, CTA link) and design system. The LinkedIn-size/PNG framing clearly separates it from sibling tools like make-sales-page.

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?

Provides real gating context: it operates on one account, requires a connection using a Better Design API key with a verified email, and costs 2 credits per call. It doesn't explicitly name an alternative tool for other image/page needs, so it stops short of explicit when-not 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real behavioral context beyond them by enumerating exactly what is produced (beats, per-beat components with alternatives, frame budget, an install command string, a renderable Remotion file) and noting that the film type is inferred. Given no output schema, this output disclosure is valuable.

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 dense sentences, front-loaded with the core action and outputs, followed by inference behavior. Every clause carries information about the produced artifact. Slightly long but no filler or repetition.

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 carries the return-value burden and does so well by listing the deliverables. For a 4-parameter planning tool with strong annotations, an agent has enough to invoke it correctly. A note that it plans but does not render (routing to render-video-frames) would have completed the picture.

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% with descriptions for brief, length, and archetype already in the schema. The description restates that it 'takes a length and a format' and infers the archetype, which corroborates but adds little syntax beyond the schema. The undocumented 'format' parameter is not elaborated on in the description either, so it does not compensate for the coverage 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?

States a specific verb (Plans) and resource (a product film) and enumerates the concrete outputs: beats, one video component per beat, frame budget, install command, and a Remotion TransitionSeries file. This is far more informative than a generic 'plan a video' and lets an agent predict the artifact. It does not, however, name or distinguish itself from the related siblings like render-video-frames or get-motion-guide.

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 by describing what a one-line brief produces and that it infers the archetype from the brief, which hints at when it fits. But it never states when to choose this over siblings such as render-video-frames, or any preconditions/ordering. Guidance is implied rather than explicit.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine value beyond that by disclosing the return contents (component preview plus a link to the full live showcase), which helps the agent know what a successful call yields. It omits any auth or rate-limit context, but with full annotation coverage the bar is lower.

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 with zero filler; the core purpose and component inventory are front-loaded and the input-source note follows. Every clause 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?

For a single-parameter read tool with an output schema present, the description needn't explain return structure, and annotations carry the safety profile. It is nearly complete, with only the absence of any sibling routing as a minor gap.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema, including examples ('linear', 'editorial-warm'), so the baseline is 3. The description only restates the parameter's origin ('Takes an id from find-design-system') without adding format or constraint detail beyond what the schema provides.

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 and resource ('Returns a visual preview of a catalog design system') and enumerates what the preview contains (palette, typography, buttons, card, input, badge). This distinguishes it from data-oriented siblings like get-design-system-kit or extract-design-system, though it never names an alternative 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?

It supplies a prerequisite chain by stating 'Takes an id from find-design-system,' which tells the agent where the input comes from. However, it gives no explicit when-to-use vs. when-not guidance relative to the other design-system siblings (get-design-system-kit, extract-design-system, get-design-system-status), leaving selection to inference.

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

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

Annotations already declare the write/non-destructive/idempotent profile, and the description adds the critical behavior they cannot express: the rule is staged on the Team rules page and nothing follows it until the user approves it there. Permission, rate-limit and error behavior are left unstated, keeping this short of a 5.

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 sentences, no padding, with the deferred-approval constraint placed where it will be read. The opening clause 'Keeps one rule the user's agent proposed from the user's correction' is slightly dense but still parses on one pass.

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 three-required-parameter write tool with no output schema, the description covers what the tool does with the input and the lifecycle state the record lands in. Only the post-call result (confirmation or identifier) is unaddressed, which is a minor gap given annotations cover idempotency.

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?

All three parameters carry full schema descriptions including max lengths, so the schema does the heavy lifting. The description's 'why it exists and where it applies' merely restates the 'why' and 'where' fields rather than adding syntax or format guidance, which is the expected baseline at 100% 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 verb 'keeps' plus the resource 'one rule' and the scope 'from the user's correction' make the operation identifiable, and the 'waits on the rules page' clause signals it is a staging/proposal write rather than an activation. It stops short of naming the sibling it differs from, so an agent must infer how propose-team-rule relates to set-team-rules or get-team-rules.

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 trigger context is explicit: a rule that came out of a user correction is what belongs here, and the description makes clear the tool is not for applying rules that are already live. It offers no explicit when-not or named alternative, but the pending-approval framing gives an agent enough to decide.

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 safety is covered. The description adds real value by explaining return content and the no-filter behavior, but no output schema exists and it doesn't mention the 2MB map size limit or payload cost disclosed 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?

Four sentences, front-loaded with the return shape before parameter and use-case detail. Mostly efficient, though the `map` instruction overlaps with what the schema already says, so it isn't maximally tight.

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?

A read-only tool with full annotation coverage and no output schema; the description explains return values and the two main usage modes. It is nearly complete, missing only edge details like the map size limit and how results are ordered/truncated.

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% (baseline 3), and the schema already documents all five parameters exhaustively. The description goes slightly beyond by framing `planned` as a pre-build check against the Main Quest, but mostly restates the `map` parameter the schema already defines.

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 ('Returns') and resource ('flows in a feature map') and details what each returned flow contains: 'the screen, route, components and data files of every step.' An agent can tell this is the read counterpart to build-feature-map and update-feature-map without opening either 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?

Gives clear usage context: unfiltered calls list every flow plus the Main Quest, and `planned` is for checking new work before building it. However, it never names the sibling alternatives (build-feature-map, update-feature-map) or states when NOT to use this read.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the return behavior is conditional — it emits Remotion commands plus a checklist, and only renders actual images on a connection running on the user's machine. That dual-mode behavior is not derivable from any structured field.

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 sentences, no filler, and the primary capability is front-loaded before the conditional rendering detail. Slightly dense in the second sentence, where two distinct modes are compressed together, but nothing is wasted.

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 carries the burden of describing returns and does so (commands, checklist, images). For a six-parameter tool with a nested props object it is largely sufficient, though the ambiguity about exactly what comes back in each connection mode 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 description coverage is 100%, so all six parameters (entry, props, scale, frames, projectDir, composition) are already documented in the schema, including the non-obvious guidance on picking first/settled/last frames and keeping scale small. The description adds nothing parameter-level, so the baseline 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?

Specific verb and resource: renders chosen frames of a Remotion composition as images, and names the concrete artifacts returned (Remotion commands plus a review checklist). It is clearly distinguishable from plan-video and the design-system siblings. It stops short of naming any sibling it could be confused with, but the action 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 never says when to reach for this tool versus plan-video (the obvious adjacent sibling) or when not to. The only situational cue is an implicit review workflow ('a checklist for reviewing them'), which the agent must infer. No prerequisites or preconditions are stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety bar is lower. The description adds genuine behavioral context beyond them: the review is against a fixed rubric and the outcome is binary (PASS, or FAIL with every finding surfaced as a tool error), which tells the agent how to interpret the result.

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 sentences, front-loaded with the rubric criteria and followed by the inputs and return behavior. The rubric enumeration is long but each item earns its place; 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 validation tool with no output schema, the description covers what is checked, what inputs are required, and what the pass/fail outcome means. It is complete enough to call correctly; only explicit routing against sibling review tools 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%, so the baseline is 3. The description restates that source, fixture, interpretation, and component sources must be passed but adds no syntax or format nuance beyond what the schema already documents, including the nested fixture object.

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 (reviews) and resource (dashboard or overview page source) and enumerates the rubric: complete source, unchanged data, supported claims, hierarchy, scan order, and component usage. An agent knows exactly what the tool inspects. It does not explicitly name or distinguish itself from the similarly-named sibling finalize-dashboard-review, 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?

Invocation context is implied by 'Pass the page source, the data fixture, its interpretation and the component sources', which tells the agent how to call it, but there is no explicit when-to-use versus the related finalize-dashboard-review or get-review-rules siblings, and no stated 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?

Adds behavior beyond annotations: unsafe SVGs (scripts, event handlers, remote references) are refused, and re-reviewing with a token is free, which the non-idempotent annotation alone wouldn't convey. The readOnlyHint=false profile is consistent with a rendering/validation operation, and it discloses the rejection policy rather than just 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?

Four compact sentences, front-loaded with what the tool does, then invocation advice, then the safety caveat. No filler, though the style guidance partially duplicates the schema's enum description.

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 an output schema present the return shape needn't be explained, and the description covers inputs, the token reuse flow, and the refusal condition. Only the `animated` motion-check parameter is unaddressed, leaving a minor gap for a moderately complex 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 100%, so the schema already documents all five parameters; the description mostly restates the intent and style semantics already in the schema. It does not explain the `animated` flag at all, so it adds little beyond the structured fields.

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 (renders) and resource (SVG illustration in a browser) and specifies the exact output (visible faults against illustration principles) with concrete examples of fault categories. An agent can distinguish it from get-illustration-guide (which supplies rules) 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?

Gives clear invocation context: pass the SVG plus intent, use style "isometric" for technical figures, and reuse reviewToken to re-review the same drawing. It doesn't explicitly name alternative siblings or state when not to use it, but the operator conditions are concrete.

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 destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=true. The description adds genuinely useful context beyond them: the merge-over-current semantics, that saved values overwrite earlier ones, and that anyone with the config URL can read them.

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 tightly written sentences, front-loaded with the action and resource, followed by merge/visibility semantics. No wasted clauses, though the second sentence combines two ideas.

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 return values need not be explained. For a 2-param write with 100% schema coverage and rich annotations, the merge/overwrite behavior and read-visibility note make it nearly complete; only explicit sibling routing 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% and the schema already documents each config field with examples (oklch strings, rem radius, density enum). The description restates the same field groups, so the 3 baseline is appropriate with the schema carrying the load.

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 (Saves) and resource (exact design token values) plus the target (a generated project) and the fields touched (colors, radius, fonts, icon library, layout density). It is clearly the write counterpart to the read-only get-design-config sibling, and the merge wording further pins down 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?

Usage is implied by 'merged over its current config' and 'saved values replace the earlier ones', which tells the agent this is a partial-update write. However, it names no alternative and gives no explicit when-to-use/when-not guidance (e.g. vs create-design-system or get-design-config).

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds genuine behavioral context beyond that: it will refuse to overwrite differing saved text unless the user agreed, and saving is gated on the person having read and approved the exact draft.

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?

Only two sentences and the main verb leads, which is good. However, the long middle clause ('its guidelines, a use, never or pairing rule for one part, a brand-wide ban, or a spec on a screen') is densely stacked and awkward enough to slow parsing rather than inform.

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 seven parameters, a destructive write tool needs its approval gating and refusal semantics stated, and both are present. Minor gaps remain (what a successful save returns, the intended relationship to propose-team-rule), but nothing essential to invoking it 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%, so the schema already documents kind, part, screen, markdown, projectId, personApproved and replaceExisting in detail. The description restates the kind selection logic (screen alone means spec, nothing means guidelines) but adds no syntax or edge-case detail the schema lacks, so baseline 3 is correct.

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 (saves) and resource (Markdown rules as the team's rules, or one project piece), and enumerates the granular kinds it can write (guidelines, use, never, pairing, spec). An agent can tell this is the write counterpart to the read-only get-team-rules, though the description never names that sibling 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?

Implies when each mode applies (no projectId = team rules, projectId = one piece, with kind distinguishing), and states the refusal condition for replacement. It never names an alternative such as propose-team-rule or explains when to use that draft-then-save loop, so routing guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, and the description is consistent with that by framing the tool as a transform that 'returns the updated map' rather than a side-effecting write. It usefully adds the single-change atomicity constraint, but leaves the persistence question open — an agent cannot tell from the description whether the returned map must be written back to .better-design/feature-map.json or what happens on an invalid op.

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 with the verb first and no filler; every clause maps to real functionality. It is dense with a long enumerated list, but nothing is redundant or wasted.

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 high-complexity, 10-variant oneOf tool with no output schema and a readOnly annotation, the description covers the op space broadly and states the return value. The critical gap is the write-back/persistence model and error behavior on malformed ops, which an agent needs before composing a call.

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 50%: the 'map' param is documented as 'the exact contents of .better-design/feature-map.json' while the large 'change' oneOf is self-describing via const ops. The description adds a prose summary of the op set, which helps an agent skim the union, but it neither enumerates every op (end-main-quest, add/remove-initiative, set-initiative are only loosely implied) nor clarifies required fields per op. Baseline 3 is appropriate given 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?

States a concrete verb ('Applies one change') and resource ('feature map') and enumerates the operation space (add/rename/remove feature or flow, set Main Quest and initiatives, link flow to initiative), so the agent knows exactly what the tool covers. It never names the obvious siblings read-feature-map or build-feature-map, so the boundary against those is left implicit rather than stated.

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 'Applies one change' implies an incremental workflow (repeated calls for multiple edits), which is a weak usage signal distinguishing it from a from-scratch builder. There is no explicit when-to-use/when-not, no named alternative, and no prerequisites such as needing to read the map first.

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