UiChemy AI Website Creator

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

Annotations (readOnlyHint=false, destructiveHint=true) already signal a mutating tool, and the description adds genuinely useful behavior beyond them: the three-article-page cap and name-matching rule, that existing same-named pages are reused rather than clobbered, and how the canvas paints post data. It does not cover permissions or what the call returns.

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, but the body is a dense wall of prose with defensive asides ("that is not a shortcut") and heavy all-caps emphasis that could be trimmed. Sizing is defensible for a structural tool, yet several clauses do more explaining than instructing.

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 multi-page creation tool with no output schema and 7 params, it discloses the important structural constraints (page naming, article cap, archive set, export caveat). The gaps are the layouts/categories params and any indication of what the call yields.

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

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

With 57% schema coverage, the description does real work: it defines the archives flag's default and effect, states articleSections must include post-featured-area and post-content, and ties post title/byline/date/read time to fields. layouts and categories semantics are still left largely to the schema, so it only partially compensates.

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

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

Opens with a specific verb+resource: "Give a project a blog," then enumerates exactly what it produces (listing page, article page per post, four archives, the posts). This is clearly distinguishable from siblings like uichemy_add_page or uichemy_add_section, which each build a single primitive rather than a whole blog structure.

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 concrete alternative mode ("Pass archives: false for the two-page blog this tool used to make") and an explicit exclusion (the WordPress export builds posts from the backend collection, not from what this writes). Clear when-to-use and one when-not, though it never names a sibling tool as the alternative path.

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 flag destructiveHint=true, but the description goes further by explaining exactly what is destroyed and why — slot tokens belong to the layout, so copy is overwritten on other pages sharing that layout. It also discloses the duplicate-name refusal and the fallback-token rendering consequence, which 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?

Front-loads the most dangerous behavior (the OVERWRITES warning) before anything else, which is the right ordering. It is dense and long, but nearly every clause carries an actionable rule; a small amount of restructuring could reduce the wall-of-text feel.

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 destructive multi-parameter creation tool with no output schema, it covers behavior, prerequisites, and naming/category rules thoroughly. It never states what the call returns (page id? node reference?) or how failures other than duplicate names surface, which is the main remaining gap.

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

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

With only 25% schema coverage, the description compensates well for `category` by mapping enum values to real filing decisions and explaining the omitted-category inference rule. It also constrains `sections` composition (navbar/footer placement, section count) and implies the required template-slots lookup, though it says nothing about `projectId` or the `text`/`images` object shapes.

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 ('Add a whole page to a project — the sitemap node, its sections, their layouts and their copy') and implicitly distinguishes itself from uichemy_add_section and uichemy_add_blog by scoping to a whole page. An agent can tell what this creates 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 explicit prerequisites ('Call uichemy_template_slots for every layout first and fill EVERY text slot'), composition rules (navbar first, footer last, 5-8 sections), category routing (policy→Legal, blog post→Blog, 404→Site Extras), and a named constraint ('Refuses a page name that already exists').

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 and readOnlyHint=false, but the description adds materially more: that `text` OVERWRITES copy shared by the layout elsewhere in the project, that both the sitemap node and variant map are mutated together, and that blog pages enforce a hard section whitelist with refusal behavior. These are non-obvious, high-consequence details an agent could not infer from the annotations.

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

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

Dense but nearly every sentence adds non-redundant information (overwrite semantics, dual-document write, slot-filling alternative, blog constraints). The structure is the weak point: it opens with a caveat about `text` rather than the core action, so the purpose statement lands second, and the all-caps blog block is louder than its relative importance.

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 destructive, 7-parameter, nested-object mutation tool with no output schema, the description covers the important behavioral risks: shared-layout copy overwrite, dual-document consistency, and page-type restrictions. It does not say what the call returns or whether the new section's identifier/index is reported back, which an agent planning follow-up edits would want.

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 only 43% across 7 parameters, so the description carries a real compensation burden. It adds meaningful semantics for `text` (slot tokens belong to the layout, overwrite scope) and implies `index` via 'at a position', but says nothing about `images`, `projectId`, or `pageName`, and does not clarify the required `variant` layout-id resolution beyond what the schema already states. Partial compensation only.

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: 'Add a section to a page at a position.' It also distinguishes itself from the failure mode of editing only one document, which implicitly separates it from sibling tools like replace_section or set_section_style. However, the actual purpose statement is buried in the second sentence behind a caveat about copy overwriting, so the agent has to read past a warning to learn what the tool 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 routes the agent to sibling tools ('call uichemy_template_slots and pass `text`'), names the data sources for the required fields (uichemy_list_section_kinds, uichemy_list_templates), and provides a concrete when-not clause: BLOG PAGES ARE CONSTRAINED, with the exact allowed section set per blog page type and the note that disallowed sections are 'refused, not added.' That is about as complete as usage guidance gets.

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 and readOnlyHint=false, and the description adds substantial behavior beyond them: ALL-OR-NOTHING semantics, that a single invalid op refuses the whole batch and writes nothing, that all problems are named so the batch can be resent, that ops execute in the order given, and the concurrency hazard with someone editing in the browser. This is exactly the extra context annotations cannot 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-loaded with the core claim and the op inventory before the rationale; every sentence carries information (collision risk, atomicity, error reporting, link semantics). The half-applied 'fourteen changes' illustration is vivid but slightly longer than needed.

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 12-variant union schema with no output schema, the description covers the critical contract an agent needs: ordering, atomic validation, error reporting, and one worked op example. It is thin on per-op field guidance (icon, iconColor, sectionSurface, textStyle) and on projectId, which leaves some calling risk unaddressed.

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?

Top-level schema description coverage is 0% (projectId and ops carry no descriptions), so the description must compensate and it only partly does: it explains execution ordering and details the `link` op (key sourced from uichemy_list_links, href semantics identical to uichemy_set_link). It never mentions projectId, the 200-op cap, or how the remaining ten op variants map to the listed edit categories, leaving gaps the schema alone does not fill.

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 states a specific verb and resource ('Many edits in ONE write') and then enumerates exactly which edit classes the batch accepts (copy, pictures, videos, text styles, button roles, badge designs, image display, section backgrounds/icons). This lets an agent distinguish it from the ~30 sibling set_* tools it supersedes.

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 routes the agent: 'Prefer this to calling the single tools thirty times,' naming the alternative and giving the reason (each single call is its own revision and risks colliding with a browser editor, leaving a half-applied state). The atomicity note reinforces when this tool is the right choice.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this ('takes no project and changes nothing') and adds valuable domain context about project-wide slot token sharing. However, it doesn't describe the return shape (the clash report an agent would act on), leaving that 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?

Front-loaded with purpose and timing; each sentence carries information (mechanism, timing, consequence). Slightly long but no dead weight.

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, and the description explains when/why to call but not what the check returns (e.g., a list of clashing tokens/layout pairs). Minor gap, but the decision-critical context 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% and the schema includes a concrete example of the layouts array with kind/variant. The description adds no parameter-specific syntax or semantics beyond what the schema already provides, so 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 (check) with resource (layouts), scope (a SHORTLIST, cross-checked against each other), and the actual defect it detects (shared slot tokens). Clearly distinct from siblings like search_layouts or create_project.

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?

Explicit timing guidance ('Call this while choosing sections, not after'), names the sibling create_project as the point after which it's too late, and explains the cost of skipping it ('no tool that re-layouts a built project').

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?

With readOnlyHint/destructiveHint already declaring safety, the description adds real mechanism: it reads the template's own Tailwind responsive classes (deterministic at a fixed width) and copy length against design intent, rather than rendering pixels. Stating what it explicitly does not do ('THIS IS NOT A SCREENSHOT') is useful behavioural context. It stops short of describing output shape or any execution caveats.

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 failure-mode list is front-loaded and informative, but the back half drifts into rhetorical justification about renderers that is longer than the task requires, and the capitalized disclaimer sits mid-paragraph rather than leading. Appropriately sized overall, but several sentences do not earn their 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 read-only check with no output schema and only two parameters, the description conveys what is inspected and the non-rendering nature well. It omits how findings are returned or scoped (per page vs whole project), leaving the agent without a full picture of the result it will receive.

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

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

Schema coverage is 50%: pageName is documented in the schema, but projectId carries no description. The description mentions 'slots' and 'a page' only in passing and adds no meaning about the projectId/pageName parameters, so it does not compensate for the documented gap.

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

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

The description enumerates concrete failure modes it detects (copy overflow, unfittable columns, oversized fixed widths, non-wrapping text, unreadable colours, unresolved slot tokens) at phone/tablet/desktop widths, so the resource and scope are clear. It also explicitly distinguishes itself from a screenshot/render check. It never states the verb+'resource' crisply up front, relying on the reader to infer that this is a read-only responsive audit.

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 contrasts itself with the 'second renderer' approach and disclaims being a screenshot, which implies when it is preferred over visual capture. However it never gives a use-this-when instruction, and it fails to differentiate from the very similar sibling uichemy_check_layouts, which an agent would need to choose between.

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 mark this readOnly=false and destructive=true, so the safety profile is known; the description adds genuinely non-derived context – that the call restores the template default and that it behaves the same under either key scheme, and that removal resolves rather than creates override conflicts. The word 'Safe' sits slightly awkwardly against destructiveHint=true, but it is a claim about idempotence/conflict resolution, not a contradiction. Gaps remain on no-op behavior when no override exists and on reversibility.

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

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

Two short sentences with the action front-loaded and no filler. Slightly idiosyncratic phrasing ('whatever the template ships', 'fighting pair') costs a little precision but does not pad the text.

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 small two-parameter mutation with no output schema, the description covers the effect but omits the practical details an agent needs: parameter formats, behavior when no override is present, and what a successful response indicates. Adequate but with clear gaps.

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

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

Both parameters are required and schema description coverage is 0%, so the description carries the full burden. It conveys only that a single icon is targeted ('one icon'), hinting at iconId, and vaguely gestures at key-scheme variants. It says nothing about projectId, its requiredness, or the expected format of iconId.

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 action on a specific resource: putting an icon back to the template default, i.e. clearing an override. That distinguishes it reasonably well from set_icon/set_icon_color, though it never names a sibling explicitly or uses the word 'override' (the noun in the tool name and in uichemy_list_icon_overrides).

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

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

The second sentence implies the scenario (resolving a 'fighting pair' of overrides) but gives no explicit when-to-use rule, no prerequisite such as listing overrides first to obtain iconId, and no statement of what to use when the goal is to change rather than clear an icon.

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 destructiveHint=true; the description adds real value beyond that by spelling out what is destroyed — alignment, size, colour and tag overrides are released back to global. It stops short of stating irreversibility or permission requirements, but the annotation already carries the safety profile.

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 tight clause, front-loaded with the action ('Put one element back to the global scale') followed by the released properties. No filler; only minor loss is the em-dash list being slightly terse on ordering.

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 destructive mutation with annotation coverage, the description adequately conveys effect but leaves the two required parameters entirely undocumented and offers no prerequisite or permission context. Complete enough to understand intent, not enough to call it safely without the schema.

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

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

Schema description coverage is 0% and both parameters (projectId, textKey) are required, yet the description never mentions either. 'One element' loosely hints at textKey but projectId and the identifier format are completely unspecified, so the description fails to compensate for the schema 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?

Names a clear action (put one element back to the global scale) and enumerates exactly which properties are released (alignment, size, colour, tag). This makes the reset semantics distinguishable from a plain style-setter, though it never names the relevant sibling (uichemy_set_text_style).

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 rather than stated: reverting an element to global-scale styling tells the agent roughly when to reach for it, but there is no explicit when/when-not guidance and no named alternative such as set_text_style for applying instead of clearing overrides.

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

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

Annotations only tell the agent this is a non-read, non-destructive, closed-world write. The description goes well beyond: it is idempotent, writes only what changed, makes no AI call, and reports residual first-open behavior (random layout / AI copy fill). That is exactly the extra behavioral context 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?

The content is valuable but packed into long, comma-chained sentences, and it opens with a reference to an editor button rather than a direct verb+resource. It is dense enough that the core action is not front-loaded as sharply as it could be.

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 carry return-value duty and does state what it would report back ('Says what, if anything, the canvas would still do'). Combined with the mutation effects and idempotency, an agent has enough to call it correctly, though the ambiguity of the 'Continue to design' reference 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 50%; sectionStyle is already documented in the schema as applying only when no section style exists. The description reinforces this ('pin the section style... would otherwise roll one at random') but adds no syntax or format detail, and projectId remains undocumented. Baseline 3 is appropriate.

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

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

The description names the concrete effects: derive colour roles, pin section style, write band colour and export section list, mark pages built. That is a specific, multi-step operation an agent can distinguish from siblings like set_palette or set_section_style. It never names a sibling explicitly, so it does not reach the top band.

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

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

It clearly states the trigger ('on the first canvas open'), asserts idempotency ('Safe to call again — it writes only what changed'), and notes the no-AI-call condition. It does not compare against the individual setters (set_section_style, set_palette) an agent might otherwise choose, so guidance is clear but not exhaustive.

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

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

Annotations only give the generic safety profile (not read-only, not destructive, closed-world). The description adds genuinely non-obvious behavior: empty text slots render their token, empty image slots keep stock photos, copy over a limit fails the entire call, duplicate layouts share copy, image slots require URLs so generated images must be uploaded first, and the response names unfilled slots and missing layouts.

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 action and the 'only way to start a project' constraint before details. It is long and dense, but nearly every sentence carries distinct operational information rather than filler; a small amount could still 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 an 8-parameter, deeply nested mutation with no output schema, the description covers the essentials an agent needs: required inputs, the slot/failure contract, global-section sharing, and what the result reports. Nothing critical is left 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 coverage is 100%, so the baseline is 3, but the description still adds meaning: `category` files a page in the sitemap and falls back to Core Pages, `brief` fills the Scope tab and is required, and headingFont/bodyFont/five palette colours are mandatory. It does not restate every nested SEO field, which is reasonable given the schema documents them.

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 ('Creates a new UiChemy project') plus the source ('from layouts in the UiChemy template library'). It also draws a hard boundary: 'It is the only way to start a project here' and explicitly names the sibling it is not (uichemy_get_page_code).

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 when-to-use ('the only way to start a project'), when-not ('HTML, CSS or JavaScript written elsewhere is not imported'), and routes the alternative case to uichemy_get_page_code. It also points to uichemy_template_slots for discovering the slot contract before calling.

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=false and destructiveHint=false, so the write/non-destructive profile is partly covered. The description adds value by specifying the non-destructive scope ('without touching the one currently applied') and the colors-omission seeding behavior. It is silent, however, on whether the new variant becomes active or what the call returns.

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 with zero filler, and the core action plus the key non-destructive guarantee are front-loaded ahead of the optional-parameter hint.

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 mutation tool with no output schema and one required parameter, the definition is adequate but leaves gaps: it does not say what the call returns (e.g. a variant identifier needed for later delete/list calls) or whether the created variant is immediately selectable, which an agent would reasonably want to know before chaining 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 coverage is 67%: the schema documents the `name` default and describes `colors` only vaguely as 'Concept colours, keyed by index', leaving `projectId` undocumented. The description compensates meaningfully for the weakest part of the schema by explaining that omitting `colors` seeds a built-in concept, which is not inferable from the schema itself.

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

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

The description uses a specific verb+resource ('Add a colour variant to a project') and clarifies the resulting artifact as 'another whole palette the user can switch to'. It implicitly distinguishes itself from set_palette by the phrase 'without touching the one currently applied', though it never names that sibling 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?

The 'Omit `colors` to seed it from one of the built-in concepts' clause gives one concrete usage condition, but there is no guidance on when to create a variant versus switching the active palette (set_palette) or its contrast with delete_variant/list_variants. The when-to-use context is implied 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 cover safety (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the bar is lower, yet the description still adds real context: it creates a new file, the source is left untouched in storage, and repeated crops do not compound. It does not address permissions or rate limits, but the behavioral picture is stronger than annotations alone.

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

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

Front-loads the core action and result before justifying it. Four sentences is on the longer side, and the export-survival sentence is more rationale than instruction, but each sentence carries useful information rather than restating the name.

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 convey return behavior; it does so by stating the result is a new file placed in the slot. Combined with the originality note and parameter rationale, an agent has enough to invoke it correctly, though explicit sibling routing is absent.

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

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

With 67% schema coverage, the schema documents most parameters, but the description adds genuine meaning for the ambiguous ones: `focus` as the surviving focal point and `maxWidth` as the guard against a 4000px photo filling a 400px card. It leaves `ratio` and `url` to the schema, which is acceptable.

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 ('Crop a picture to a shape, and/or shrink it'), immediately clarifying the result is a NEW file placed in the slot. This distinguishes it from siblings like edit_image_masked, set_image_display, and upload_image, which do not produce a cropped derivative file.

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 why cropping matters ('sections export to static HTML, so a crop that exists only as CSS ships uncropped'), which implies when to use it. However, it never names or excludes alternatives (e.g. edit_image_masked, set_image_display) or states prerequisites, leaving the agent to infer 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?

Goes well beyond the destructiveHint=true / readOnlyHint=false annotations: it states the operation is IRREVERSIBLE, that there is no restore point in the product, that nothing can read an earlier revision back, and it explains the opaque-id hazard that motivates confirmName. That is exactly the operational context an agent needs before a destructive call.

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

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

Front-loaded with the destructive fact and scope before any rationale, and every sentence carries content. The confirmName rationale runs long ('That is not ceremony —') and the closing sentence on superseded projects is a slight detour, so it is efficient rather than 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?

For a destructive tool with no output schema and only two params, it covers irreversibility, confirmation requirements, and the failure mode of stale ids. It does not mention auth/permission requirements or whether a project must be empty or unpublished before deletion, which would round it out.

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

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

Schema coverage is 50% (projectId is undocumented). The description compensates for confirmName by specifying exact-match semantics and the reason it exists — ids are opaque and a stale list may point at a different project — which is meaningfully more than the schema's 'exactly as uichemy_list_projects shows it.' projectId is left to inference, keeping it from a 5.

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

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

States a specific verb (delete) and resource (a whole project) and immediately scopes the blast radius: 'its sitemap, its sections and everything written into them.' This is clearly distinguishable from the sibling partial removals (remove_page, remove_section, delete_variant), which delete narrower things.

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 a use case in the closing sentence — superseded projects accumulate with no way to remove them except the browser — which tells the agent when this tool is the right lever. It does not explicitly name an alternative or state exclusions (e.g. it never says 'use remove_section for partial cleanup'), so it stops short of full routing 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 flag destructiveHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: the variant is removed from both the picker's list and the store, and it explains the referential-integrity consequence of a partial removal. It stops short of stating irreversibility or required permissions.

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 a short first sentence. The second sentence is a bit wordy and em-dash-heavy, but it earns its place by conveying the dual-list side effect.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter delete with annotations covering destructiveness and no output schema, the description covers purpose and side effects adequately. However, with both required parameters fully undocumented at 0% schema coverage, it leaves a meaningful gap for correct invocation.

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

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

Schema coverage is 0% and neither projectId nor variantId is described in the schema. The description only names the resource generically ('a colour variant'), so it does not compensate for the missing parameter documentation or clarify the project/variant relationship.

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 (Remove) and resource (colour variant), clearly distinct from siblings like create_variant and list_variants. It does not name an alternative sibling explicitly, but the delete semantics are 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives or exclusions. The agent is not told when deleting a variant is appropriate versus, say, editing or reordering it.

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 destructiveHint=true, and the description adds real context beyond them: the write touches only the sitemap, nothing on the rendered page changes, an empty string clears a note, and each write is one revision subject to race conditions. Minor gap: it never states permission/auth requirements or what happens to notes on sections not included in the call.

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

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

Purpose and the set_text disambiguation are front-loaded in the first sentence. Guidance is dense and each sentence carries a rule, though the editorial aside about notes restating section names is longer than needed and 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?

For a 3-parameter mutation with no output schema, the description covers the workflow (read before writing), the semantics (documentation vs. copy), the batching constraint, and the race-condition risk. Only the parameter-level details of index/projectId resolution are left entirely to the schema, which is a modest 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?

Top-level schema coverage is 0% (pageName, projectId, descriptions have no top-level descriptions), so the description has to compensate, and it does partially: it explains the array is a batch that must be sent as one write, and gives content guidance for the description field (say what the section is FOR, derived from uichemy_get_page). It does not explain the index parameter's 1-based ordering, which only the nested schema 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?

States a specific verb and resource — writing the sitemap note on a page's sections — and immediately disambiguates the concept: it is documentation shown in the sitemap panel, not rendered copy. It explicitly names the sibling it is not (uichemy_set_text), so an agent can separate the two 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 an explicit when-not (do not use this to put words on a section — that is uichemy_set_text), a prerequisite workflow (read uichemy_get_page first and describe the copy that is actually there), and a batching rule (every note on a page goes in ONE call). Alternatives and conditions are stated, not inferred.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the safety profile is coarse. The description adds a genuinely non-obvious behavioral trait: slot tokens belong to the LAYOUT, so the duplicate shares text sourcing with the original. It does not address whether the copy is independent for styling, where it lands, or name-collision handling.

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 verb and copied scope, followed by the caveat and the remediation path — a sensible information ordering with no filler sentences. The all-caps emphasis on 'THE COPY SHOWS THE SAME WORDS' is slightly shouty but conveys the key constraint efficiently.

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 mutation tool with no annotations detail and no output schema, the description covers what gets copied and the slot-token caveat well, but omits where the new page is placed, whether pageName must already exist, and what the caller receives back. Adequate but with clear gaps.

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

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

All three parameters are required and only newName has a schema description ('What the copy is called.'), giving 33% coverage. The description says nothing about projectId, pageName, or the naming parameter, so it does not compensate for the sparse schema — an agent gets no help on which project/page the copy is taken from.

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 ('Copy a page') and enumerates the copied scope (sections, layouts, backgrounds, overlays, padding), which is far more informative than the title alone. It does not explicitly name or contrast with the nearby sibling uichemy_duplicate_section, so an agent must infer the page-vs-section distinction.

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 not only states the operation but explains the critical usage consequence — the copy reads from the same slot tokens, so duplicating will not let you show different words — and routes the agent to the correct alternative workflow: use uichemy_replace_section to swap layouts, then write copy into those. That is explicit when-to-use-this and what-to-do-instead.

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

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

Annotations already declare the safety profile (write, not destructive, closed-world). The description adds substantive non-obvious behavior: the copy carries background, overlay and padding, and slot-token text is deliberately NOT duplicated (shared by construction). This explains preservation vs. sharing well; it omits auth/prerequisite and side effects on the source.

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 action, and each sentence carries a distinct point (routing, what's preserved, why text isn't copied). The prose is stylized and somewhat longer than strictly needed ('everything it is wearing', the unpainted-section aside), costing a little efficiency.

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 non-trivial write operation with no output schema and only 33% param coverage, the description covers the mechanics and the text-sharing nuance but leaves the two undocumented required params and any return value (e.g., an identifier for the new section) unexplained.

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

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

Schema coverage is 33%: only 'index' is documented (1-based, per get_page). The description never mentions projectId or pageName, which are the undocumented required params, so it does not compensate for the coverage gap. 'Put the copy after it' only loosely gestures at placement and adds little over 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 ('Copy a section... put the copy after it') plus the placement rule (after the original). It explicitly routes to the sibling ('uichemy_duplicate_page exists; this is the same move one level down'), so an agent can distinguish it from duplicate_page and other section tools without opening a 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?

Clearly positions itself relative to uichemy_duplicate_page as the section-level analog, giving the agent a strong selection cue. It does not, however, contrast against section-creation siblings like add_section or insert_saved_section, nor state when duplicating is preferable to adding fresh.

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

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

Annotations only say readOnly=false, destructive=true, openWorld=true; the description goes well beyond that by disclosing credit cost and the refund-to-actual-usage behavior, the plan requirement, and the crucial output semantics (result is a NEW file, the original stays in storage). That mutation/side-effect profile is exactly what an agent needs before invoking a destructive write.

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

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

It is a dense paragraph rather than skimmable lines, but the ordering is sound — action, modes, cost, mask inputs, output — and each clause carries information (mode semantics, defaulting, coordinate convention). Slightly long, but nothing is 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 an 8-parameter, nested-object, mutation tool with no output schema, the description covers the essentials: coordinate conventions, mask semantics, cost/refund, plan prerequisite, and where the result lands. It does not address failure modes (e.g., missing plan, model rejection) or timeout/latency expectations, which would complete 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?

With only 50% schema description coverage, the description usefully compensates: it explains `region` as a rectangle in 0–1 fractions measured from the top-left, defines `maskUrl` as a same-size PNG transparent where change should occur, and clarifies `prompt` is required for `fill`. `url`, `slot`, and `expandPercent` are left to the schema, so it is good but not fully compensating.

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

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

The description names a specific verb (edit part of a picture with AI) and enumerates the three concrete modes it supports — `fill`, `erase`, `expand` — each with a one-line semantic gloss. An agent can immediately distinguish this from uichemy_crop_image (a mechanical crop) and from uichemy_upload_image or uichemy_set_image_display 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?

It clearly states the conditions for each mode (paint something new, remove the area, extend outward) and the prerequisite plan, which is genuine when-to-use guidance. What it lacks is an explicit exclusion or routing statement — it says 'same write as uichemy_crop_image' but never tells the agent when to pick crop_image versus this tool.

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

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

The annotation readOnlyHint=false implies the call creates state, and the description's 'one-time' detail usefully explains why (a single-use token). It does not contradict the annotations. Still missing: auth requirements, whether the token is consumed on use, or what the caller receives.

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 short sentence with no filler, and the 'Internal' qualifier is front-loaded. It is efficient, though arguably too terse to be useful.

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 tool whose only parameter is undocumented and that has no output schema, the description should say what 'to' is and what comes back. Marking it internal helps scope expectations but does not fill the gaps an agent needs to invoke it correctly.

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

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

Schema description coverage is 0% for the required 'to' parameter, so the description carries the full burden — yet it never explains what 'to' means (presumably a redirect target) or its expected format. The one parameter an agent must supply is left completely opaque.

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

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

The description identifies a sign-in URL for the UiChemy panel and flags it as 'Internal', which separates it somewhat from siblings like uichemy_site_admin_login. However it is a noun phrase with no verb — it never says it generates, returns, or embeds the URL, so the actual operation is only inferrable.

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?

'Internal' is the only usage signal, and it is not actionable: it does not say when an agent should call this, nor how it differs from uichemy_site_admin_login or uichemy_open_preview. No prerequisites or exclusions 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 establish that this is a read-only, non-destructive, closed-world operation. The description adds meaningful behavioral detail beyond that: every supplied filter is ANDed, not ORed, and mixing conditions can bury the matches, which directly affects invocation strategy.

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

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

The description is front-loaded with the core action and then explains why the filters matter. The coin-flip framing is somewhat colorful but supports the usage rationale; overall it is efficient, though slightly longer than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 10 parameters and no output schema, so the description could do more to explain what is returned and how results are shaped. It covers the filtering model well enough, but leaves gaps around the required kind parameter and the result format.

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

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

Schema description coverage is high at 80%, so the detailed parameter meanings are mostly carried by the schema. The description still adds value by grouping the filter parameters conceptually and clarifying the AND matching rule, which is not captured by the individual schema 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?

The description states a specific verb and resource: finding layouts of one kind using attribute filters such as columns, background, media, and copy volume. It distinguishes the tool conceptually from a blind listing, but it does not explicitly name or contrast with sibling tools such as uichemy_list_templates or uichemy_search_layouts.

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 when to use the tool by warning that picking blindly among 849 generically named layouts is a coin flip. However, it does not explicitly say when to use this instead of alternatives like uichemy_list_templates or uichemy_search_layouts, nor does it state exclusions or prerequisites.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuine value the annotations cannot: the exact fields returned and the identifier semantics (post number rather than title), which materially affects downstream calls. It omits pagination or ordering 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?

Two tight sentences, front-loaded with the return payload, then the usage rule and the identifier caveat. Every clause earns its place, though the field enumeration is slightly list-like.

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-shape burden and does so competently (fields plus page mapping), and annotations cover safety. Only the meaning of projectId is left undocumented.

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

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

Schema coverage is 0%, but there is only one parameter (projectId) and the description never explains it, leaving a small gap. What it does contribute is identifier semantics for the returned 'post number', which is useful but not a substitute for documenting the actual input parameter; baseline 3 fits.

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

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

The description states a specific resource ('the posts this project has') and enumerates what each entry contains (title, byline, date, category, read time, landing page), so the agent knows exactly what comes back. It reads clearly as a list/read operation, though it never explicitly names a sibling like uichemy_add_blog or uichemy_remove_post to contrast against.

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

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

'Call it before changing a post' gives a concrete trigger for invoking the tool, and the note that 'the post number, not the title, is what identifies it' tells the agent how to act on the result. There is no explicit when-not-to-use or named alternative, 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 establish this is a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds behavioural context beyond that: colour decisions are role-based, the palette has named surfaces (bgLight1/bgLight2/bgDark1/bgDark2), and painting outside the palette mints a new swatch with a hard cap of five per project. It does not describe the shape of what is returned, so it is 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?

The read directive lands early ('Read it before choosing any colour'), which is good front-loading. However, the passage is a long, metaphor-heavy paragraph for a single-parameter getter, and lines like the closing 'looks right while the palette already had that exact surface under a name' are persuasive flourish rather than specification.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations about return values, the description is the only source for what a caller gets back. It explains the role vocabulary and the swatch-cap constraint, but never describes the returned structure or how colours are named, so an agent knows why to call it more than what it will receive.

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?

One parameter (projectId) at 0% schema description coverage, so the description must carry the semantics. It implies scoping via 'this project' and 'a project holds five', but never defines projectId, its format, or where a caller obtains it. It adds thematic context but only marginal clarification of the single parameter.

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 communicates a specific resource: the project's named colour vocabulary/roles rather than a hex list, and it situates that against siblings (uichemy_set_text_style's colorRole, template bgLight1/bgDark1 usage, section painting). The plain 'get the palette' statement is dressed in rhetoric, but an agent can still tell what it retrieves and how it differs from a raw colour list.

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 an explicit usage directive: 'Read it before choosing any colour.' It explains the consequence of skipping it (choosing between meaningless hexes) and references the role-based workflow that other tools rely on. It stops short of naming a competing sibling or a when-not-to-use case, so it is clear context rather than a full when/when-not map.

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, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: full URLs are returned, slots still holding template stock imagery are named, and orphaned URLs (tokens no section renders) are ordered last. This return-shape and ordering detail 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?

The core capability is front-loaded in the first sentence, which is efficient. The middle sentence is anecdotal backstory ('after uploading eighty pictures the only record of which token holds which was whatever the caller kept by hand') that restates the motivation at length without adding invocation guidance, so not every sentence 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?

With no output schema, the description must carry the return contract, and it does: URLs, owning sections, stock-template slots, and orphan ordering. For a single-parameter read-only tool with annotations covering safety, this is nearly sufficient; only the absence of any projectId note and a coarse sense of output shape keeps it from a 5.

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

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

The schema documents projectId by name only, with 0% description coverage, and the description never mentions it — so no compensation is provided for the gap. The parameter is self-evidently the project scope, which keeps this at a minimum-viable 3 rather than lower, but the description adds no semantics 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 resource and scope: every picture and clip in the project, with full URLs and the section each occupies. It also implicitly contrasts itself with the writer sibling uichemy_set_images ('writes and nothing read it back'), which helps an agent pick the read tool. It does not distinguish itself from other read siblings such as uichemy_list_section_backgrounds or uichemy_get_page_code, 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?

Usage is implied through motivation: the tool exists so callers can recover the token-to-URL mapping that uichemy_set_images does not return. There is no explicit 'use this when' statement, no exclusions, and no named alternative for related reads. The context is clear enough to infer intent, but nothing is spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: the taxonomy of slot types, that partner slots carry their own picture, and the failure mode (an unfilled slot shows another brand's mark, not emptiness). It doesn't describe return shape or pagination, but for a read tool 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?

Two sentences, front-loaded with the enumeration of what is returned, followed by the purpose. The closing flourish ("it looks like somebody else's brand") is colorful but does convey the failure mode, so it earns its place; the first sentence is dense but not padded.

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 describing what comes back, and it does so reasonably well by naming slot categories and the band/ownership attributes. It omits the projectId requirement and any sense of the returned structure's shape, leaving a small gap for an agent deciding how to consume the result.

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

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

Schema description coverage is 0% and the description never mentions projectId or what it scopes. The single parameter is self-explanatory by name and convention across sibling tools, which keeps this at minimum-viable rather than worse, but the description contributes nothing to parameter meaning.

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 concrete resource (logo slots) and enumerates exactly what is returned: site slots (navbar, footer, coming-soon/404) with their band, plus partner/client logo slots. It is clearly a read operation, implicitly the counterpart to uichemy_set_logo, but it never names that sibling or any other to differentiate itself 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?

"Use it to check that no slot is still showing the template's built-in mark or a placeholder from the image library" gives a clear, actionable trigger for calling the tool. It stops short of naming alternatives (e.g. set_logo for fixing a bad slot) or stating when not to use it.

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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by describing the return shape (filled vs empty slots, placeholder tokens, stock images) and enumerating what each slot record contains — useful since no output schema exists.

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 what is returned before the usage instruction. Dense but every clause carries information; the em-dash list of returned attributes earns its space rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly carries the burden of explaining what comes back, and does so thoroughly. The main gap is that half the parameters are undocumented, but for a read-only two-parameter lookup with annotations covering safety, the description 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?

The description never mentions pageName or projectId. Schema coverage is only 50% (pageName has a terse 'As uichemy_get_project listed it.' while projectId has none), so the description should compensate but does not — an agent gets no help on parameter format or provenance.

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

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

The description names a specific resource (one page's sections and every slot within them) and enumerates the fields returned — token, slot purpose, character cap, current content — which is far more specific than a tautology. It stops short of explicitly differentiating itself from near-siblings like uichemy_describe_sections, uichemy_get_text, or uichemy_template_slots.

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

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

Gives concrete when-to-use guidance: locate the slot token a piece of text lives in before editing it, and inspect slots still showing their placeholder token or the template's stock picture. It implies the follow-up session (uichemy_set_text) but does not name an alternative tool or state when not to use this one.

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 read-only/non-destructive, and the description adds substantial behavior: it returns every component file plus an App.jsx and a stylesheet-download command, unfilled slots fall back to template sample copy, files are meant to be used as-is with styling coming from the kit, and photos are searched server-side, so no separate image search is 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 core action and routed alternatives early, and dense with useful detail. Slight redundancy in the closing 'copy and image urls can be changed afterwards by editing the files' which restates the earlier 'rewrite the copy by editing the files'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description fully covers the return shape (component files, App.jsx, stylesheet command, slot metadata per file) and default behaviors, which is everything an agent needs to invoke and consume the result.

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

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

Schema coverage is 100%, so baseline is 3; the description nonetheless adds real meaning: `text` is slot-token→copy, `photos` is per-section queries with a page-wide default, and palette/fonts are page-level. It clarifies the relationship between the per-section photos and the top-level photos default, which the schema only hints at.

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 (builds a page of React app code from UiChemy sections) and explicitly contrasts with uichemy_create_project for projects and implies get_template_code territory. An agent can distinguish it from siblings 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?

Explicitly says when to use this tool vs uichemy_create_project, and names the discovery path (uichemy_find_templates / uichemy_search_layouts to pick layouts, uichemy_list_templates to enumerate a kind's layouts). No inference required.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results mirror the editor's Page Settings screen, and 'Defaults are named as defaults' tells the agent how unset values will be represented in the response.

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 and resource first, followed by a useful field enumeration. The long em-dash list is dense but every element names a distinct setting category, so it earns its length; it stops just short of being over-stuffed.

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 heavy lifting by enumerating the returned settings fields, which is exactly what an agent needs to plan a read. The one real omission is any semantic guidance on projectId, the required 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 coverage is 50%: pageName is documented ('One page; omit for all.') but projectId has no description. The description's phrase 'each page's' reinforces the all-pages default but adds nothing about projectId, so it neither compensates for the gap nor falls below the baseline for partially-covered schemas.

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 (read) and resource (each page's Settings) and enumerates the exact fields returned (slug, meta title/description, social image, canonical URL, language, indexing, AI crawlers, custom code). This separates it cleanly from siblings like uichemy_get_page (page content), uichemy_get_page_code, and uichemy_set_page_settings (the write counterpart).

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: 'Read each page's Settings' suggests inspection, and the schema's 'omit for all' hints at the all-pages case. There is no explicit statement of when to prefer this over uichemy_get_page or uichemy_set_page_settings, nor any 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: it is a prerequisite read for mutation tools, and imported projects are governed by different rules than generated ones – useful behavioral information not derivable 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 scope of what is inspected. The second sentence is information-dense about sequencing and import rules. Slightly long, but each clause 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?

With no output schema, the description correctly carries the burden of listing what is returned, and it does so thoroughly. Combined with annotations covering the read-only nature and the usage note that it precedes mutations, an agent has enough to call it correctly; only an explicit alternative path 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 single projectId parameter is documented in the schema ('From uichemy_list_projects, or the id in the editor url'). The description adds nothing 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?

The description gives a specific verb ('Look INSIDE') and resource (a UiChemy project) and enumerates exactly what comes back: pages in order, sections, palette, fonts, button/card designs, import provenance. That scope implicitly separates it from narrower siblings like uichemy_get_page or uichemy_get_style_kit, but no alternative is named explicitly, 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?

Explicit when-to-use: 'Call this before changing anything', with a stated rationale (the design tools need current values to describe replacements). It also flags a conditional behavior (imported vs generated projects follow different rules). What it lacks is a named alternative for the case where only a slice of project data is 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 establish readOnly/non-destructive/closed-world, so the bar is lower, and the description still adds real behavior: output is a download command rather than raw CSS by default, the file is self-contained and works with Tailwind v4, v3, or none, and coverage is bounded by the layouts passed. It does not discuss failure modes or what happens if an unknown layout kind is supplied.

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 what is returned, then routing, then parameter guidance. Four dense sentences with parenthetical asides; nothing is filler, though the parenthetical and the inline sentence could be tightened.

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 work of saying what comes back (a download command, or CSS itself when inline is set). Combined with the coverage caveat and framework compatibility, an agent has enough to call it correctly; error behavior and the layout kind vocabulary remain 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 coverage is 75% and already documents fonts/palette/inline/layouts shapes, so the baseline is 3; the description adds non-obvious semantics — that palette and fonts brand every section at once, and that layouts must enumerate the full set for the kit to cover it. It does not clarify the hex format of palette beyond the schema's #RRGGBB notes or the layout `kind` vocabulary.

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+resource (produce the stylesheet / CSS file the library sections need for a user's React app) and explicitly distinguishes itself from the sibling that overlaps: 'uichemy_get_page_code already includes it.' An agent can route between this and get_page_code 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?

Explicit when-not (get_page_code already contains the stylesheet), explicit completeness rule ('pass every layout the app uses'), explicit re-invocation trigger ('when a section is added, run it again with the full list'), and an explicit condition for the alternative output mode ('Set inline only when the caller cannot run a command').

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

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

Annotations only declare the safe-read profile; the description adds substantial behavior beyond that: the file depends only on React, colours are optional props defaulting to the style kit, the stylesheet prerequisite, the files are meant to be used as returned, and photos are searched server-side from free-licence stock so no separate image search is needed. It also notes copy and image URLs are editable afterwards. This is exactly the added context the annotations cannot 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-loaded with the purpose and then dense but mostly load-bearing detail. A couple of statements overlap (the stylesheet prerequisite and 'styling comes from the kit'), and the run-on middle sentences could be tightened, but nothing is 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 7-parameter code-generation tool with no output schema, the description covers the key unknowns: prerequisites, image-resolution behavior, and editability of the result. It could say more about what is actually returned (single file vs files, naming, where the componentName lands), which is the one remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: text keys are slot tokens cross-referenced to uichemy_template_slots, photos are natural-language queries resolved server-side against free-licence stock (one query per picture, in order), while images are direct slot→url overrides. The photos-vs-images distinction and server-side search behavior are not obvious from the schema alone.

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

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

Opens with a specific verb+resource+scope: 'One UiChemy library section as a standalone React + Tailwind component for the user's own React app.' It explicitly contrasts itself with uichemy_get_page_code ('returns a whole page in one call'), so an agent can route between the two 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 real routing context: use this for one section, get_page_code for a whole page; pass text via uichemy_template_slots tokens; the output needs the stylesheet from uichemy_get_style_kit. It stops short of an explicit 'do not use this when…' rule, but the when-to-use signals are clear and actionable.

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 a safe read (readOnlyHint=true, destructiveHint=false), but the description adds real behavioral context beyond them: values are exact/unclipped, and page reads are capped with the cap signalled in the response. The silent-truncation risk of the sibling is a useful disclosure. It does not describe the return shape in detail, 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?

Front-loads the key contrast (full copy vs get_page's clipping) in the first clause, and the cap disclosure earns its sentence. The middle em-dash clause is slightly verbose but not wasteful.

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 only read-only annotations, the description carries the behavioral burden well: it covers the clipping distinction, the two request modes, and page-read capping. It stops short of describing the response structure or how capping is reported, but is complete enough to invoke 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 67%, with projectId undocumented in both schema and description. The description compensates by clarifying the tokens-vs-pageName modes and implying they are alternatives, which is more than the schema states. projectId remains unexplained, keeping it below 5.

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

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

States a specific verb+resource (reads the FULL, unclipped copy in named slots) and explicitly distinguishes itself from uichemy_get_page, which clips at 80 characters. An agent can tell the two apart 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 the two selection modes directly ('Ask for the tokens you need, or name a page to read everything on it') and names the alternative with the condition that rules it out (get_page's 80-char clipping makes it useless for paragraph reads). Nothing 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 destructiveHint=true, so the bar is lower. The description adds real value by spelling out exactly what gets overwritten (copy, pictures, clips, button/badge choices in any section sharing the layout) and that background is reported rather than painted—detail absent from the annotations.

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

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

The OVERWRITES warning is correctly front-loaded, but the middle sentence is a long run-on that buries the delegation to uichemy_add_section. It earns its length on behavioral content but could be tighter and clearer.

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 destructive, no-output-schema mutation, the definition covers overwrite scope, the add_section routing, and the separate background step. The main gap is parameter documentation for projectId/pageName, but overall an agent has what it needs.

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

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

Schema coverage is 50%; the schema documents index and points savedId to uichemy_list_saved_sections, while pageName and projectId are undocumented. The description adds no parameter-level detail beyond implying the saved/layout relationship, so the baseline of 3 fits.

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 action (put a saved section into a page) and explicitly contrasts it with uichemy_add_section, the sibling it delegates to. It clearly distinguishes the insert-saved operation from plain section-adding, though the phrasing is circuitous.

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 routes the agent explicitly: insertion happens through uichemy_add_section, and background must be set separately with uichemy_set_section_background. These are named alternatives with conditions, though it never states when NOT to use this versus save_section/duplicate_section.

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 and openWorldHint=false, so safety and account-scoping are covered. The description adds that only exported-marked projects are returned, which is useful scoping context, but says nothing about ordering, completeness, or result shape.

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 short noun phrase with no filler, front-loading the filter (exported) and the notable return field (builder). It is a fragment rather than a sentence, which is stylistically inconsistent but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must carry the return picture, and it does mention both the entities and the builder attribute. It stops short of anything about result size or ordering, but for a zero-argument listing tool that 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?

The tool takes zero parameters, so the parameter-semantics baseline of 4 applies; there is nothing for the description to compensate for and no misleading parameter claims.

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 resource (projects marked exported) and the payload detail (the builder each went to), which distinguishes it implicitly from uichemy_list_projects by the exported filter. It never names the sibling it contrasts with, so differentiation requires the agent to infer 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?

Use is implied by the description — retrieve exported projects — but there is no explicit when-to-use, no mention of the related uichemy_mark_exported action that creates these records, and no statement of alternatives such as uichemy_list_projects.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful interpretive context about the two key schemes, but says nothing about result shape or pagination beyond that.

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 first sentence is front-loaded and clear. The second is discursive, ending on a convoluted phrase ('stops a change from fighting an existing one') where a plain 'prevents conflicting overrides' would do.

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 sketches what comes back (icons plus their keys under two schemes), but omits the required projectId entirely and gives no sense of result structure. Adequate but with clear gaps.

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

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

There is one parameter and schema description coverage is 0%, so the description carries the full burden — yet it never mentions projectId or its format, only discussing the output keys. It does not compensate for the coverage gap on inputs.

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

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

The description names a specific resource and scope: the icons this project has had replaced, with their override keys. It is identifiable as a read/list operation, though the verb is only implied and it never names the close sibling list_icons or clear_icon_override to sharpen the boundary.

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 conceptual context — that a LABEL and a POSITIONAL id are the two key schemes and that recognizing them prevents conflicting changes — which implies you call this before mutating overrides. But it never states when to use this versus list_icons or how it pairs with clear_icon_override/set_icon.

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 safety (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description still adds real behavior: slot labels are authored in templates and readable without a rendered page, and `instances` counts how many icons share a label so a loop-drawn row is replaced as a unit. That is genuine context an agent could not infer from the annotations.

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

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

The core purpose is front-loaded, but the middle is a rambling anecdote ('On a project where none have been it answers...') that restates the overrides distinction at length. The useful payload — slot label readability and `instances` semantics — is buried at the end rather than stated crisply up front.

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 meaning, and it does explain what a result row conveys (slot label plus instance count). It is reasonably complete for a read-only listing tool, though it omits pagination or ordering behavior.

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% — pageName is documented in the schema as 'One page. Omitted = every page.' while projectId is undocumented. The description says nothing about how to scope by page or what projectId must be, and instead spends its detail on the returned `instances` field, 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?

The description states a specific verb and resource — listing every icon SLOT rendered by pages, including unset ones — and immediately distinguishes that from uichemy_list_icon_overrides, which lists only replaced icons. An agent can pick between the two siblings 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?

It names the alternative (uichemy_list_icon_overrides) and the exact condition that selects this tool instead: when no icons have been replaced and there is no id to write to. It stops short of explicit when-not guidance, but the conditional routing is unusually 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 the safety profile (readOnly, non-destructive, not open-world), so the description's job is to add context — and it does: it discloses that some destinations are baked into the LAYOUT (phone, email, map), carry no key, and cannot be changed from this tool. That is real behavioral value beyond the structured hints, though it says nothing about pagination or return volume.

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 what is returned and folds the constraint into an em-dash aside. Dense but every clause earns its place; slightly run-on but not padded.

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 compensates by enumerating what each returned link contains (key, current target, layout-baked destination). The main shortfall is the unexplained required projectId, which leaves the calling contract incomplete.

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

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

Schema description coverage is 0% for both parameters, so the description carries the full burden, yet it never mentions projectId or pageName. 'A page's sections' loosely gestures at pageName, but projectId — the required parameter — is entirely unexplained.

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+resource (list links on a page's sections), scopes it to buttons and text links, and explicitly ties it to the sibling uichemy_set_link by naming the key that tool consumes. An agent can distinguish this from other list_* tools 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 reference to 'the key uichemy_set_link takes' plus 'cannot be changed from here' implicitly frames the workflow (read here, mutate via set_link) and sets a boundary on what this tool can alter. It does not, however, state an explicit when-to-use-vs-alternative condition beyond that implicit pairing.

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, and openWorldHint=false, so safety is covered. The description adds meaningful non-schema behavior: results are account-scoped and returned newest-first, which tells the agent what ordering to expect. It stops short of describing truncation/pagination semantics when the limit cap is hit.

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 most decision-relevant fact (what the list is) is front-loaded before the usage tip. 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 simple one-parameter, no-output-schema read tool with full annotation coverage, the description is nearly sufficient — it conveys scope, ordering, and the payoff (project ids). It could note whether the list may be truncated, but nothing essential for calling 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?

With a single parameter at 100% schema description coverage ('How many to return. Default 20.'), the schema already carries the semantics. The description's 'newest first' adds ordering context that matters for interpreting the limit, but no additional syntax or edge-case detail. 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 pair ('The UiChemy projects this account can open'), plus scope ('this account') and ordering ('newest first'). An agent can immediately distinguish this enumeration tool from get_project (single), create_project, and delete_project 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 an explicit when-to-use: 'Use it to find the project id another tool needs,' and an anti-pattern to avoid ('rather than asking the user to copy one out of a url'). It does not name a specific sibling alternative (e.g. open_projects) as the contrast case, so it stops just short of a full when/when-not statement.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, so the safety profile is covered structurally. The description adds useful behavior — that results are account-scoped and sorted newest-first — but says nothing about pagination, result size, or what a 'section' record contains.

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 tight sentence with zero waste; the scoping (this account) and ordering (newest first) are front-loaded and immediately actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with annotations covering safety and a fully described filter parameter, the definition is adequate. It is missing return-shape and pagination context, but with no output schema declared this is a minor gap rather than a blocking one.

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

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

With a single optional parameter and 100% schema description coverage ('Only this section kind — hero, pricing, faq…'), the schema already carries the parameter meaning. The description adds nothing beyond what the schema provides, 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 (list) and resource (saved sections for this account), plus ordering ('newest first') and provenance ('saved with uichemy_save_section'). This distinguishes it from siblings like uichemy_save_section and uichemy_insert_saved_section, though it does not explicitly name the alternatives.

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 provenance phrase 'saved with uichemy_save_section' implies the natural workflow (save first, then list/insert), which gives implied usage context. However, there is no explicit when-to-use guidance and no routing between this and similar retrieval tools like uichemy_describe_sections or uichemy_list_section_kinds.

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, openWorldHint false, and destructiveHint false. The description adds return content—every section kind with layout counts—but omits output format or pagination details.

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 resource and examples, zero waste. The second sentence efficiently communicates the primary usage context.

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 no-param read-only catalog with no output schema, the description provides the return content and usage context, which is sufficient. No missing information that would block correct invocation.

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 baseline 4. No parameter semantics are 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 (list) and resource (section kinds) and enumerates examples like hero, features, pricing. Clearly distinguishes this catalog from site-specific tools by contrasting library vs uploaded site.

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

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

Explicitly says to start here when building from the library and not from an uploaded site, giving a clear when and when-not. It does not name the alternative tools (e.g., describe_sections or list_saved_sections) that cover other scenarios.

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, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the results are scoped to 'this account' and include the remaining publish allowance, which is useful behavioral detail. It stops short of describing ordering, pagination, or error conditions.

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

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

A single compact sentence that front-loads the main return (the sites) before the secondary one (the quota). Slightly informal phrasing ('how many more it may have') costs a little precision but wastes no space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns, and it does so at a high level: the published site list plus the remaining allowance. For a zero-parameter read-only tool this is nearly sufficient, though the exact shape of each site entry and the quota value is left unspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. Schema coverage is 100% and the empty input schema is consistent with a parameterless list call.

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

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

The description states a specific resource (every site this account has published on uichemysites.com) and adds a scope detail (remaining publish quota). It is clear what the tool returns, but it never explicitly distinguishes itself from near-siblings like uichemy_list_projects or uichemy_list_exported, leaving the agent to infer the site-vs-project boundary.

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 or when-not-to-use guidance and no alternative named. The agent gets no help deciding between this and uichemy_list_projects or uichemy_publish_status.

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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds useful workflow context (the chained call to uichemy_template_slots) but says nothing about return shape, ordering, or whether thumbnails affect cost/latency.

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

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

Two short sentences, zero waste, with the resource identified first and the follow-up action second. Nothing could be removed without losing guidance.

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 convey the return concept (layout ids) and the follow-up tool, and the params are fully documented in schema. It omits any note about what a 'layout id' looks like or how many results to expect, but that is a minor gap for a simple list 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% and both params are documented in the schema (kind sourced from section kinds, withThumbnails adding a preview url). The description adds no syntax, format, or default information beyond what the schema already supplies, so 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 resource (layout ids) scoped to one section kind, and the parameter description ties 'kind' to uichemy_list_section_kinds. It does not distinguish itself from near-siblings like uichemy_find_templates or uichemy_search_layouts, which also surface layouts, so an agent must infer the difference.

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 next step: pick a layout id and call uichemy_template_slots to learn its copy requirements. The 'kind' param description implies this runs after uichemy_list_section_kinds. No when-not-to-use or alternative is named, 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?

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered without the description. The description adds the keying scheme (`text_*` slot) and the panel provenance (Text panel controls), which is genuine context. It says nothing about return shape, emptiness when no styles are set, or ordering, so it adds moderate but not rich behavioral detail.

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. The resource and its keying are front-loaded, and the disambiguating clause about the global type scale is placed last where it does the most routing work.

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 has to carry the return-value burden, and it does describe the shape of a style entry and how entries are keyed. What is missing — whether unset slots are omitted, or how the global type scale interacts — is minor for a read-only listing tool.

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

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

Schema description coverage is 0% for the single projectId parameter, so the schema contributes nothing. The description only implies the scope via 'this project', never naming or explaining projectId. For a lone, self-evident identifier this is close to adequate, but the description does not compensate for the schema gap.

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

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

The description names the resource precisely — per-element text styles set on this project — and enumerates the fields returned (alignment, size, colour role, semantic tag). It also distinguishes itself from the global type scale, which is the closest sibling concept. It stops short of a crisp verb-first statement of what the call does, but an agent can tell what it returns.

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 closing clause 'not the global type scale' gives one negative boundary, which is useful routing information toward set_type_scale / get_style_kit. However, there is no explicit when-to-use trigger, no mention of the sibling uichemy_get_text or uichemy_clear_text_style / uichemy_set_text_style relationship. 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real domain context beyond that: variants are whole palettes 'kept alongside the applied one', which tells the agent that listing does not disturb the currently applied palette and that variants are parallel alternatives rather than sequential states.

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 front-loaded sentence with no boilerplate; the em-dash apposition and ellipsis convey the sidebar naming convention compactly. Slightly conversational, but nothing is 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?

No output schema exists, and the description does enough to let an agent interpret results: it explains that variants are named 'Variant 1, Variant 2 …' in the sidebar and that each is a full palette. It is complete for a simple single-parameter read, though it never says what fields come back (ids vs names).

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

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

There is only one parameter (projectId) and schema description coverage is 0%. The phrase 'on this project' implies projectId scopes the listing, but no format, ID source, or lookup hint is given. Baseline 3 for a single-parameter tool whose schema is undocumented in both places.

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

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

The description states a specific resource (the colour variants / whole palettes on a project) and clarifies what a variant actually is, so an agent knows this is a read of existing alternatives rather than palettes themselves. The verb is only implied ('this is how you see what alternatives a project already has'), and no sibling is named explicitly, 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?

'...before adding another' gives a clear triggering context: check existing variants prior to calling create_variant. There is no exclusion list or explicit naming of the alternative tool, but the when-to-use is unambiguous for this tool's main decision point.

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=false and destructiveHint=false, so the mutation/safety profile is partly covered. The description adds genuinely useful context beyond that: the payload is not generated here and the plugin pulls it during sync, which prevents the agent from assuming a file artifact is produced.

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 first sentence is well front-loaded and informative. However, the final clause ('so say that plainly rather than implying a file was produced') is meta-instruction about how to phrase things rather than tool behavior, muddying an otherwise tight definition.

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 low-complexity two-parameter mutating tool with no output schema, the description conveys the essential behavioral nuance (state change, no payload generation, plugin reads it). The only real gap is the undocumented builder/projectId parameters.

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

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

Schema description coverage is 0%, so the description carries full burden for two parameters. It explains neither projectId nor the builder enum (elementor/gutenberg), so the agent gets no guidance on what builder selects or how the mark is scoped.

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 ('mark a project as exported') and clarifies what the action does ('puts it in the Exported list and what the WordPress plugin reads'). The negative clause ('does NOT generate the Elementor or Gutenberg payload') sharpens the boundary, though no sibling tool is named to route against.

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 the context in which the state matters (plugin sync reads it), but never states when to call this versus alternatives like sync_builders or publish_site, nor any prerequisites or ordering. Usage must be inferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real context beyond that by enumerating the three surfaces the project can open in and by disclosing the no-projectId fallback behavior. It omits any note about what happens if the projectId is invalid or whether the open is synchronous.

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 primary action and destinations, then the trigger condition, then the edge-case fallback. No filler or repetition of the title.

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 navigation tool with full schema coverage and explicit annotations, the description supplies the destination semantics and the missing-parameter behavior an agent needs. The only real gap is disambiguation from the sibling uichemy_open_projects, which has overlapping dashboard-opening behavior.

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 (view, pageName, projectId) are already documented in the schema, including enum meanings and defaults. The description only echoes the 'preview' value and adds no syntax or constraint beyond what the schema provides — 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?

Specific verb+resource ('Open a UiChemy project') with three explicit destinations: embedded ChatGPT view, the canvas editor, and a full-page single-page preview. It stops short of naming its near-twin sibling uichemy_open_projects, so the agent must infer which of the two 'open' tools to pick when no projectId is given.

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

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

'Call it after changing a project so the user sees the result' gives a clear triggering condition, and the no-projectId dashboard fallback is stated explicitly. It does not, however, say when to prefer uichemy_open_projects over this tool, which is the obvious alternative given the sibling list.

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, and openWorldHint=false, so the safety profile is covered. The description adds that the dashboard opens inside ChatGPT, but does not mention auth requirements, side effects, or return behavior beyond that.

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

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

The description is two tight sentences with no wasted language, and the core action is front-loaded. It is appropriately sized for a simple zero-parameter navigation tool.

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 zero parameters, no output schema, and annotations covering safety, the description is largely complete: it says what opens, where it opens, and when to use it. Stronger sibling differentiation would make it fully complete in this crowded toolset.

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

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

The tool has zero parameters and an empty input schema, so there are no parameter meanings for the description to clarify. This matches the baseline of 4 for parameterless tools.

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: "Open the UiChemy dashboard (the user's projects) inside ChatGPT." It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as uichemy_list_projects or uichemy_open_site_admin.

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 clear usage guidance: "Use when the user wants to see, pick or open one of their UiChemy sites, or just open UiChemy." It lacks explicit when-not guidance or named alternatives among the many sibling tools.

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

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

Annotations only declare the generic non-read-only, non-destructive, closed-world profile. The description adds the crucial operational traits: the return value is a one-time sign-in link, it works exactly once, it expires roughly a minute after the call, and a fresh call is needed after expiry. It also explains the underlying reason (UiChemy owns the admin account, the user has no password), which prevents a wrong recovery path.

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 purpose first, then trigger, then return behavior, then fallback warning and alternative. Every sentence carries load, though the one-time/expiry/anti-/wp-admin material runs a bit long and could be tightened 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?

There is no output schema, so the description correctly explains the return value (a one-time link) and its lifecycle. Combined with the trigger conditions, the alternative tool, and the credential caveat, an agent has everything needed to call and relay the result 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?

One required parameter (projectId) with 0% schema description coverage. The description implies the site is scoped to 'a project's hosted site', which loosely ties projectId to a project, but gives no format, source, or lookup hint for the ID. It partially compensates but leaves the only parameter under-specified.

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+destination: signing the user into the WordPress wp-admin dashboard of a project's hosted site on uichemysites.com. It is immediately distinguishable from the sibling uichemy_site_admin_login, which it explicitly names and contrasts.

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 ('whenever the user asks to open, log in to, or get into the site's admin, dashboard or backend') plus an explicit anti-pattern ('Never send the user to /wp-admin or wp-login.php') and the alternative for a different need (uichemy_site_admin_login for durable credentials). Nothing 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?

Far exceeds the annotations (which only declare non-readOnly, openWorld, destructive). The description discloses public exposure, idempotent re-publish semantics (same address, pages replaced), a 24-hour Temporary lifecycle with plan quotas, that only generated pages are published, and that the call is async and returns immediately.

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

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

Front-loads the core purpose and consequence before the operational caveats, and nearly every sentence carries distinct information. It is dense and long, but largely justified by the tool's complexity; only minor tightening is possible.

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 explains the async return ('returns at once with the address') and the follow-up status tool. It covers lifecycle, quota, and access rules so an agent can call and explain the result correctly; the only omission is the required projectId's own semantics.

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

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

Schema coverage is 67%: 'pages' and 'address' are well documented in the schema (address already notes it is ignored on updates). The description adds context linking address to the first-publish flow, but the required 'projectId' is undocumented in both schema and description. Baseline 3 is appropriate here.

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 ('Put a project ONLINE as a real WordPress site at https://<address>.uichemysites.com') and names the intermediary (UiChemy WordPress plugin). It is clearly distinguishable from siblings like uichemy_publish_status, uichemy_unpublish_site, and uichemy_open_site_admin, which it explicitly routes to.

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 when: 'only call it when the user asks to publish, go live, or put the site online.' It also names alternatives for adjacent needs (uichemy_publish_status for progress, uichemy_open_site_admin for admin access) and states a scope limit (WordPress only).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral value beyond that: it discloses the fallback behavior when publishId is omitted and enumerates the possible states the publish can be in (live, setting up, or failed). It does not cover permissions or latency, but the added context is substantive.

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

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

A single tightly packed sentence that front-loads the outcome and then lists the returned fields. There is no filler, though the colon-heavy structure is a touch dense for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the return-value burden and does so by naming the fields an agent gets back. Combined with read-only annotations and the fallback rule, an agent has enough to call and interpret this tool correctly; only projectId semantics are thin.

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

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

Schema coverage is 50%. The schema documents publishId as coming from uichemy_publish_site, and the description reinforces its optional/conditional role. However, projectId is left completely undocumented in both the schema and the description, so the description does not fully compensate for the coverage gap. Baseline 3 fits.

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

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

The description states a specific resource (a publish / the project's hosted site) and enumerates the status fields returned (address, live/setting-up/failed, last publish time), which lets an agent recognize this as a status-query tool. It does not name sibling tools such as uichemy_publish_site or uichemy_list_sites to sharpen the boundary, and the phrasing 'Where a publish is up to' is slightly indirect.

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 one useful conditional: if no publishId is supplied, the tool reports the project's hosted site instead of a specific publish. That implies usage but there is no explicit when-to-use vs alternatives (e.g., versus uichemy_publish_site to start a publish, or uichemy_list_sites), and no exclusions or prerequisites.

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

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

Annotations already declare destructiveHint=true, but the description goes well beyond that: it enumerates exactly what is destroyed, explains why slot tokens on other pages survive the deletion, states the home-page protection rule, and notes that a report of what was deleted is returned because the action is irreversible. This is unusually rich behavioral disclosure for a destructive operation.

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 destructive scope is front-loaded, which is good, but the middle sentence ('Copy a section on ANOTHER page still renders is kept...') is syntactically tangled and hard to parse, and the closing clause about the caller being able to report the deletion is more editorial than 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?

For a destructive tool with no output schema, the description covers destruction scope, the home-page restriction, cross-page side effects, and the fact that a deletion report is produced. The only real gap is parameter identity (which project, which page), which the schema does not fill either.

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

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

Schema description coverage is 0% and the description never mentions projectId or pageName, their formats, or how a page is identified. It only implies 'page' generically, so it does not compensate for the undocumented parameters even though the names are fairly self-explanatory.

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 precise verb and resource ('Delete a page') and immediately scopes what 'page' includes: sections, layouts, backgrounds, overlays, padding, copy and pictures. This clearly separates it from siblings like uichemy_remove_section, uichemy_duplicate_page and uichemy_delete_project 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 a real usage boundary — the home page cannot be removed because it is the root of every other page — which tells the agent when this call will fail. It does not name alternative tools (e.g. remove_section for partial teardown), so it stops short of full when/when-not/alternatives 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 confirm destructiveHint=true, and the description goes well beyond them: posts are renumbered down, listing cards move, a surplus article page is deleted with the post unless keepPages says otherwise, and a numbering hole leaves an empty card. This covers exactly the side effects an agent must anticipate before a destructive call.

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

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

The action is front-loaded and every sentence carries rationale, but the historical aside ('Before this the only way... three deletions cost two extra pages') is longer than strictly needed to guide invocation.

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 three simple params, the description supplies ample behavioral context for a destructive operation. It omits return confirmation and any permission requirements, but nothing else 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 67%; postNumber's 1-based convention is documented in the schema, and the description adds the behavioral meaning of keepPages ('The surplus article page goes with the post, unless keepPages says otherwise'). projectId remains undocumented in both places, a minor 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?

Opens with a specific verb+resource: 'Delete one blog post.' It immediately distinguishes itself from siblings like uichemy_remove_page by naming the exact entity and the numbering mechanism involved.

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 explains why this tool exists versus the prior approach ('the only way to remove a post was to overwrite the whole list positionally'), giving clear context for when to reach for it. It does not, however, name a sibling alternative or state preconditions explicitly.

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 destructive=true/readOnly=false, and the description goes well beyond them: it explains index reflow, variant-key rebuilding, why stale keys matter, the cascade of owned assets (background, overlay, padding, slot content), the sharing exception when another section renders the layout, and that dropped content is reported.

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 action is front-loaded in the first short sentence, and the following sentences each add distinct destructive-behavior detail. The enumeration of owned assets is slightly padded but each clause carries real meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, no-output-schema tool, the description covers what is destroyed, what is preserved via sharing, the one hard prohibition, and that dropped content is reported. Only the exact returned payload and any authorization requirements are left 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 coverage is only 33% — only 'index' is documented as 1-based, while projectId and pageName have no descriptions. The description never mentions any parameter or clarifies how the index relates to the resulting reflow, 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?

The description opens with a concrete verb+resource: 'Take a section off a page.' The resource noun ('section') separates it from nearby siblings like remove_page and remove_post, but it never explicitly contrasts itself with replace_section or duplicate_section, so differentiation is left to inference.

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 a clear when-not rule ('the last Post Featured Area or Post Content ... cannot be removed'), which prevents a class of invalid calls. It does not point to alternative tools (e.g. replace_section) when removal is the wrong operation, but the context is otherwise clear.

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 and readOnlyHint=false, so the safety profile is known; the description goes further by disclosing exactly what is destroyed — both the section's worn background and the override that survives a style recompute — and that orphan entries are unreachable by any page tool. It does not discuss error behavior or permissions, but the added destruction semantics are substantive.

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 primary action and both modes are front-loaded, and most sentences carry real content. The narrative aside about deletes 'taking their own state with them' is slightly chatty, but overall the length is justified for a tool with two distinct behaviours.

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 still covers both modes, the origin of `sectionKey`, and the derived swatch-strip behaviour that follows removal. It omits edge cases such as an invalid sectionKey, whether both parameters can be supplied together, and permission requirements for a destructive operation.

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

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

Schema coverage is 67% and the description compensates by explaining what `orphans: true` actually clears (background, overlay and padding, beyond the schema's terse 'every entry'), and by identifying `sectionKey` as a value returned by uichemy_list_section_backgrounds. The two modes are implicitly presented as alternatives, though the description never states whether they can be combined.

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 states a specific verb and resource in two modes: unpaint a section's background, or clear backgrounds orphaned by deleted sections. It is clearly distinguishable from siblings like uichemy_set_section_background and uichemy_remove_swatch, which do different things.

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

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

It gives explicit conditions for each mode: pass `sectionKey` to unpaint one section, or `orphans: true` to drop every orphaned entry. It also routes the agent to uichemy_list_section_backgrounds for keys and uichemy_validate for discovering orphan-section-key entries, so the when and the source of inputs are both covered.

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 and readOnlyHint=false, but the description adds real value beyond them: it discloses the cascade side effect (every section painted that colour is unpainted back to its section style's colour) and that the strip is rederived. That is exactly the behavioral risk an agent needs. It omits reversibility and permission requirements.

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?

Compact and front-loaded — the action and target lead, with side effects trailing. Dense but every clause carries information; no 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?

No output schema exists, so the description must carry the result semantics, and it does explain the cascade and that the strip is rederived. For a two-parameter destructive mutation the main behavioral hazard is covered, though projectId's role and failure behavior are left unexplained.

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 only 50%: hex is documented in the schema and projectId is undocumented in both places. The description reinforces the 'saved section colour' concept but adds no format, scope, or meaning beyond what the schema already states, and does nothing to fill the projectId 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 (remove) and resource (one saved section colour from the swatch strip) and grounds it in the UI (the background picker's remove button). It is clear what it does, though it never explicitly distinguishes itself from the closely-named sibling uichemy_remove_section_background.

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 frames the tool as the picker's remove button but gives no when-to-use vs. when-not guidance and does not mention the ambiguous alternative uichemy_remove_section_background. Usage is only inferable from the UI analogy.

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 and destructiveHint=false, so the agent already knows this is a non-destructive write. The description goes well beyond that, disclosing that the page id and section ids are preserved, that layouts/backgrounds/copy are keyed against those ids (so the rename is safe), and that variant aliases embedding the old name are rebuilt. That side-effect disclosure is genuinely valuable context.

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

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

Three short sentences, front-loaded with the core action, then the safety guarantee and the one consequential side effect. Every sentence carries weight; nothing is 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?

Behaviorally the definition is strong: it covers what changes, what is preserved, and the alias-rebuild side effect, all without an output schema to lean on. It falls short only on input semantics, leaving projectId and the exact role of pageName/newName unexplained for a 0%-coverage schema.

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

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

Schema description coverage is 0% for all three required parameters (projectId, pageName, newName). The description only obliquely conveys that one input is the current page name and another is the new name ('Change what a page is called'); it never addresses projectId, and it does not tie any input to its parameter name or format. Compensation for the coverage gap is partial at best.

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 ('Change what a page is called' = rename a page) in plain language. It is immediately distinguishable from siblings like duplicate_page, remove_page, and reorder_pages. No ambiguity about what the operation 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?

Usage is implied by the operation itself (rename an existing page), and the safety framing hints that this is the right call when only the display name changes. However, it never explicitly says when to use this versus alternatives such as set_page_settings or duplicate_page, nor names any prerequisite.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, openWorld=false), and the description goes beyond that by explaining the downstream effects: the Design canvas renders one card per page in this order while the Site map keeps category containers fixed and reorders only within them. That is genuinely useful behavioral context. It stops short of stating permissions, error behavior, or what happens to pages omitted from the list.

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 imperative, then constraints, then effects. Four sentences with no filler, though the Design canvas / Site map explanation is slightly longer than strictly needed to invoke the tool correctly.

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-parameter mutation with no output schema, the description covers the critical semantics: input shape, the home-page invariant, and how the order manifests in the UI. It omits edge-case behavior (invalid/duplicate/missing page names, effect on published sites), which is the remaining gap.

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

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

Schema coverage is only 50% (projectId is undocumented), so the description must carry weight for 'order' — and it does, specifying completeness ('every page name exactly once'), ordering semantics, and the home-page-first invariant that the schema's one-line description only gestures at. It adds real meaning beyond the schema, though projectId remains entirely unaddressed.

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 ('Put the pages in a new order') and immediately scopes it as a whole-project page ordering, which cleanly separates it from the sibling uichemy_reorder_sections and uichemy_duplicate_page. An agent knows exactly what operation this is 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 strong invocation rules ('pass every page name exactly once', 'home page stays first') but never states when to reach for this tool versus alternatives such as uichemy_reorder_sections or uichemy_set_page_category, nor any preconditions (e.g. project must exist, pages must be known). Usage is implied rather than routed.

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=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: the exact semantics of the order array (1-based, every position exactly once, with a concrete [3,1,2] example). It doesn't cover reversibility or error behavior on invalid positions, keeping it at 4.

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

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

Two tight sentences, front-loaded with the action, and the illustrative example earns its place by disambiguating the non-obvious order semantics. Zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-param mutation with annotations covering the safety profile and no output schema, the description is nearly complete – it nails the tricky parameter. It leaves unstated what happens to sections omitted from the list or how invalid positions are handled, 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 only 33% – only 'order' has a schema description, and pageName/projectId are undocumented. The description compensates strongly for the ambiguous parameter by explaining 1-based indexing, the 'every position once' rule, and giving a worked example, which the bare schema phrase 'Every current position, exactly once' does not.

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 ('Put a page's sections in a new order'), clearly distinguishing this from the sibling uichemy_reorder_pages which operates on pages rather than sections. It's clear and specific, though it doesn't explicitly call out the sibling alternative.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives like reorder_pages or replace_section. Usage is only implied by the imperative 'Put a page's sections in a new order'.

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 flag destructiveHint=true, but the description adds the crucial consequence that annotations cannot express: the copy does NOT carry over because slot tokens belong to the template, so the new layout renders tokens raw until filled. This is exactly the kind of destruction/behavior disclosure that lets an agent anticipate data loss.

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, followed by the critical data-loss warning and the workflow pointer. No filler; every sentence carries distinct 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 destructive, no-output-schema mutation tool this covers the essentials: what changes, what is lost, and how to re-fill. It omits permission/auth requirements and reversibility, but the key agent-relevant behaviors are 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 only 17% (just `index`), so the description carries most of the burden. It adds real meaning for `text` (slot tokens sourced from uichemy_template_slots), but `kind`, `variant`, `projectId`, and `pageName` — including how `kind`/`variant` select the template — remain undocumented in both schema and 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 ('Swap the layout rendering at one position — same slot, different template'), which is precise enough to separate it from uichemy_add_section and uichemy_remove_section by implication. It does not explicitly name those siblings, so differentiation is inferential 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?

Gives a clear usage context (replacing at an existing position rather than adding/removing) and a concrete procedural step: call uichemy_template_slots for the new layout and pass `text`. It stops short of explicitly naming the alternative tools or stating when-not to use it.

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 write semantics (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description usefully adds persistence scope ('Saved to this account') and the eligibility restriction (library layouts only). It does not disclose what happens on a name collision, overwrite behavior, or whether saving is idempotent, which is the main remaining gap for a mutating 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?

Two dense sentences, front-loaded with the action and the payload, followed by the destination and the restriction. No filler or redundant restatement of the title.

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 save tool with annotations present and no output schema, the description covers what is saved, where it lives, and what cannot be saved. It leaves open name-collision/duplicate behavior and the meaning of the required projectId/pageName/index triple beyond what the schema states.

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 only 50%: name and index are documented in the schema, but pageName and projectId are bare strings with no explanation anywhere. The description never mentions any parameter, so it does not compensate for the coverage gap at all.

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 (save) and resource (one section), and enumerates exactly what is captured: layout plus copy, pictures, videos and per-button/per-badge choices. It also distinguishes itself from neighbors by naming the consuming tool (uichemy_insert_saved_section), so an agent can tell it apart from add_section, duplicate_section or set_global_section.

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 the use case (reuse in any other project), the follow-up tool (uichemy_insert_saved_section), the inspection tool (uichemy_list_saved_sections), and an explicit when-not exclusion: 'an AI or code section cannot be saved.' That is a complete routing set for this operation.

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, non-destructive), and the description adds context they cannot: it requires Label Studio to answer, it matches against the labelling team's own layout descriptions, and non-renderable hits are dropped so every returned hit is pickable. That is real operational and result-quality disclosure beyond the structured fields.

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

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

Front-loaded with an imperative that states the core behavior, then example queries, then the sibling comparison, then the dependency caveat — each sentence carries information. It runs slightly long with the parenthetical style, but nothing is 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 exists, so the description's note that returned layouts are renderable/pickable is a useful stand-in. The Label Studio dependency is disclosed, which matters for latency/failure expectations. It stops short of explaining result shape or how hits feed downstream tools like uichemy_add_section, but it is otherwise complete for a 3-parameter search.

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 67% and the description reinforces the key `query` parameter with natural-language examples ("a hero with a big photo and one line of copy"). However, it says nothing about `kind` or the 1-25 `limit`, leaving a third of the parameters documented only by the schema. Adequate but with a clear gap.

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