Edit and publish your FramerToNextJS sites (converted Framer or AI-built) from Claude, Cursor or Codex. 19 tools: read pages, rewrite copy, restyle elements, add sections and pages, design Studio sites, manage CMS collections and items, then publish to your own host. OAuth with a read-only option, and MCP runs no model on FNJ's side. Requires an FNJ plan (Lifetime or any AI builder plan).
Scored across 19 tools
The six read/context tools (get_site, get_site_context, get_page_context, get_page_outline, get_page_text, list_sites) are at risk of overlap, but the descriptions explicitly differentiate them (words vs boxes vs node tree) and give routing guidance for converted vs Studio sites. Minor tension exists because batch_edit_design claims to be 'the ONLY tool that writes to a design document' while add_section, edit_text, and set_style also write, which could confuse an agent about where to make changes.
All 19 tools follow a strict snake_case verb_noun pattern with a small, predictable verb set (get_, list_, create_, update_, edit_, set_, add_, audit_, publish). No camelCase mixing or vague standalone verbs, and the lone verb-only tool (publish) is unambiguous.
At 19 tools the surface is on the heavy side for the domain, and several read tools (get_site vs get_site_context, get_page_context vs get_page_outline vs get_page_text) could plausibly be consolidated. The breadth of design editing plus CMS plus publishing justifies most of them, so it is borderline rather than excessive.
The design lifecycle (read context, add/edit/restyle, create pages, audit, publish) and CMS create/read/update are well covered end to end. There are minor gaps in destructive operations: no explicit delete for pages, sections, collections, or CMS items, though batch_edit_design may cover some of these.
Add a new block of content to a page — a call-to-action, a row of cards, a banner — placed relative to a section that is already there. Give it plain semantic HTML with inline styles; it is inserted as written. Re-running with the same sectionId replaces that block instead of adding a second one, so this is also how you revise a section you added.
| Name | Required | Description | Default |
|---|---|---|---|
| html | Yes | The block's HTML. Inline styles only — the site's own classes will not apply to new markup. Scripts, frames and event handlers are stripped. | |
| route | Yes | ||
| scope | No | "page" (default) adds it to this route only. "site" adds it wherever the anchor appears. | |
| siteId | Yes | ||
| position | Yes | "before" / "after" put it outside the anchor; "prepend" / "append" put it inside, first or last | |
| anchorKey | No | key of that element from get_page_outline. OMIT IT to target every element with that tag, which is what you usually want: a converted page has one footer per breakpoint, and naming just one would leave the section off mobile. | |
| anchorTag | Yes | tag of the element to place it against, from get_page_outline, e.g. "footer" | |
| sectionId | Yes | Your own stable name for this block, e.g. "cta-book-a-call". Reuse it to revise, change it to add another. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description goes further by disclosing exactly what the destructive behavior entails: an identical sectionId replaces the prior block. The html param additionally documents that scripts/frames/event handlers are stripped and site classes won't apply.
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 tightly written sentences with no filler, front-loading the core action and examples before the revision caveat. Each 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 carries return-value burden, but for a mutation tool the important thing is behavioral context, which is well covered (replacement semantics, stripping). The get_page_outline dependency is referenced via the schema rather than the description, a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema already documents most parameters (html, scope, position, anchorKey, anchorTag, sectionId). The description adds the insertion-as-written and replace semantics but no additional parameter-level syntax. 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 opens with a specific verb+resource ("Add a new block of content to a page") and grounds it with concrete examples (call-to-action, row of cards, banner). It clearly conveys that this inserts a section relative to an existing one. It does not, however, explicitly contrast itself with siblings like create_page or edit_text.
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 context, including the crucial rule that re-running with the same sectionId revises rather than duplicates, and that changing the sectionId adds a new block. No alternative tools are named for the when-not case, but the add-vs-revise condition is well specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a Studio site for problems worth fixing before publishing: missing titles and descriptions, images with no source or alt text, empty headings, pages with no sections, instances pointing at deleted components, and broken routes. Returns findings with the id of the thing to fix, so the fixes can go straight into batch_edit_design.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description is consistent with a non-mutating audit. It adds useful behavioral context beyond the annotations: the tool returns findings keyed by the id of the item to fix, which lets the agent chain directly into batch_edit_design. It omits any note on scope limits or cost, 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?
A single dense sentence with the purpose and the finding list front-loaded, followed by the routing to batch_edit_design. Every clause describes an actual detection category, though the enumeration is long enough to push against the brevity line.
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 conveys what comes back (findings with fixable ids). The only real gap is that it says nothing about the required siteId or about what an empty/clean audit looks like.
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 sole required parameter (siteId) is never mentioned in the description; 'a Studio site' only weakly implies it. With one simple identifier parameter the gap is minor, but the description adds no syntax or format guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Check') and resource ('a Studio site') and enumerates the exact problem categories it detects (missing titles/descriptions, missing alt text, broken routes, etc.). An agent can distinguish this read-only audit from mutating siblings like batch_edit_design or publish without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context ('before publishing') that signals when to run it, and explicitly routes results onward to batch_edit_design ('so the fixes can go straight into batch_edit_design'). It does not state when NOT to use it or what to do if the audit is unnecessary, so it stops short of full alternative coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a Studio site: pages, sections, nodes, per-breakpoint styles and components, as a list of operations applied in order. This is the ONLY tool that writes to a design document, and it is all-or-nothing — if any operation is rejected, none of them are saved and you are told which one failed. Send a whole page as one call rather than one node at a time: the cost is the same. Pass baseVersion from get_site_context or get_page_context to be refused rather than overwrite an edit somebody made while you were working.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | ||
| operations | Yes | ||
| baseVersion | No | Version from get_page_context/get_site_context. Supply it to be refused rather than overwrite somebody else's concurrent edit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare destructiveHint=true; the description adds far more: the operation is all-or-nothing with no partial saves, a rejected operation reports which one failed, batching is cost-neutral, and baseVersion triggers an optimistic-concurrency refusal instead of an overwrite. This is exactly the behavioral context an agent needs before 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?
Four sentences, front-loaded with the core action and scope, then atomicity, then batching guidance, then the concurrency parameter. No filler, no repetition of the title, and each sentence carries a distinct decision the caller must make.
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 21-variant batch-mutation tool with no output schema, the description covers atomicity, failure reporting and concurrency well. The main gap is the success path: it never says what comes back (e.g. a new version to feed the next call), which matters in a multi-call editing workflow where baseVersion must be threaded forward.
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 at top level is only 33%, but the nested operation schemas are well annotated. The description contributes real semantics the schema cannot express: operations are 'applied in order' and the whole list is atomic, which is essential for reasoning about dependency between ops. It adds nothing, however, about siteId or the 200-operation cap.
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 a Studio site') and enumerates the full scope it covers: pages, sections, nodes, per-breakpoint styles and components. It also distinguishes itself from siblings by declaring it is 'the ONLY tool that writes to a design document', which separates it from set_style, edit_text, add_section and create_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete usage strategy: send a whole page in one call rather than one node at a time, and pass baseVersion from get_site_context or get_page_context. It names the sibling tools that supply the version. It stops short of explicit when-not-to-use guidance relative to the single-purpose siblings (set_style, edit_text), leaving that boundary implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a CMS collection — a repeating content type such as Posts, Team or Testimonials — with the fields you specify. Returns each field's key, which is what create_item expects. The collection stores content and can be read back; it does not by itself publish a page per item, so to show the content put it on a page with add_section.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | What the collection is called, e.g. "Blog posts". | |
| fields | No | The fields each item has. Omit for a single Title field, which you can add to later in the CMS panel. | |
| siteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=true. The description adds genuinely new behavioral context: the collection stores and can be read back, and creating one does not publish a page per item. That clarifies the blast radius beyond the annotation, though it never explains what makes the operation destructive.
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 purpose and jargon definition, then the return value, then the publishing caveat. No filler and no repetition of the schema.
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 states the key return value (each field's key) and explains the downstream publish path. The only gap is that siteId is left unexplained and the destructiveHint is never accounted for.
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%, so the schema already documents name, the fields array, and its label/options semantics; siteId is undocumented in both places. The description adds only marginal parameter meaning by noting that returned field keys feed create_item, which is a reasonable baseline-3 contribution.
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 ("Create a CMS collection") and immediately defines the concept for non-experts with concrete examples (Posts, Team, Testimonials). It also implicitly distinguishes itself from create_item by describing the downstream relationship, so an agent can place it in the workflow 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 clear workflow context: the returned field keys are what create_item expects, and content only becomes visible via add_section. It stops short of an explicit when-to-use/when-not statement or naming list_collections as the read alternative, but the sequencing guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an item to a CMS collection. fields is keyed by the field keys from list_collections. Items are live by default; pass draft: true to keep one unpublished.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | ||
| draft | No | ||
| fields | Yes | ||
| siteId | Yes | ||
| collectionId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already supply readOnlyHint=false and destructiveHint=true. The description adds genuinely useful behavior the annotations do not carry — items publish to live by default and draft:true suppresses that — but it never explains the response, permissions, or what 'destructive' means for a create (e.g. duplicate slugs).
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, front-loaded sentences with no filler; the core action comes first and each following sentence adds a distinct piece of 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 5-param create tool with a nested object, no output schema, and zero schema descriptions, the definition covers the hardest part (field keying and publish default) but omits slug behavior, identifier requirements, and any hint at the returned item.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does explain that `fields` is keyed by field keys from list_collections and clarifies `draft` semantics plus its default, but slug, siteId, and collectionId — including three required params — remain unexplained 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 ('Add an item to a CMS collection'), which cleanly separates it from siblings like create_collection, create_page, and update_item without the reader 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?
Usage is implied (add new, not modify existing) and it usefully cross-references list_collections for field keys, but it never states when to prefer update_item over create_item, nor any prerequisite ordering (site/collection must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a page to the site at a new URL. It starts as a copy of a page that already exists — pass the closest one as fromRoute — and you then make it its own with add_section, set_style and edit_text. Copying rather than starting blank is what keeps the new page's header, footer, fonts and styling consistent with the rest of the site; a page built from nothing would have none of them. Edits to the copy never touch the page it came from.
| Name | Required | Description | Default |
|---|---|---|---|
| route | Yes | The new URL path, e.g. "/pricing" or "/blog/my-post". Slashes nest; anything else is kebab-cased. | |
| title | No | Label for the Pages list. Does not change the page's <title>; use edit_text for that. | |
| siteId | Yes | ||
| fromRoute | Yes | Route of the existing page to copy — from get_site. Pick the closest in layout to what you are building. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is covered. The description adds genuinely useful context beyond that: the new page is a copy, and edits to the copy never propagate to the source page. It does not address what happens if the requested route already exists, which is the main scenario where the destructiveHint could bite.
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 action, and the rationale sentence ('Copying rather than starting blank...') earns its place by explaining why fromRoute is required. Four sentences is slightly long but no sentence is pure 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 4-parameter, no-output-schema mutation tool, the description covers the workflow, the copy rationale and the follow-up editing tools. The remaining gap is behavior on route collision and whether a page identifier is returned, but with no output schema the return-value omission is forgivable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, with route, title and fromRoute all carrying their own descriptions. The description reinforces fromRoute selection ('pass the closest one') but largely restates what the schema already says, and adds nothing for title or siteId. Baseline 3 is appropriate when the schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource with scope: 'Add a page to the site at a new URL.' It further distinguishes itself from the create_collection/create_item siblings by explaining the copy-from-existing-page mechanism, so an agent knows exactly what kind of creation this is.
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 how-to-use guidance — pass the closest existing page as fromRoute, then make the page its own with add_section, set_style and edit_text — naming the follow-up siblings explicitly. It stops short of any when-not-to-use case (e.g. route collisions or when a blank page would be appropriate).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the text of one element on a page. Match it by tag and its exact current text (copy both from get_page_text). The change is saved to the site's draft — visible in the editor immediately, live only after publish.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | Element tag from get_page_text, e.g. "h1", "p", "a" | |
| route | Yes | The page you read the text from | |
| scope | No | "site" (default) changes this text wherever it appears — right for headers and footers. "page" limits the change to this route. | |
| siteId | Yes | ||
| newText | Yes | The replacement text | |
| oldText | Yes | The element's current text, exactly as get_page_text returned it |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds genuinely useful behavioral context beyond them: the change lands in the site's draft, is visible in the editor immediately, and goes live only after publish. It does not, however, warn what happens on a failed match or how site-scope changes ripple across pages, leaving some destructive-operation side effects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the core action and followed by the matching rule and publish semantics. No filler, and each 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?
With no output schema, the description carries the return/side-effect burden and does reasonably well by explaining the draft-versus-live lifecycle. It leaves a gap around failure modes (non-matching oldText, ambiguous matches with the site scope) for a destructive tool with five required 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 coverage is 83%, so the schema already documents tag, route, scope, oldText, and newText in detail. The description reinforces the matching rule (tag plus exact current text) but adds no syntax, format, or default information beyond what the schema property descriptions already carry, 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?
The description states a specific verb and resource ('Change the text of one element on a page') and immediately scopes it to a single element matched by tag and exact current text, distinguishing it from siblings like set_style (styling) and batch_edit_design (bulk design edits). An agent can tell what this does 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?
It explicitly routes the agent to the sibling get_page_text ('copy both from get_page_text') for the matching inputs, which is concrete when-to-use guidance. It lacks explicit when-not-to-use or guidance on choosing between this and update_item or batch_edit_design, 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.
One page's node tree, with each node's id, type, name and text. Styles are off by default and cost tokens — ask for a single breakpoint when you need them. Use the returned ids with batch_edit_design.
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | Page id, or its route like "/pricing" | |
| depth | No | How deep to walk the tree. Default 4; deeper costs tokens. | |
| siteId | Yes | ||
| breakpoint | No | With includeStyles, return only this breakpoint's values. | |
| includeStyles | No | Include each node's styles. Default false — ask for one breakpoint instead when you can. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already covers the safety profile, so the description's job is to add context, and it does: it discloses the token-cost sensitivity of styles and depth, the default-off behavior, and the downstream contract with batch_edit_design. It does not state result size limits or truncation behavior for deep trees.
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: what you get, the costly optional behavior with its mitigation, and how the output is consumed. Nothing is redundant or buried; the default-off warning is front-loaded before the alternative.
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 it by listing the per-node fields. Combined with the cost/default guidance and the handoff to batch_edit_design, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80% and already documents page, depth, breakpoint and includeStyles, so the baseline is 3. The description adds the non-obvious interaction and cost framing (styles off by default, request one breakpoint, depth costs tokens), which meaningfully improves how an agent sets these knobs.
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 (one page's node tree) and enumerates exactly what each node carries (id, type, name, text), which implicitly separates it from text-only or outline-only siblings. It never names those siblings (get_page_text, get_page_outline) as the alternatives, so the differentiation is inferable rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear conditional guidance: styles are off by default, cost tokens, and should be requested for a single breakpoint when needed. It also points forward to batch_edit_design for using the returned ids. No explicit when-not-to-use or named alternative retrieval tool is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The structure of one page: its sections and named containers in order, each with the tag and key you pass to add_section or set_style. Use this before changing layout, spacing or adding anything — get_page_text shows words, this shows the boxes they sit in.
| Name | Required | Description | Default |
|---|---|---|---|
| route | Yes | Page route, e.g. "/" or "/about" | |
| siteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered; the description goes further by disclosing the return shape (ordered sections/containers with tag and key) and its role as a prerequisite for add_section and set_style. It stops short of stating whether results are paginated or cached, so it is short of a 5 but well beyond the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with no filler; the resource description comes first, the usage instruction and the sibling contrast follow in priority order.
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, two-parameter lookup with no output schema, the description covers what is returned, when to call it, and how it differs from the nearest sibling. Nothing an agent needs to invoke it correctly is missing, aside from the self-evident siteId.
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%: route is documented in the schema but siteId has no description anywhere. The description contributes no parameter detail at all, so it neither compensates for the gap nor adds to what the schema already says — the baseline 3 for partial coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a concrete resource (one page's structure: sections and named containers in order) and states what each element carries (tag and key). It explicitly differentiates itself from the sibling get_page_text by contrasting 'words' with 'the boxes they sit in', so an agent can pick between them 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-to-use ('Use this before changing layout, spacing or adding anything') and names the alternative tool plus the condition that selects it ('get_page_text shows words, this shows the boxes'). The routing decision is fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The text on one page, as a list of elements: tag, text, and an optional class. This is how you see a page — call it before editing so your oldText matches exactly. Entries marked edited show the current (already changed) wording.
| Name | Required | Description | Default |
|---|---|---|---|
| route | Yes | Page route, e.g. "/" or "/about" | |
| siteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered; the description adds non-obvious behavior by explaining the return structure and that entries marked "edited" show current, already-changed wording. This is genuinely useful context an agent could not infer from annotations or schema, though nothing is said about ordering, size, or route failures.
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, zero filler, and the highest-value instruction (call before editing) is placed after the output description but before the edge-case note. Nothing is repeated from the name or annotations.
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 takes on describing the return payload (tag/text/class) and does so adequately, plus notes the "edited" marker. Minor gaps remain around pagination or whether all page text is returned at once, but nothing critical to correct invocation 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 only 50%: route is documented in the schema but siteId is undocumented in both schema and description, and the description adds no parameter meaning at all. With half the parameters carrying no semantics anywhere, the description fails to 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?
Names a specific resource (page text) and specifies the return shape (list of elements with tag, text, optional class), which is concrete and actionable. It does not explicitly distinguish itself from sibling readers like get_page_outline or get_page_context, so it falls 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?
"call it before editing so your oldText matches exactly" gives a clear trigger condition tied to the edit workflow (edit_text/batch_edit_design), which is strong usage guidance. It stops short of 5 because it names no alternative tool or when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Details of one project: its pages (routes), CMS collections, live URL, and how many unpublished edits are pending.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | From list_sites |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=true annotation already establishes the safe read-only nature. The description adds valuable context by enumerating what the response includes: pages/routes, CMS collections, live URL, and count of unpublished edits. It does not cover pagination, error behavior, or permission requirements, but it adds more than the annotation alone provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence fragment that immediately states the resource and its returned components. Every element earns its place, with no redundancy or 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 helpfully enumerates the main return fields and the read-only annotation covers the safety profile. The siteId parameter is fully documented in the schema. It lacks guidance on error cases or response format, but it is sufficient for an agent to call and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single parameter siteId is documented as 'From list_sites' in the schema. The description adds no parameter-specific meaning beyond that, so the baseline score of 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool retrieves details of one project, listing pages/routes, CMS collections, live URL, and pending unpublished edits. It distinguishes the resource from list-based siblings by specifying 'one project', though it does not explicitly name or differentiate from get_site_context or list_sites.
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: an agent would call this when it needs detailed information about a single site, and the siteId schema note says 'From list_sites'. However, there is no explicit when-to-use guidance, no when-not guidance, and no named alternative 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.
Everything about a Studio site in one call: its pages with routes and node counts, its components with props and variants, the breakpoints, site metadata, and any broken routes. Start here before designing or editing — it is one round trip and it gives you every id the edit tools need. Only for sites with a design document; converted Framer sites use get_site and get_page_outline instead.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | ||
| includeSeo | No | Run the SEO audit and include its findings. Default false — it walks every page. | |
| includeComponents | No | Component definitions with their props and variants. Default true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered and the description is consistent with it. The description adds real context beyond the annotation: it is a single round trip, it is the prerequisite for the edit tools, and it silently fails to apply to converted Framer sites. It does not, however, discuss latency/cost beyond "one round trip" or failure modes for a missing design document.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with content scope before usage routing and the exclusion clause. Every sentence carries distinct information — contents, when to call it, and when not to.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the return-value burden and does so by enumerating the payload contents. Combined with the routing to sibling tools and the design-document precondition, an agent has everything needed to select and 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 67% and the schema already documents includeSeo (walks every page, default false) and includeComponents (default true). The description's enumeration of pages/components/breakpoints echoes what the schema says about the include flags rather than adding syntax, defaults, or interaction rules, so the baseline of 3 for schema-driven parameters 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?
Opens with a specific verb+resource scope ("Everything about a Studio site in one call") and then enumerates exactly what is returned: pages/routes/node counts, components/props/variants, breakpoints, metadata, broken routes. It also explicitly separates this tool from sibling names (get_site, get_page_outline) for converted Framer sites.
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 ("Start here before designing or editing") with a rationale (one round trip, supplies every id the edit tools need), plus an explicit when-not with named alternatives ("Only for sites with a design document; converted Framer sites use get_site and get_page_outline instead"). 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.
CMS collections on a site, with their fields — needed before creating or updating items.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile needs no restating. The description adds that the response includes collection fields and that the call is a prerequisite step, but says nothing about pagination, ordering, or scope limits on large sites. Adequate but not rich for a read 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?
A single tight sentence with no filler; the resource is front-loaded and the purpose clause follows. It is arguably over-compressed rather than verbose, but nothing in it is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the return-value burden; it does disclose that fields are returned, which is the key detail. It omits any mention of result size or that siteId comes from list_sites, leaving a gap for a tool whose only input is an opaque id.
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%: siteId is typed as a string with no explanation anywhere. The phrase "on a site" loosely implies that siteId scopes the listing, but the description never says what form the identifier takes or where to obtain it, which is the main risk for a one-param tool.
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 (CMS collections on a site) and what comes with it (their fields), which is enough to distinguish it from list_items and list_sites by noun alone. It reads as a fragment with no explicit verb, but the list semantics are unambiguous in context. Sibling differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"needed before creating or updating items" gives a concrete workflow trigger that points at the create_item/update_item siblings as the follow-on actions. It does not name alternatives (e.g. list_items) or state when this tool is unnecessary, 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.
Items in a CMS collection (drafts included), newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| siteId | Yes | ||
| collectionId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds that drafts are returned and the ordering is newest-first, but says nothing about pagination behavior, even though a limit parameter implies pageable results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short fragment with zero waste, and the most useful fact (drafts included) is front-loaded. It is efficient but too thin to be exemplary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the burden of return-value behavior, and it omits pagination semantics entirely for a tool that exposes a limit cap of 100. For a list endpoint this leaves real gaps an agent would hit on 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 description coverage is 0% and the description mentions none of the three parameters. siteId, collectionId, and limit are largely self-explanatory by name, but nothing clarifies limit's default, whether ordering is configurable, or how to fetch beyond the first page.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource precisely ('items in a CMS collection') and adds two distinguishing scope facts: drafts are included and results are sorted newest first. The verb is only implied, and it never contrasts with siblings like list_collections or get_page_text, 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?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the 19 sibling tools. The agent must infer that this is the read-side counterpart to create_item/update_item.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The section templates you can drop into a page, the node types you can create, and the breakpoints. Takes no arguments and reads nothing — call it once when you are about to build.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true; the description adds that it takes no arguments and 'reads nothing,' clarifying this is a static catalog with no server-side lookup or side effects, and that a single call suffices. It does not describe the return shape, but that is the only notable omission.
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 clauses: what you get first, then the usage instruction. No filler words, no restatement of the tool name, and every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameters, the description must convey the payload, and it does by naming the three content categories returned. It is adequate for a zero-argument discovery tool, though it could say a bit more about the form of the returned catalog.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description correctly states 'takes no arguments,' matching the empty schema rather than contradicting it.
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 specific resources returned — section templates, node types, and breakpoints — which is far more concrete than the tool name alone. It does not, however, name any sibling (e.g. list_collections, list_items) to disambiguate which listing tool an agent should pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call it once when you are about to build' gives an explicit trigger condition and cadence, which is strong guidance. It stops short of naming alternatives or stating when NOT to call it, keeping it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's FNJ projects (converted sites): id, name, source, status, and live URL if deployed. Start here when you do not have a site id.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already covers the safety profile, so the description's added value is the scoping (only the user's own sites) and the disclosure of what each result contains, including the conditional live URL. It says nothing about ordering, pagination, or count limits for larger accounts, which is the remaining 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?
Two sentences with no filler, front-loading the resource and its fields before the usage cue. 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?
With no output schema and no annotations about return content, the description carries responsibility for describing results and does so adequately via the field list. Minor omissions (ordering, whether all sites are returned at once) keep it just under complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. The description correctly avoids inventing parameter behavior.
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 (the user's FNJ projects/converted sites), and enumerates the returned fields (id, name, source, status, live URL), which distinguishes it from get_site and the other sibling list_* tools. An agent can tell exactly what this returns 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?
"Start here when you do not have a site id" gives a clear conditional entry point and implicitly routes the agent to get_site once an id is known. It stops short of naming get_site explicitly as the alternative, so it is strong but not fully explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish the site: bakes every draft edit and CMS change into the code and redeploys to the user's connected host (their own Vercel/Netlify). Only works once a deploy target is connected — check canPublish on get_site.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true, so the risky profile is known. The description adds meaningful context beyond that: it defines what publish actually does (bakes draft + CMS state into deployed code) and that it requires a connected external host. It stops short of covering failure modes, latency, or revert behavior, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the core action first, then the gating constraint and where to verify it. Every clause earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description adequately covers what the tool does and the precondition for calling it. It omits what the response returns and what a failed/partial publish looks like, which matters for an open-world destructive action, so it is strong but not exhaustive.
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, siteId, and schema description coverage is 0%, so the description must carry the burden — but it never mentions siteId, its format, or where to obtain it. Implicitly 'the site' refers to it, but no concrete detail is added.
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 (publish) plus the resources acted on (every draft edit and CMS change baked into code) and the target (the user's connected Vercel/Netlify host). This clearly separates it from the design/edit siblings and from get_site/list_sites.
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 states an explicit precondition — 'Only works once a deploy target is connected' — and routes the agent to the exact check ('canPublish on get_site'). That is actionable when-to-use guidance with the gating condition spelled out rather than left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set CSS on one element — padding, margin, background, colour, font size, alignment, gap, border-radius. Applied with !important so it survives the site's own runtime. Pass an empty string for a property to hand it back to the original design.
| Name | Required | Description | Default |
|---|---|---|---|
| css | Yes | CSS properties in kebab-case, e.g. {"padding-top":"96px","background":"#0b0b0f"} | |
| key | Yes | key from get_page_outline, or the element's exact text | |
| tag | Yes | tag from get_page_outline (or get_page_text for a text element) | |
| route | Yes | ||
| scope | No | "page" (default) styles this route only. "site" applies wherever the element appears. | |
| siteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true but the description adds genuinely non-structured behavior: rules are applied with !important to survive the site's runtime, and an empty string reverts a property to the original design. That revert semantics materially softens the destructive picture and is exactly the context the annotation 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?
Two sentences: the first front-loads the operation and scope, the second covers the runtime override and the revert escape hatch. The property enumeration earns its place by hinting at accepted value families; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with no output schema, this covers the essential behaviors (override persistence, revert path, single-element blast radius). It stops short of stating failure modes or that scope defaults to the current route, which is left to 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 coverage is 67%; the description adds meaning for `css` beyond the schema by explaining the empty-string/clear behaviour, which the schema does not mention. It does not clarify `scope` (page vs site) or the key/tag/route relationship, but the added css semantics are real value.
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 ('Set CSS on one element') and enumerates the property families it governs, which clearly separates it from siblings like edit_text or batch_edit_design. An agent can tell what this does 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?
Usage is implied by the single-element framing and the empty-string revert tip, but there is no explicit when-to-use guidance versus batch_edit_design or edit_text, nor any prerequisite or exclusions. Adequate but with a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change some fields on an existing CMS item. Only the fields you pass are touched.
| Name | Required | Description | Default |
|---|---|---|---|
| draft | No | ||
| fields | Yes | ||
| itemId | Yes | ||
| siteId | Yes | ||
| collectionId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is signposted. The description usefully adds patch semantics ('Only the fields you pass are touched'), but it does not explain what the destructive hint means in practice, whether changes go live, or the effect of the undocumented draft flag.
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 filler, with the patch-scoping caveat front-loaded immediately after the purpose. Nothing is padded or redundant.
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 five-parameter, nested-object mutation with no schema descriptions and no output schema, this is too thin. Missing are the draft/publish semantics, the shape of the fields payload, and any error or permission context an agent needs before calling it.
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% across 5 parameters, so the description carries the full burden and largely fails. It gestures at the fields object but says nothing about siteId/collectionId/itemId, the allowed keys inside the free-form fields object, or what draft does.
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 ('Change') and resource ('an existing CMS item'), which cleanly separates it from create_item in the sibling list. It is clear what the tool does, but it never names or contrasts itself with the other mutation siblings such as batch_edit_design or publish.
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 (e.g., item must already exist, whether the item must be unpublished), and no named alternatives. The reader must infer the tool's place in the workflow from the word 'existing' alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_sectionaudit_designbatch_edit_designcreate_collectioncreate_itemcreate_pageedit_textget_page_contextget_page_outlineget_page_textget_siteget_site_contextlist_collectionslist_itemslist_section_templateslist_sitespublishset_styleupdate_itemLets your AI build and edit websites in Xodia, a visual website builder for real code (Vite, React, Tailwind CSS or plain HTML in your own git repo): read and write site files, create pages and CMS collections, run typecheck, design and link checks, take screenshots, manage forms and translations, and pick up change requests the user sends from the visual editor. Sign in once with your Xodia account (OAuth). Free plan, no card needed. Setup: https://xodia.ai/ai/mcp
Manage WordPress blogs and WooCommerce shops from Claude, ChatGPT, Cursor and other MCP apps.
AI-powered design and management for Webflow Sites
Publish SEO pages from Claude or Cursor to your website. Next.js now, more frameworks soon.
Add one secure layer between your agents and this server.
