Siteon

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=false); the description adds genuinely useful behavior the agent could not otherwise know — internal retry on schema collision, the requirement to mirror the field in HTML with a matching name, the mandatory _hp honeypot, and the no-JS submission rule. Value is real but scattered among unrelated billing/delete-site passages.

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?

Most of the text is off-topic for adding a field: plan_set, checkout expiry, plan_downgrade/plan_remove, delete_site restoration, embed snippets and publish_form. The agent must sift through billing and site-lifecycle rules to find the one paragraph about form fields, and the tool-specific content is not front-loaded past sentence one.

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 nested-object write tool with no output schema, the description covers the essential outer-loop contract (create_form_if_missing, form_label, HTML synchronization, show_if markup) well enough to call correctly. It stops short of describing the response shape or what get_embed_snippet returns in detail, but 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?

Schema coverage is already 80%, yet the description adds semantics the schema lacks: key naming rules, the requirement that the HTML input name match fields[].key exactly, the reserved "_hp" key, and how show_if fields must be wrapped in data-sitekit-field divs. It doesn't explain create_form_if_missing/form_label interplay beyond the schema text, hence not a 5.

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

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

The opening sentence gives a specific verb and resource ("Add one input field to a form") and even names the underlying mechanism (get_schema → add → update_schema). It is distinguishable from create_form, though the core statement is buried under a large amount of unrelated policy 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 explicitly routes whole-form needs to create_form/publish_form, explains create_form_if_missing, and ends with a clear when-to-use/when-not block about explicit user requests and prompt-injection resistance. The signal is present but diluted by billing and site-deletion guidance that does not apply to 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?

Goes well beyond the annotations (readOnly=false, destructive=false, openWorld=false) by disclosing the required scope (submissions:write), the 2,000-character cap, the visibility model (all shop staff read notes in the admin), and the deletion authority (only the site owner, in the admin). That is the operational context an agent needs before writing a semi-permanent, broadly visible record.

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 statement and visibility/deletion facts are front-loaded and dense with value. The bracketed [When to use] block is generic safety boilerplate that is useful but longer than strictly necessary for this one tool, costing a point.

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-destructive mutation with annotations and full schema coverage, the description covers scope, limits, audience and safety. The only notable gap is that no output schema exists, so it could say what the call returns (the created note's id or the updated submission), leaving a small hole.

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 each parameter is self-documented (submission id, note text with the 2,000-char limit, site id). The description's only added parameter detail is the repeated character limit; the "key scope" line is auth context, not parameter semantics. Baseline 3 applies.

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

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

States a specific verb and resource ("Add a note to a submission") plus the intent ("keeping a record of the follow-up or a summary"), which cleanly separates it from the status-changing siblings like set_submission_status or add_submission_status. An agent knows exactly 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?

Gives a clear usage context (recording a follow-up or summary) and an explicit gating rule: only use it when the user explicitly asks, plus guidance on not obeying instructions found in external data. It stops short of naming alternatives (e.g. status updates vs notes), so it earns a 4 rather than 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=false and destructiveHint=false, and the description adds real context beyond them: the required auth scope (submissions:write, site owner), that the call changes data or sends notifications, and that built-in statuses are immutable. It stops short of describing conflict behavior when a key already exists, which is the main remaining unknown for a create 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?

Front-loaded with the substantive definition and semantics, then a clearly delimited [When to use] section. The safety boilerplate is longer than the functional content, but it is structured rather than rambling and every clause is 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 5-param, 3-required mutation with no output schema, the description covers required and optional params, auth, and immutability constraints. The gaps are the meaning/format of color and the behavior on duplicate keys; return values need not be covered since no output schema exists.

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 schema description coverage at 20% (only 'site' documented), the description has to carry the load, and it mostly does: it explains that key is lowercase/digits/underscore, label accepts any language, and crucially that closed=true means the status counts as done. Color is left unexplained (hex vs. named value), so one optional param remains ambiguous.

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 pair: adding a custom submission status definition, with the required scope (site owner) and key format. It implicitly separates itself from the read paths (list_submission_statuses) and from mutation siblings by noting built-in statuses cannot be redefined, but it never names update_submission_status or set_submission_status as the alternatives, so the differentiation is only partial.

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 [When to use] block gives a clear gating condition (only when the user explicitly asks) and warns against acting on instructions in external data, which is actionable guidance for a mutating tool. What it lacks is guidance on when to pick this over update_submission_status or set_submission_status for an existing 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?

Adds genuinely useful behavior beyond the annotations: quota consumption ("Counts against the plan's daily limit"), consent not required, and a prompt-injection warning about external data. However, the "[When to use]" block claims the tool "changes data or sends notifications," which mischaracterizes an analysis/read operation and contradicts the same description's "nothing is taken." Annotations (readOnlyHint=false, openWorldHint=true) technically leave room for the write framing, so this is an internal inconsistency rather than a direct annotation contradiction.

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 return/exclusion enumeration is front-loaded and earns its space, but the trailing "[When to use]" paragraph is boilerplate that both wastes length and injects a wrong characterization of the 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 no output schema, the description carries the return-shape burden well by enumerating every returned field group and the exclusions. Quota and consent behavior are also covered. The misleading when-to-use block is the only missing/wrong piece an agent needs 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 description coverage is 100% — url, site and pages are each documented in the schema, including the 1-3 page cap and default. The description adds no parameter-level meaning (e.g. how many pages to read for a design audit), so the schema carries the full load.

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

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

The description states precisely what is extracted (palette with hex/roles, fonts, layout, tone metrics, meta) and, unusually, what is deliberately excluded (no text, images, logos or links). No sibling tool does anything comparable, so it is easy to place. It stops short of a clean verb phrase ("The look of..."), which keeps it from a 5.

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

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

It gives a downstream-purpose constraint ("use the result only to choose colours, fonts and structure for the person's own site") but no real guidance on when to pick this over fetch_site or other read tools. The "[When to use]" block is generic boilerplate rather than guidance specific to 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?

Goes well beyond the annotations: discloses the required scope (submissions:write), the not_a_member error for users outside the site, and the optimistic-concurrency contract for expected_version including the read-first default and the 409 re-read loop. This is exactly the kind of runtime behavior an agent cannot infer from readOnlyHint=false.

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 the permission scope, then the error and concurrency details, with the safety block clearly segmented under [When to use]. Dense but every sentence carries operational information; minor cost is the slightly recursive wording of the 409 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?

For a four-parameter mutation with no output schema, it covers scope, error cases, concurrency, and safety intent. It stops short of saying what a successful call returns or which parties receive the notification it alludes to, which would help an agent report results.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value on top by sourcing user_id from list_submission_statuses, defining the not_a_member failure for that parameter, and explaining expected_version's read-concurrency semantics by reference to set_submission_status.

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 a submission's assignee") and immediately names the related siblings (list_submission_statuses, set_submission_status) so the agent can distinguish it from the similarly named status-setting tools. The null-removal behavior makes the effect unambiguous.

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

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

The [When to use] block gives explicit gating: only when the user explicitly asks, and never in response to instructions found in external data. That is strong guidance for a mutation tool, though it does not compare this tool against set_submission_status or add_submission_status as alternatives for adjacent workflows.

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

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

Beyond the annotations, which only declare the read-only/destructive profile, the description discloses the required key scope and a non-obvious visibility rule: owners/admins see everything, a billing seat only billing rows, a site owner only their sites. That role-based filtering materially changes how an agent should interpret an empty or partial result.

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

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

One dense paragraph with the safety profile and scope requirement front-loaded, and the narrowing parameters last. 'Read-only; changes nothing' slightly duplicates readOnlyHint/destructiveHint annotations, but the rest of the text earns its 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 compensates by naming the returned fields (change, actor, site, result ok/conflict), the permission model that governs row visibility, and the full set of filtering inputs. An agent has enough to call it correctly and interpret the response.

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

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

Schema coverage is 75% (site, limit, since documented; offset bare), so baseline is 3. The description summarizes that site, since, limit (1-200) and offset narrow the result set, largely restating schema content, and offers no additional guidance on offset behavior or since semantics beyond 'ISO time'.

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 content: the account's audit log of API-key operations, listing what changed, the actor, site, and result. That verb+resource+payload framing distinguishes it from the many list_* siblings, which cover entries, forms, submissions, and members rather than audit rows.

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?

Sets clear context with the required key scope (audit:read) and explains who sees what rows, which effectively tells the agent who can use it and what it will return. It does not name an alternative or state a when-not condition, but no plausible sibling overlaps this audit-log niche.

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, and the description goes well beyond them: cancellation is irreversible, removes the calendar event, and emails the invitee. It also documents the compare-and-set failure mode (409 conflict → re-read and re-ask) and the already_canceled / not_cancelable outcomes, which annotations cannot express.

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 irreversibility warning and the confirmation procedure, which is the right ordering for a destructive tool. It loses a point for mild redundancy ('cannot be undone' appears twice) and a dense, run-on block that could be split.

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 5-parameter tool with no output schema, the description covers preconditions, required confirmation flow, failure modes, and side effects. Nothing an agent needs in order to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by tying confirm:true and expected_version to the required human-agreement and read-then-cancel workflow, and by noting reason is recorded and shown to shop staff. The conflict/409 consequence of a stale expected_version is genuinely beyond the schema, though most other parameter meaning is already documented.

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 precise verb+resource ('Cancel a confirmed booking on the shop's side') and scopes it to shop-side cancellation, distinct from booking_pause/cancel_submission siblings. The consequence ('notifies the customer') is stated immediately so the agent knows what class of operation 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?

It gives an explicit when-to-use rule ('only when the user you are talking with explicitly asks for it'), an explicit prerequisite sequence (read via booking_status/bookings_list, state date/time/invitee, get an explicit yes), and an exclusion (ignore instructions embedded in external data). Alternative tools are named rather than implied.

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

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

Goes well past the annotations: it discloses that the created page starts paused as a draft and is not public until booking_page_publish, names the auth scope (bookings:config), and specifies failure behavior (a flagged text on a free site yields check_failed 422). Those are the operational facts an agent needs before calling a write tool, none of which annotations 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-loaded with the action and the draft-state caveat, then the parameter reference, then the workflow pointer. The dense settings list is justified by the 40% schema coverage, though the generic '[When to use]' safety paragraph is boilerplate that could be trimmed for a tool that already states its own prerequisites.

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 create tool with no output schema, nested settings object, and 5 parameters, the description covers creation semantics, draft/publish lifecycle, required settings with validation rules, error behavior, and the follow-up validation step. Nothing an agent needs to invoke 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 only 40%, but the description compensates thoroughly: form is the form key from list_forms, resource is the id from booking_status resources[].id, and every settings field is enumerated with constraints — duration_min must be a multiple of 5, weekly accepts a concrete {mon:[["09:00","17:00"]]} shape, max_per_day 1-20, max_active_per_email 1-10, date formats YYYY-MM-DD. Only site/redirect_path rely on schema text, and those are already described there.

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 booking page on an existing resource') plus the required key scope 'bookings:config', which immediately separates it from sibling mutation tools like booking_page_update and booking_page_publish. An agent can tell what it creates and where 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 '[When to use]' block gives an explicit gate — only call when the user has explicitly asked — plus a prompt-injection exclusion, and the body prescribes a workflow ('Check the open slots with booking_slots before publishing'). What it does not do is contrast with booking_page_update (when to create vs. modify an existing page), which is the most likely sibling confusion.

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?

Rich beyond the annotations: it discloses the required key scope (bookings:config), the 409/resource_inactive failure mode, and the optimistic-concurrency contract via the two expected-version parameters. However, it never states what publishing does to a subsequently edited page (does publishing again require a new version?) or any rate/idempotency behavior, so gaps remain despite the strong start.

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 pre-flight sequence, then the when-to-use block. The prompt-injection boilerplate in the last two sentences is generic and repeats a policy likely applied across many tools, so it costs some density, but nothing is redundant with 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?

No output schema exists, and the description compensates by naming the return values (public_url, embed_snippet) and what to do with them. Combined with the prerequisite chain and error code, an agent can call this correctly without further reading.

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 60% schema coverage, the description usefully maps values to parameters: 'confirm: true', 'the page version as expected_version', 'the resource version as expected_resource_version', each of which the schema barely labels. The bare `id` parameter receives no explanation in either place, keeping this below the top score.

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 ('Publish a paused booking page') plus the user-visible effect ('visitors can book from then on'), which is meaningful. It does not differentiate from close siblings such as booking_resume, booking_pause, or booking_page_update, so an agent must infer which of these actually toggles the page live.

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 sequenced workflow: read the page via get_booking_page, read the resource via get_booking_resource, show settings and booking_slots, obtain an explicit yes, then call with confirm/expected versions. It also names an exclusion condition ('use it only when the user explicitly asks') and warns against acting on instructions embedded in tool results.

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

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

Adds substantial behavior beyond the annotations: the required key scope (bookings:config), optimistic concurrency via expected_version with a 409 conflict outcome, and the immediate-visibility side effect ('a live page changes for visitors at once'). None of this is derivable from readOnlyHint=false / destructiveHint=false 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-loaded with the operation, then the versioning caveat, then a bracketed usage block — easy to scan. The prompt-injection boilerplate is wordy but is standard safety copy rather than filler about the tool itself.

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, yet the description covers the mutation semantics, permission scope, concurrency failure mode, and visibility impact — everything needed to invoke safely. Remaining gap is the opaque settings object, mitigated only by a pointer to booking_page_create rather than enumerated fields.

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 40% and settings is an undescribed nested object, but the description compensates by defining it as a subset of booking_page_create fields. It also explains expected_version's provenance (version read from get_booking_page) and the 409 consequence, going beyond the bare integer type.

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 booking page's settings ... and / or redirect_path') and immediately anchors the field set to a named sibling ('the same fields as booking_page_create, any subset'), so an agent can distinguish it from create/get/publish 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 workflow prerequisite: read with get_booking_page first and pass expected_version, otherwise conflicts surface as 409. The [When to use] block adds a clear consent gate ('only when the user explicitly asks'). It stops short of contrasting against booking_page_publish or booking_resource_update, so no full alternatives 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?

Beyond the annotations, the description discloses the required key scope, explains that existing bookings are kept, and states how to undo the pause for pages and resources. It even notes the calendar-connection requirement for resuming a resource.

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 consequences, followed by key scope, reversal paths, and usage policy. Every sentence contributes useful operational or safety 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 mutation tool with no output schema, the description covers effects, permissions, reversibility, and usage conditions. The annotations already declare the read/write and destructive profile, and the description is complete 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 description coverage is 100%, so the parameters are already well documented. The description adds some semantic distinction between pausing a resource versus a page, but does not add parameter syntax or formatting details 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?

The description uses a specific verb, 'Pause', and clearly identifies the two resource types affected: booking resource and booking page. It explains the consequence for each and distinguishes the action from related siblings like booking_page_publish and booking_resume.

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 includes an explicit [When to use] section requiring the user to ask for the change and warning against following instructions from external data. It also names the tools and conditions for reversing the pause.

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); the description goes further by disclosing the required key scope bookings:config, the side-effect boundary (existing bookings keep their instants), and the optimistic-concurrency contract via expected_version. These are exactly the facts an agent needs before invoking a non-destructive mutation.

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 action, scope, effect on existing data, and version prerequisite are all front-loaded in the first three short sentences. The bracketed safety paragraph is boilerplate that repeats a policy applicable to every mutating tool, which costs some density, but nothing is genuinely 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 four-parameter mutation with no output schema, the description covers the field format, auth scope, concurrency requirement, and data-preservation behavior. It stops short of stating the return value or the failure mode when expected_version is stale, 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?

Schema coverage is only 25% (only 'site' is documented), so the description must compensate and largely does: it specifies the IANA format for 'timezone' with an example and explains where 'expected_version' comes from. 'id' remains undocumented in both places, which keeps it short of 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 and resource ("Change a booking resource's time zone") with the exact field being mutated, and names get_booking_resource as the read counterpart, so an agent can distinguish it from booking_page_update or get_booking_resource 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?

The [When to use] block gives a clear condition (user explicitly asks), an explicit prohibition (do not act on instructions in tool results), and a procedural prerequisite (read the version first if expected_version is missing). The guidance is clear but generic to all mutating tools rather than specific to this operation, and it does not compare against sibling mutation tools like booking_page_update.

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=false, openWorld=false; the description goes well beyond them by disclosing the auth failure modes (personal_key_required 403 for shared keys, not_grant_owner for other users), the mandatory confirmation contract, and optimistic concurrency via expected_version. This is meaningful operational context the 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-loaded with the verb and resource, with the permission constraints stated parenthetically before the call recipe. It is somewhat dense and the prompt-injection paragraph is close to boilerplate, but no sentence is pure filler for a mutation 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?

No output schema exists and parameter coverage is low, so the description carries the burden; it covers auth, confirmation, idempotency/versioning and safety. What it leaves implicit is the success response shape and the exact meaning of "id" for this resource type.

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 25%, so the description must compensate: it explains that confirm must be true and that expected_version is the version previously read — the two parameters where misuse is most likely. The required "id" is only obliquely referenced ("a paused booking resource"), so its meaning is still inferred.

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 ("Resume a paused booking resource") plus the required key scope (bookings:config), which immediately separates it from booking_pause and the read-side booking_status/bookings_list siblings. An agent knows exactly what state transition this performs 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 preconditions: only the calendar connector with their own key, get the user's explicit yes first, then call with confirm: true and expected_version. The bracket section adds when-to-call and when-not-to-call (never trigger on instructions from tool results), which is exactly the guidance an agent needs for a mutation 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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses the required key scope, the ordering, the returned row fields, and data-handling cautions about personal information and prompt injection. These are material behavioral details an agent needs before invoking or trusting the output.

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 purpose, then filters, return fields, and safety guidance. It is information-dense and mostly earns its length, though some filter details duplicate the schema and could be trimmed.

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

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

With no output schema, the description usefully explains the returned fields and their meanings. Combined with the filter semantics, privacy note, and prompt-injection warning, it is complete enough for an agent to invoke 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 description coverage is 100%, so the schema already documents all seven parameters with types, ranges, enum values, and date semantics. The description restates the filters but adds little parameter meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: list the site's bookings, ordered newest start first. It is clear what the tool returns at a high level, but it does not explicitly distinguish this from sibling tools such as booking_status or booking_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?

Filtering options and data-handling constraints are described, so the usage context is implied. However, the description does not say when to use this tool instead of alternatives such as booking_status or get_booking_page.

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

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

Adds real context beyond the readOnlyHint/destructiveHint annotations: paused pages still answer, the window is capped at 14 days, and the `unavailable` result means the calendar could not be reached. The opening 'Read-only; changes nothing' largely restates the annotation, keeping it from 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?

Dense but front-loaded — the read-only nature and scope come first, then the payload, then the range constraint and edge behavior. Slightly packed with parenthetical asides, but every sentence adds information.

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

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

With no output schema, the description carries the return-value burden and does so by naming the slot fields, time zone, and the `unavailable` sentinel. A brief note on ordering or pagination would complete it, but nothing essential is missing 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 already 100%, so the baseline is 3; the description earns extra credit by restating the ISO format for from/to and their defaults (now, from + 7 days) and by explaining the 14-day maximum span exposed by 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 — the open slots of a booking page — and defines the payload (slot start times in UTC plus the resource's time zone). This clearly separates it from status/listing siblings such as booking_status or get_booking_page, which describe pages rather than 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 usage context: it can be used to verify slots on a paused page before a person publishes it, and it notes the default 7-day window and 14-day cap. It does not explicitly name an alternative tool (e.g., booking_test) or state exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that ("Read"). It adds non-obvious behavior beyond the annotations: the required key scope (bookings:write), the fact that the backing calendar resource cannot be created here and must be connected by a person in the admin, and that pages created elsewhere start paused as a draft.

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

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

Front-loaded with purpose, which is good, but the body sprawls across the full page/resource CRUD lifecycle, an external product's URL, and an admin_url aside that belong to the sibling mutation tools rather than to a read-only status call. The enumeration of returned fields is informative but dense, and the piece reads as one long run-on.

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 only one parameter, no output schema and full schema coverage, the description compensates well by naming the returned fields, the auth scope, and the domain boundary. Remaining gaps are minor: no note on result size/pagination and no contrast with get_booking_page/get_booking_resource.

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 (site) at 100% schema description coverage, so the schema already explains it is the id from list_sites. The description adds no site-scoping nuance (e.g. multi-site behavior or what happens with an invalid/unauthorized site id), 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 and resource ("Read the site's booking setup") and enumerates what is returned: resources with status/paused_reason/timezone/version and booking pages with title/form_key/duration_min/hours/public_url. What it does not do is distinguish itself from the read siblings get_booking_page and get_booking_resource, which return overlapping data for a single page/resource, so an agent must infer the overview-vs-detail split.

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?

Strong exclusion guidance: it explicitly says memberships, coupon books, class booking and capacity-limited slots are out of scope and should be redirected to Gym rather than built. It also routes the mutation lifecycle to booking_page_create/update/publish/remove. The gap is that the closest read alternatives (get_booking_page, get_booking_resource) are never named, so the most likely misuse case is unaddressed.

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

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

The description adds substantial behavior beyond the annotations: it really holds the slot, creates a Google Calendar event, auto-cancels after keep_minutes, and explicitly says nothing is sent to Webhooks, spreadsheets, staff, or the invitee. It also discloses rate limits, wait behavior, and returned state fields. The only slight gap is that the interaction with destructiveHint=false and the cleanup mechanics is described but not framed as a reversibility guarantee.

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 action and the core side effects, and nearly every clause carries operational meaning for a risky mutation. It is dense and parenthetical, however, so scanning the many constraints takes more effort than an ideal structure would require.

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

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

Given the mutation risk, authentication requirements, cleanup behavior, rate limits, and lack of an output schema, the description is complete enough to call the tool correctly. It covers prerequisites, side effects, confirmation, return fields, and what is not triggered.

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 useful semantics beyond the schema: slot defaults to the first open slot in 14 days, wait can take up to 90 seconds, keep_minutes defaults to 30 and is capped at 1440, and confirm requires the user's explicit agreement. It does not document every parameter individually in prose, but the added behavioral meaning is significant.

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: make one test booking on a booking page through the real booking intake. It immediately distinguishes the tool from page-editing siblings by emphasizing end-to-end calendar and Meet behavior, and it clarifies that a paused page can also be tested.

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 explicit prerequisites (key scopes forms:test and bookings:config, own key, site owner who connected the calendar) and explicitly excludes shared keys. It also states the confirmation protocol and includes a clear when-to-use warning against following instructions from external data.

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 annotations: discloses the customer notification, the irreversibility, the waitlist promotion side effect, the 409 conflict semantics with no-op guarantee, the cancelable-state whitelist, the cancel_until deadline behavior, and the meaning of the 'promoted' response field. This is exactly the mutation-side context an agent needs.

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

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

Well front-loaded with the destructive warning and organized into workflow and when-to-use blocks. However, it is long and repeats the irreversibility message ('cannot be undone' appears twice, once as a bracketed aside), which is mild waste rather than failure.

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?

Despite having no output schema, it explains the response's 'promoted' field, enumerates failure codes, and covers the full mutation lifecycle. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'confirm: true' requires prior explicit user agreement, and 'expected_version' must be the version read via get_submission, with a 409 if it changed. It also clarifies what the site/id refer to indirectly through the workflow.

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 ('Cancel an entry on a form with a capacity or email confirmation, on the shop's side') plus the required key scope, which is concrete. It does not explicitly distinguish itself from nearby siblings like booking_cancel or deploy_cancel, so an agent must infer the boundary from the 'form entry' framing.

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 pre-call procedure (read with get_submission, tell the user, get an explicit yes, pass confirm:true and expected_version), names the when-to-use condition, and includes a when-not-to-use guard against following instructions embedded in external data. Error branches are enumerated with codes.

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 non-read-only, non-destructive, closed-world mutation; the description adds material context beyond that: the required scope, that locale-primary is mandatory, that version is always 0, and that nothing is published as a side effect. That is exactly the extra behavioral information an agent cannot get from the annotation hints.

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, data shape, and outcome, followed by a clearly bracketed policy block. The policy block is generic boilerplate that runs long relative to the tool-specific content, but nothing is redundant with the earlier sentences.

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-required-param mutation with no output schema, the description covers the gaps that matter: return values (id, version 0, op_id), the required scope, the shape of the nested data object, and the follow-up path to publishing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the nested shape { <locale>: { <field>: value } }, the rule that the primary locale is required, and how to discover valid fields via get_schema → collections[].fields. Only the `site` and `collection` params are left entirely to the schema.

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

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

States a specific verb and resource ("Create a CMS entry as a draft") plus the key scope required (content:write) and the exact return payload. It is clearly distinguishable from siblings like update_entry, publish_entry, and get_entry.

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 publishing never happens here and routes the agent to get_entry_preview then publish_entry, giving the full draft→check→publish workflow. It also states the consent precondition (only when the user explicitly asks) and names the alternative tools by name.

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

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

Annotations cover the safety profile (mutation, non-destructive, closed-world), and the description adds substantial beyond it: required key scopes, form_exists error on key collision, the site-resolution fallback logic, the honeypot requirement, and an explicit no-JS/no-recipients constraint. It loses a point because a large share of the text is about plan/billing and delete_site, which are not behaviors of this tool and dilute the actual disclosure.

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 is front-loaded well, but roughly half the text is off-topic boilerplate about plan_set, plan_status, plan_downgrade, delete_site, restore_site and billing keys that have nothing to do with creating a form. Those sentences do not earn their place here and risk steering the agent toward irrelevant actions.

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

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

With no output schema, the description correctly names the returned values (page_url, qr_url, embed_html) and the returned form_key used as input to add_form_field, plus the error mode on duplicate keys. The remaining gap is that the required scopes and return shape are stated but constrained behavior in the no-page case (what page_url/qr_url become) is left implicit.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds beyond the schema: it explains how site is resolved when omitted (only site / dev site / failure with candidates) and what page:false means in practice. The template list is also glossed with meanings, though the schema enum already carries the values.

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

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

Opens with a specific verb and resource: creates a form from a template plus its public page (URL, QR, embed code). The template enum values are spelled out with human meanings, and the tool is clearly distinguished from add_form_field (adding fields) and publish_form (publishing).

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 selection rules: without a site it uses the only site, creates a dev site when none exist, and fails with candidates when 2+ exist — call again with site. It also names page:false as the case for embedding on the user's own site, and routes to add_form_field and publish_form for adjacent operations.

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 non-readonly, non-destructive, non-open-world; the description goes far beyond by disclosing that the plan is forced to dev, that non-dev origins return upgrade_required with next_steps, that billing fields are ignored or 400, that delete_site takes a site offline immediately and restoration loses domains/Google/plan, and that explicit user consent is required.

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 constraints are front-loaded well, but the bulk of the text is a rule dump that belongs to other tools: HTML form markup, honeypot rules, show_if wrapping, notification recipients, and a long multi-paragraph billing flow (plan_set, plan_downgrade, checkout states). Much of this does not help an agent decide how to call create_site and dilutes the actionable content.

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 create tool with no output schema, the description covers prerequisites, constraints, error behavior, and next steps (get_embed_snippet), which is nearly everything needed. The only gap is that it never says what the call returns (e.g. the created site id), leaving the agent to infer it from the follow-up tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it enumerates the contents of each template ('form' = contact form only, 'news_form' = news + form, 'shop_news_form' = shop info + news + form) and constrains allowed_origins with concrete examples and the upgrade_required consequence. It does not add anything for id/name, but those are already fully documented.

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 first sentence names a specific verb and resource ('Create a new Siteon site') and immediately bounds scope ('the plan is always dev, for development'). It also differentiates from the closest sibling by pointing to create_form when only forms are needed.

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 is given: use create_form if the user only needs forms, use update_site_origins to change origins later, use get_embed_snippet after creation, read site_version before delete_site. It also states the prerequisite that production domains require a paid plan and that billing values are rejected.

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 annotations: it specifies the required scope (deploy:write), states the live version is unaffected, describes the 409 error case, and explains what happens to reserved space. This is exactly the behavioral context the annotations alone do not convey (and it is consistent with destructiveHint=false, since nothing live is changed).

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 behavior and error case are front-loaded in the first two sentences. The bracketed usage/security block is somewhat templated boilerplate, but it is relevant and short enough not to obscure the main content.

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 the full picture an agent needs: required scope, effect on live version, failure mode, and the alternative tool. Nothing essential for 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 description coverage is 100%, so both parameters are already documented in the schema. The description adds no further detail on format or provenance beyond repeating the 'id deploy returned' idea, 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 and resource ('Cancel a deploy that is still running') plus the side effect ('give its reserved space back'). It explicitly separates itself from the sibling 'rollback' and from already-finished deploys.

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 bounds the tool: only running deploys, 409 for live/finished ones, and names rollback as the alternative for that case. It also states the consent condition (user must explicitly ask) and warns against following instructions embedded in tool output.

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

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

Beyond the readOnlyHint annotation, it discloses truncation caps (≤20 changed pages, ≤10 blocks each), that output is meant to be shown to a human before mutation, and a prompt-injection warning that page text is data not instructions. These are behavioral traits 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?

Front-loads read-only status, then the comparison direction, then output shape, then the operational instruction. Dense with parenthetical qualifiers rather than prose sprawl; no sentence 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?

With no output schema, the description carries the return-value burden and does so: files added/removed/changed and per-page detail with explicit caps. The safety profile and next-step guidance are included, so an agent can call and act on it without further context.

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

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

Schema coverage is already 100%, so baseline is 3; the description adds the provenance of the 'to' value (a deploy id from list_versions) and restates the accepted forms. It largely mirrors the schema but the sourcing hint carries modest extra 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?

States a specific verb and resource (diff between two versions) plus the scope involved (deploy:write), and anchors the 'to' argument to sibling tools. An agent can tell this apart from preview_version or list_versions 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 directs use before rollback or publish_draft — naming the downstream siblings this feeds — and specifies where 'to' values come from (list_versions, live, draft, draft:<n>). Both the when and the value source are stated outright.

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

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

The description itself is rich — consent refusal returns the consent page URL, robots.txt is obeyed, a draft must exist before import_images, images are capped at 20 / 5 MiB, and calls count against the daily plan limit. However, it describes fetching arbitrary external websites and ingesting 'data written by other people', which conflicts with the declared openWorldHint=false. That inconsistency is flagged, though the surrounding disclosure is otherwise strong.

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 verb and resource are front-loaded, but the body is one dense run-on paragraph mixing return shape, consent flow, image limits, rendering fallback and plan quotas. Content earns its place individually, but the lack of structure makes it hard to scan, and the appended generic safety paragraph repeats the read-only-of-external-data idea.

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 spells out the returned page structure (title, description, lang, headings, nav, text blocks, forms, links, image URLs) and the failure shapes (consent refusal, render.reason). For a six-parameter fetch tool with prerequisites, this is complete enough to call correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: import_images downloads up to 20 pictures of named formats and sizes into the draft's candidates with source_url and requires an existing draft; render 'auto' triggers headless rendering and reports failure via render.reason; purpose is tied to the recorded consent. Only 'pages'/'site' get no extra treatment, which the schema already handles.

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 ('Read an existing website'), the scope of the read (same-origin pages, robots.txt, plan page count) and enumerates what is returned. It also explicitly names the sibling that replaces it for already-published sites ('start from it with restore_draft'), so an agent can distinguish it 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?

Gives an explicit prerequisite (request_fetch_consent must have been agreed in the browser), an explicit prohibition ('Never fetch a site the person does not own or have permission for'), an explicit alternative (restore_draft / list_versions for Siteon-published sites), and the fallback path when rendering fails. When-to-use versus when-not-to-use is fully 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 readOnlyHint and destructiveHint=false, so the safety profile is covered; the description adds genuinely useful auth context — the required scope and the site_restricted_key limitation. It does not describe failure behavior or error output, which leaves a small 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 short sentences, both front-loaded with the essential information: what is read first, permission constraints second. 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 usefully names the returned values (language/locale and time zone) plus auth constraints, which is enough for an agent to call it correctly. It omits error/edge-case behavior, but nothing critical is missing for a zero-param read.

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; baseline 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 (Read) and resource (the account) and names the returned fields (locale, time zone), which is well beyond restating the name. It stops short of explicitly contrasting with get_settings or update_account_settings, so sibling differentiation is only implied.

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 precondition for use (key scope settings:read) and an explicit exclusion (keys limited to specific sites). It does not name an alternative tool for the excluded case, keeping it just below 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 readOnly, non-destructive, closed-world, so the bar is lower; the description still adds real value by naming the auth scope required and by cataloguing the returned fields (public_url, embed_snippet, version) in the absence of an output schema. It does not cover error/not-found behavior, keeping it below a 5.

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

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

A single front-loaded sentence with the verb first and the payload enumeration after. The long field list is the one place it thickens, but it substitutes for a missing output schema, so it mostly 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 two-parameter read tool with no output schema, the description supplies the two things an agent would otherwise lack: what comes back and what permission is needed. The parameter semantics are fully covered by 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 100% and both parameters carry their own descriptions (id from booking_status pages[].id, site from list_sites), so the schema does the work. The description adds nothing about parameter formats or constraints; baseline 3 applies.

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

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

States a specific verb and resource ("Read one booking page") plus the scope of what is returned. The enumerated settings make it clearly distinct from booking_page_update/booking_page_create and from the plural listers like booking_status.

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

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

The description implies single-page settings retrieval and discloses the required scope (bookings:read), but never says when to prefer this over booking_status, get_booking_resource, or booking_slots. The id-provenance hint lives only in the schema, not the description.

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

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

Annotations already declare readOnly/openWorld=false, but the description adds the required key scope (bookings:read) and enumerates what the response contains, which matters since there is no output schema. It stops short of stating error behavior for missing ids or sites.

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 scope requirement attached to the verb and the payload enumerated compactly. 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 two-parameter read with full schema coverage and readOnly annotations, the description supplies the missing pieces: auth scope and the field set returned. Only cross-tool routing guidance 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?

Schema coverage is 100% and both parameters already carry descriptions linking id to booking_status resources and site to list_sites. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Read one booking resource') and enumerates the returned fields (calendar, busy calendars, time zone, status, paused_reason, version). It implicitly separates itself from booking_resource_update and bookings_list, though no sibling is named explicitly.

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

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

Usage is only implied by 'Read one booking resource' and the 'bookings:read' scope note. It does not say when to prefer this over booking_status, get_booking_page, or bookings_list, so an agent must infer the selection.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description adds important behavioral context: the tool requires deploy:write scope, reports up to 500 files, interprets blobs_missing as files whose bytes did not arrive, distinguishes draft_version from published_version, and explains the null case for live_deploy_id. It also connects the 409 case to re-reading the draft, which is valuable operational guidance.

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 dense but front-loads the key fact ('Read-only; changes nothing') and then provides a structured enumeration of return fields and usage hooks. The length is justified because there is no output schema, though the single long parenthetical list makes it less scannable than 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?

For a read-only inspection tool with no output schema, the description is complete: it explains the return fields, their meanings, version relation semantics, missing-blob handling, publish-related identifiers, and when to call the tool. An agent has enough information to invoke get_draft correctly and interpret its results without additional documentation.

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

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

There is only one parameter, site, and the schema description already explains it fully as the site ID from list_sites. The description refers to 'the site's draft' but does not add any meaning beyond the schema's parameter documentation, so the baseline of 3 is appropriate for 100% schema coverage.

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

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

The description clearly states that this tool reads the site's draft and precisely enumerates what the draft response includes: draft_version, files, upload candidates, missing blobs, published_version, live_deploy_id, last_publish, and versions. This is far more specific than a generic 'get draft' and lets an agent distinguish this tool from siblings such as read_draft_file, preview_draft, and list_versions.

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 explicit invocation conditions: call it before the first write_files of a conversation and after any 409. It also explains how the returned values are used by write_files, publish_draft, and restore_draft, which helps an agent understand the tool's place in the workflow, though it does not explicitly state when to prefer alternatives like preview_draft or read_draft_file.

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

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

The annotations already establish a safe read-only, non-destructive operation, and the description adds useful behavioral detail about what is returned and how the returned HTML must be treated. It warns that form names, data-sitekit-form, and _hp must not be changed, which is meaningful context beyond the annotations. It does not contradict the read-only annotation.

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

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

The first sentence is well front-loaded, but the description is dominated by a large rules block covering schema key conventions, billing, deletion, and unrelated tools. Much of that content does not belong in get_embed_snippet and makes the definition unnecessarily difficult to scan. The useful signal is buried under substantial global 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?

For a read-only snippet retrieval tool with full parameter coverage and no output schema, the description explains the returned pieces and the important usage constraints. It is more than complete for invoking the tool correctly. The main weakness is that excessive unrelated rules add noise rather than necessary context.

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

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

Schema description coverage is 100%, so the parameter meanings are already documented in the schema. The description adds only the useful default behavior that omitting form returns all forms, which is implied but reinforced. Baseline 3 is appropriate because the schema carries most semantic weight.

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

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

The first sentence clearly states a specific verb and output: return the embed code, script tag, forms HTML, and rules. It also clarifies the optional scope with 'Without form, all forms.' It does not consistently distinguish this tool from related retrieval tools, though it later mentions create_form as an alternative for form-only needs.

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 calling context: use it to obtain paste-ready embed code, use the returned HTML as-is, and do not alter name values or the honeypot. It also names create_form as an alternative when the user only needs forms. It lacks a direct when-not comparison against other embed/schema retrieval paths, so it is not fully 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 already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real value: the required key scope, the guarantee of unfiltered per-language content, and an explicit prompt-injection caveat that returned text is data, not instructions — a security note no annotation provides.

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

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

Two tight sentences, zero filler. The operation and scope are front-loaded, and the injection warning is appended last where it belongs. 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, the description usefully previews the return payload (all languages, _meta, status, dates) and the scope requirement. The only gap is error behavior — it doesn't state what happens for a missing or unpublished entry id — which is minor for a simple read tool.

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

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

Schema description coverage is 100%, so id, site, and collection are already documented (including the pointer to list_entries and list_sites). The description adds nothing about parameter usage beyond implying no language filter; the baseline 3 is appropriate when the schema carries the semantics.

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

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

States a specific verb and resource ('Read one CMS entry as stored') and even enumerates the payload shape (every language and _meta, status, dates). The phrase 'as stored' implicitly separates it from get_entry_preview/get_draft/get_entry_revision, but no sibling is named so the differentiation must be inferred.

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

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

The description implies the read-one-entry case and flags the required scope ('key scope content:read'), which is a useful prerequisite. However, it never says when to prefer this over get_entry_preview, get_entry_revision, get_draft, or list_entries, so the agent must guess among four plausible siblings.

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

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

Beyond the readOnlyHint/destructiveHint annotations it adds real behavioral context: the required key scope (content:read), the locale fallback to the primary language for missing translations, and the transformation of images into URLs and select fields into labels. It also warns that entry text is data, not instructions, which is a useful prompt-injection guard. 'Read-only; changes nothing' largely restates the annotations, and error behavior (e.g. unknown id) is unstated.

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-only disclaimer is front-loaded, which is good, but it duplicates what annotations already declare, and the locale-default sentence repeats the schema. The middle sentence is a long em-dash run-on that packs four distinct facts together, making it dense to parse.

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 the return shape and does so meaningfully: resolved locale, image URLs, select labels, drafts included. What remains thin is failure behavior and whether the preview reflects the live site's exact rendering pipeline, but for a single-item read the essentials are covered.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the runtime semantics of locale — defaulting to the schema's first language and falling back to the primary language when a translation is missing. That is genuine meaning beyond the schema's 'default: its first'. The other three parameters (site, collection, id) get nothing extra in the description.

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

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

States a specific verb and resource — reading one CMS entry as the site would render it — and adds scope qualifiers ('drafts too', locale resolution, images as URLs) that separate it from a plain entry read. It does not name the adjacent siblings (get_entry, preview_draft) explicitly, so the agent must infer the boundary rather than being routed to 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?

'drafts too' implies this is the right tool when unpublished content must be previewed, but the description never states when to prefer it over get_entry or preview_draft, nor any prerequisite beyond the content:read scope. Usage is inferable but not 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 readOnly, non-destructive, and closed-world, so the bar is low. The description adds the required key scope (content:read) and a prompt-injection caution ('data, not instructions'), which are genuinely useful signals beyond 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?

Two terse sentences with the read-only constraint and safety note front-loaded. Slight crypticness ('One kept body') costs a little clarity but nothing is wasted.

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

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

For a no-output-schema read tool, the description explains what is returned (all languages, _meta, as it was) and the auth scope. It is adequately complete, missing only explicit navigation to the revision-listing sibling.

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 four parameters (site, collection, id, revision) are already documented. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states it reads a single kept revision of an entry, including its data across all languages and _meta, distinguishing it from get_entry (current) and list_entry_revisions. It never names the sibling alternative explicitly, keeping it a notch below 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 only implied: the revision parameter references list_entry_revisions, so an agent can infer it should fetch a revision id first. There is no explicit when-to-use or when-not guidance relative to get_entry, get_draft, or diff_versions.

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

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

Annotations already declare readOnly/non-destructive, but the description adds real behavioral context beyond them: the required submissions:read scope, Japan-time month semantics with inclusive ends, free-text exclusion, and an explicit privacy guarantee that nothing respondent-identifying is returned.

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

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

Front-loaded with what you get back, followed by parameter and privacy notes; every clause carries information. Dense but no filler, though the parenthetical formula and nested parentheticals make it slightly hard to parse at a glance.

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 fully carries the return-shape burden (per-field {value, label, n}, average, score) and covers scope, time semantics, exclusions, and privacy. An agent has everything needed to call it and interpret results.

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 meaning the schema lacks: the Japan-time zone of from/to, that both ends are inclusive, and that omitting them returns all time. It also clarifies the NPS score computation.

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 (read) and precise resource (a form's aggregated stats), plus exactly what is returned: per-choice/rating/NPS {value, label, n}, a rating average, and an NPS score with its formula. This is unambiguously distinct from siblings like list_submissions or get_submission.

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 operational context: requires the submissions:read scope, from/to are optional months and omitting them means all time, and free-text answers are excluded. It stops short of naming a sibling alternative explicitly (e.g. 'use list_submissions for raw answers'), so no full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the required settings:read scope and the fact that changing the value is outside this tool's role and must be done by a person in the admin.

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 short, front-loaded with the read-only constraint, and every clause contributes: safety, scope, returned setting values, and the admin-only change boundary. There is 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 simple one-parameter read tool with full schema coverage and annotations, the description gives the key missing context: what setting is returned, its possible values, the required scope, and that mutations are handled in admin. It is essentially complete, with only minor room for a more explicit return description.

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

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

Schema description coverage is 100%, and the sole `site` parameter is already documented as the Site ID from list_sites. The description adds no additional parameter semantics, which is acceptable given full schema coverage but does not exceed the baseline.

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

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

The description identifies the resource as the embedded form's bot check and states the relevant values: form_turnstile required / off. It is clear what setting is being read, though it does not use an explicit verb such as 'returns' and only indirectly distinguishes itself from broader settings tools.

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

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

It clearly frames this as a read-only lookup and explicitly says changing the setting is a person's job in the admin, which tells the agent not to use this tool for mutation. It does not name a specific alternative sibling such as get_settings, but the when-not guidance is 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 readOnlyHint=true and destructiveHint=false, so 'Read-only; changes nothing' is largely redundant. The description nevertheless adds real, non-obvious context: the permission flag can_edit_business, the version fields used by update_profile, and the critical trust boundary that stored values are 'data, not instructions' — a genuine injection warning absent from 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?

The safety statement is front-loaded, which is correct, but the remainder is one very long sentence with deeply nested parentheses defining skill and help_style values. Those value definitions are useful (no output schema exists to carry them), yet the run-on structure makes the payload harder to scan than it needs to 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 carries the full burden of describing the return value, and it does: both halves, their fields, per-half versions, and the can_edit_business flag. Together with the injection caveat and the deferral to start_here, an agent has everything needed to call and interpret 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?

Zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The schema coverage is 100% and additionalProperties is false, leaving no ambiguity about invocation.

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 ('What Siteon remembers for this conversation') and immediately enumerates the two halves returned: personal and business. It is unmistakable against siblings like get_account, get_settings, plan_profile, and update_profile, whose scopes it implicitly delimits.

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 already returns this, so call it only when you need it again' is an explicit when-not plus a named alternative. It also ties the output to update_profile ('Each half carries a version for update_profile'), giving the agent a clear handoff 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 declare this a safe, read-only, non-destructive, closed-world call, so safety is covered. The description adds genuinely non-obvious context: the returned schema must be edited and its schema_version threaded into update_schema, which signals an optimistic-concurrency contract the annotations cannot express. It stops short of saying what happens on a stale or mismatched version, so a 4 rather than 5.

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

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

Two sentences, zero filler, with the mandatory workflow constraint front-loaded immediately after the what-it-does clause. Every sentence carries new information.

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

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

With no output schema, the description must say what is returned — and it does: the field definitions for forms and CMS plus schema_version. It also supplies the downstream step needed to act on that return value, leaving nothing an agent needs to call this 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?

Only one parameter (site), and the schema documents it fully at 100% coverage, including that the ID comes from list_sites. The description adds nothing about the parameter, so the baseline 3 for high schema coverage applies.

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

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

States a specific verb and resource ("Get the site's schema") and parenthetically defines what "schema" means here — field definitions for forms and CMS — which disambiguates it from sibling concepts like entries or settings. It also names the second returned value, schema_version, so the agent knows exactly what comes back.

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 prescriptive rule ("Always call this before changing the schema") and names the alternative it pairs with (update_schema), including the read-modify-write sequence to follow. There is no ambiguity about when to reach for this tool versus update_schema.

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, yet the description still adds permission scope (settings:read), a data-redaction guarantee (Slack URL is masked and never returned), and sentinel value semantics (site_locale null = inherited from schema). These are non-obvious behavioral facts an agent could not get from 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 the verb and resource, then dense field enumeration with no filler; every clause carries information. It is one long nested-parenthetical sentence, which is slightly harder to scan than a short list would 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 carries the burden of describing returns and does so field by field, plus auth scope and redaction behavior. Nothing material is missing for a one-parameter read tool.

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

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

Schema coverage is 100% and the single `site` parameter is already documented as a Site ID drawn from list_sites, so the description adds nothing beyond it. Baseline 3 applies when the schema does all 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 ("Read the site's settings") and immediately enumerates the concrete fields returned (staff_mail, auto-reply text, GTM, form_turnstile, site_locale). It explicitly rules out mutation, which separates it cleanly from the sibling update_settings.

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 "Changing them is not possible with this tool" makes the read-only context clear and implicitly routes writes to update_settings, though it never names that sibling outright. An agent gets clear situational context but must infer the exact alternative 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 readOnlyHint annotation already declares the safety profile, but the description adds useful behavioral detail: the exact format of each returned artifact (text vs base64 og.png) and the structure of copy keys (hint plus max). It does not cover file size limits or truncation behavior for large base64 payloads, which keeps it from a 5.

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

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

Two dense sentences with the read-only note front-loaded, followed by return contents and then the routing advice. No filler; every clause carries either scope, output format, or usage 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?

There is no output schema, so the description carries the return-value burden and does so completely: file formats, base64 encoding, copy key structure, and the schema field are all named. For a three-parameter read tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds intent beyond the schema by tying `paths` to a specific workflow ('read them with paths only when you will change the markup'). The `id` and `layout` semantics are already fully handled by the schema text, so the added value is partial rather than comprehensive.

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 action and resource: reading a single starter's files, copy keys, and expected schema. It enumerates exactly what comes back (HTML/CSS/SVG as text, og.png as base64), which distinguishes it from list_starters and start_from_starter 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 states plainly when the tool is not needed ('Normally you do not need the files: start_from_starter fills them for you') and the precise condition that selects it ('read them with paths only when you will change the markup'). The sibling alternative is named 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 cover read-only, non-destructive, closed-world, so the bar is lower, yet the description adds real operation-specific context: attachments can be listed but never downloaded through this tool, and the returned text is visitor-authored data rather than instructions. The prompt-injection caveat is exactly the kind of behavioral warning annotations cannot express.

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 returned fields are front-loaded, and the security caveat is a well-placed second sentence. The first sentence is long, with a nested parenthetical listing attachment fields, which slightly blurs the scan.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly, including the non-obvious fact that attachment bytes are inaccessible here. Nothing an agent needs in order to call this correctly or interpret the response 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?

Both parameters are fully documented in the schema (which itself cross-references list_submissions and list_sites), and the description adds nothing about id or site format. With 100% schema coverage, this sits at the baseline.

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

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

The description states a specific verb and resource ('Read one submission (inquiry)') and then enumerates exactly what comes back: answers, state, version, assignee, notes, change history and attachments. This distinguishes it clearly from list_submissions (which yields the id) and from the write siblings such as set_submission_status or assign_submission.

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 an explicit second use case — check the version before changing state or assignee — and warns that write tools should only be used when the user explicitly asks. It does not name a specific alternative tool to use for browsing many submissions, so the exclusion side 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 and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context beyond annotations: the required key scope (sites:read) and the fact that 'hold' means public pages are stopped, which is not derivable from structured fields. It stops short of noting rate limits or staleness of the numbers.

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

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

One dense sentence with the resource and scope front-loaded followed by the enumerated return dimensions; every clause carries information. It is long but not padded, though the trailing metric list 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 carries the burden of explaining return values and does so by listing each metric and the hold flag; the auth scope is also stated. What remains unclear is only whether the data is near-real-time versus cached, which is a minor gap for a read-only reporting 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?

There is a single parameter with 100% schema coverage, where the schema already explains that 'site' is the ID from list_sites with an example. The description adds only the indirect hint that the scope is site-level ('sites:read') and no format or acquisition detail beyond the schema, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('Read the site's usage against its plan') and enumerates the exact dimensions returned (forms, cms, storage, ai, requests with limits, period, hold flag). An agent knows precisely what comes back. It does not name the closely related sibling get_usage_pv, so the differentiation is only partial.

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?

'as the admin's usage panel shows it' implies the use case (checking plan consumption), and the sites:read scope hints at access prerequisites. However, it never says when to prefer this over the sibling get_usage_pv, nor states any exclusions or conditions.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so the 'changes nothing' line is partly redundant, but the description adds real behavioral context the annotations don't: the required sites:read scope, Tokyo-date day boundaries, and the pv-null-on-no-data return behavior. It doesn't cover rate limits or caching, 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, front-loaded with the safety signal and then the returned data. Slightly dense with parenthetical date/scope clauses, but every clause carries information an agent needs.

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

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

With no output schema, the description usefully names the return values (daily pv series plus this month's total) and the null case. Combined with a fully documented 2-param schema and explicit annotations, it's sufficient, though it doesn't explain the pv units or how the monthly total relates to the series.

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 3 is the baseline, but the description adds meaning beyond the schema: the 1-90 range for days, the 30 default, and that dates are Tokyo-based. It still leaves the exact format/interpretation of month-total untouched, so a 4 rather than 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?

Names a specific resource and scope: the site's daily page views as shown in the admin graph, plus this month's total. An agent knows exactly what it returns. It does not differentiate itself from the sibling get_usage, which plausibly overlaps, 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?

Usage is only implied by 'Read-only; changes nothing' and the sites:read key scope, which tells the agent this is a safe read for a given site. There is no explicit statement of when to prefer this over get_usage or other usage/analytics siblings, and no 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new behavioural context: the required 'content:read' key scope and the structure of the returned map including _meta with manual/pending/error status flags. That status-flag detail tells an agent how to interpret partially-translated or unpublished values, which no annotation conveys.

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

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

One front-loaded sentence: verb and resource first, then the scope, then the return shape. The inline JSON sketch is dense but every element (group.field keys, locale values, _meta flags) carries information; nothing is padding, though the notation is terse enough to need a second read.

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 spends its budget describing the return shape, including the _meta status sub-object. For a single-parameter read tool this is close to complete; only the absence of any pointer to the write-side sibling or to when values might be missing keeps it short of full marks.

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 'site' parameter is fully documented in the schema (including the list_sites pointer). The description adds nothing about the parameter itself, so this sits at the baseline where the schema does all 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 ('Read') and resource ('the site's group values'), and the return-shape sketch makes clear it reads keyed group/field data. It does not name the obvious sibling counterpart set_values, so the read-vs-write contrast is left to inference from the verb.

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 'use this when...' clause and no named alternative, though the read framing against the sibling set_values is implied. The only usage-shaped hint is the required key scope, which tells the agent what credential it needs rather than when to pick this tool.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, yet the description still adds real value: the required key scopes (deploy:write or sites:read), the hard limit of 3 subdomain changes per month, and the notion of a stopped state with suspended/hold_kinds. 'Read-only; changes nothing' merely restates the annotations, but the scope and limit details go beyond them.

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

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

It is a single dense sentence with the safety statement front-loaded and the returned fields listed in order. The parenthetical scope and limit asides are efficient, though the telegraphic style ('suspended, hold_kinds') makes it slightly harder to parse than necessary.

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

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

With no output schema, the description carries the burden of describing return content, and it does enumerate the fields an agent will get back. Combined with the auth scopes and the monthly limit, an agent has enough to call it correctly; only the relationship to sibling hosting tools 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?

There is a single parameter with 100% schema description coverage, and the schema already explains that 'site' is the id from list_sites (e.g. "my-shop"). The description adds no format or sourcing detail beyond that, 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 enumerates exactly what the tool reports about a site's hosting: serving state, subdomain and URL, live version, monthly subdomain-change usage, and suspension state. That is specific enough for an agent to recognize it as a hosting status read. It stops short of naming the sibling it differs from (hosting_subdomain), so it lands at 4 rather than 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 only implied: an agent can infer it should call this to inspect hosting before deploying or changing a subdomain, but the description never states when to use it, when not to, or how it relates to hosting_subdomain or fetch_site. The scope note (deploy:write or sites:read) is authorization context, not selection 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?

Goes well beyond the annotations: discloses that the old address stops working immediately with no redirect and that distributed links/QR codes break, plus the 3-per-month rate limit, the rate_limited failure mode, and the deploy:write / owner-admin auth requirement. Note a mild tension with destructiveHint=false given the irreversible breakage, but the description is not contradictory — no data is destroyed — and it supplies the risk context the annotation omits.

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 its consequences, then rate limits, then the confirmation workflow, then alternatives — a sensible order. It is long, and the bracketed generic block ("This tool changes data or sends notifications") is boilerplate that only loosely fits a subdomain rename.

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-required-parameter mutation with no output schema, the description covers impact, reversibility, preconditions, rate limits, consent, and the unpublished-site alternative. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning on top: confirm is a consent gate tied to a specific user-confirmation workflow, and subdomain only applies to already-published sites. That workflow context is not in 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: "Change the site's subdomain on the hosting domain," and immediately scopes it to the hosting domain rather than a custom one. It also distinguishes itself from publish_draft's subdomain parameter and the CLI equivalent, so an agent can route correctly among siblings.

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

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

Gives explicit when-to-use rules: only when the user explicitly asks, tell them the old and new address, get an explicit yes, then pass confirm: true. It also covers the negative case (unpublished site has no address yet) and points to the right alternative — publish_draft's subdomain on the remote connector, or the CLI 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 already cover the read-only, non-destructive profile, and the description adds real context beyond them: the required content:read key scope and the newest-first ordering. It stops short of stating whether results are filtered by type (images vs files) or how paging terminates.

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 the resource and ordering front-loaded, followed by pagination details. The returned-field enumeration is justified because there is no output schema, though it makes the sentence 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?

For a simple three-parameter read tool with no output schema, the description covers scope, ordering, returned fields, and paging adequately. Minor gaps remain around whether there's a total count for paging and whether asset type filtering is possible.

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 site, limit, and offset are already fully documented in the schema. The description restates the limit bounds and default and frames offset as paging, but adds no syntax or semantics beyond the schema baseline.

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

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

States a specific verb and resource ('List the site's uploaded images and files') plus ordering ('newest first'), which clearly separates it from entry/form/submission listing siblings. The returned field list further pins down what an 'asset' 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?

Usage is implied by the resource description, and the 'key scope content:read' note signals the prerequisite. However, it never says when to prefer this over adjacent tools such as read_draft_file, request_upload, or write_files, leaving the agent to infer.

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

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

Annotations only cover safety (readOnly, non-destructive), but the description adds the required auth scope, the order and exact shape of returned fields (id, status, sort, data with _meta per language, published_at, asset_urls), the default page size, and an explicit prompt-injection warning that entry text is data, not instructions. That is substantive behavior an agent cannot get from the annotations or schema.

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

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

Front-loaded with purpose and scope, then filters, then return fields, then the safety note — a logical ordering with essentially no filler. The return-field enumeration makes the middle dense, but given there is no output schema each item 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 supplies the return shape, ordering, pagination defaults, auth scope, and a data-vs-instructions safety cue. An agent has everything needed to call and interpret this 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 description coverage is 100%, so the baseline is 3. The description restates limit bounds/default and the status enum, adding only the notion of paging through an ordered result set — useful but marginal beyond the schema.

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

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

States a specific verb and resource ("List the CMS entries of a collection") and is immediately distinguishable from get_entry, list_entry_revisions and reorder_entries by scope. No agent would confuse this with a single-entry read or a revision listing.

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

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

Explains how to use the tool operationally: status narrows to drafts or published, limit/offset page through results, and the required key scope content:read is stated up front. It stops short of naming a concrete alternative (e.g., 'for a single entry use get_entry'), so it is clear context without explicit exclusions.

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

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

Annotations already declare read-only and non-destructive behavior, but the description adds meaningful context: the required content:read scope, plan-dependent retention of 5 or 50 revisions, newest-first ordering, and a prompt-injection warning about user-authored text. It does not describe pagination or error behavior, but the behavioral additions are substantial.

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

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

The description is compact and front-loads the read-only scope, then moves through returned fields and the safety note. It is somewhat dense and semicolon-heavy, but every sentence carries useful information.

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

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

With no output schema, the description carries the return-value burden and does list the key fields, ordering, and current_version. It is nearly complete for this list tool, though the terse get_entry_revision reference is not fully elaborated.

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 all three parameters are documented in the schema with clear descriptions. The tool description does not add parameter-specific semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states that this tool lists an entry's historical saved revisions, including ordering, retention, and returned fields. It also names the sibling get_entry_revision, though the routing sentence is terse and could be sharper about what data lives where.

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 useful context with the read scope, newest-first ordering, retention limits, and a pointer to get_entry_revision. However, it does not explicitly say when to use this tool versus that sibling or when not to use it, so the usage guidance remains implied rather than directive.

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 safe, read-only operation. The description adds useful behavioral context by enumerating returned fields and explaining the public-page null case, though it does not mention ordering, permissions, or pagination.

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

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

The definition is a single front-loaded sentence with no wasted text. The parenthetical return-field list is dense but purposeful and easy to scan.

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 list tool with no output schema, the description is complete enough: it names every returned field and handles the null public-page case. It omits ordering and pagination details, but complexity is low and those gaps are unlikely to 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?

Schema description coverage is 100% and there is only one required parameter, site, which the schema defines with a concrete example. The description does not add any parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: "List the site's forms," and immediately clarifies the returned fields. This is clear, but it does not explicitly distinguish the tool from nearby siblings such as get_form_stats or list_submissions.

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

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

Usage is only implied by the verb "List" and the scope "the site's forms." There is no explicit when-to-use guidance, no exclusions, and no named alternatives such as get_form_stats for aggregated metrics.

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 the opening 'Read-only; changes nothing' is redundant. However, the description adds behavior annotations do not carry: the required sites:read scope, the site_restricted_key exclusion, and the guarantee that no e-mail is ever returned and name may be null.

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, and the access restriction is placed last where it belongs as a precondition. The only waste is the first clause restating what the annotations already declare.

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 describe the return shape, and it does — user_id, name, role with the role enum, plus the nullability rule for name and the absence of e-mail. Combined with the access caveat, nothing needed to call or interpret the result 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?

Zero parameters, so the baseline is 4. The description still adds meaning about the calling context by documenting the required key scope and which key types are rejected, which is the only parameter-like constraint this tool has.

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

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

It states the resource and its scope precisely: 'The account's members', followed by the exact fields returned (user_id, name, role) and the role enum. That implicitly separates it from site-level siblings like site_members, but it never names that alternative, so an agent must infer the account-vs-site 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?

The access constraint ('Not available to a key limited to some sites') implies when the call will succeed, but there is no guidance on when to prefer this over site_members or get_account. Usage is only inferable from the scope wording.

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 behavior beyond that: the concrete fields returned (id, name, plan, allowed_origins, editable) and the key semantic that the id is 'the value to pass as site to the other tools', which is non-obvious plumbing information.

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 waste, front-loaded with what the tool lists before moving to the returned fields and the call-order hint. 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?

With no output schema, the description usefully enumerates the returned fields and their downstream meaning, which is what an agent needs to chain into site-scoped tools. It stops just short of fully exhaustive return coverage (e.g., ordering or pagination behavior is unstated), keeping it at a strong 4.

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 to disambiguate and the baseline is 4. The description does not need to compensate for any schema gaps since schema coverage is 100% and the object is empty.

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 ('List the Siteon sites') plus an explicit scope ('in this API key's account'). It also names the fields each record carries, so the agent knows exactly what this returns versus the single-site sibling fetch_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?

'Call this first to find the site id' gives a clear entry-point instruction and explains why an agent would reach for this tool before others. It does not explicitly name fetch_site as the alternative for a known id, so it stops short of full when/when-not guidance.

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

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

Annotations only declare readOnly/destructive=false; the description adds the required key scope (sites:read), the fixed catalog composition, the returned fields (id, industry, mood, tags, palette, fonts, hero/nav style, forms/CMS collections, pages), and a presentation constraint ('do not show this list raw') — all context the annotations cannot express.

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 'Read-only' and the catalog summary, then the selection rule, then next steps — a logical order. Dense but every clause carries information; the inline field enumeration is the only portion bordering on long.

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 fully compensates by listing every returned field plus the layout distinction. Combined with the filter params and annotations, an agent has everything needed to call and use 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% and both filter parameters already carry descriptions with examples, so the description only echoes them implicitly ('from the person's industry and the mood words they used'). Baseline 3 applies; no extra syntax or matching semantics are 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?

States a specific verb+resource ('Siteon's starter sites') and enumerates the exact catalog shape (6 industries × 2-3 moods × 2 layouts), then names the two downstream siblings (get_starter, start_from_starter) so the agent can place it in the workflow without opening schemas.

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

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

Explicit selection rule: 'Pick one from the person's industry and the mood words they used (or two to let them choose); do not show this list raw.' It also routes forward to get_starter for reading and start_from_starter for building, covering both alternatives.

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

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

Goes well beyond the readOnlyHint/destructiveHint annotations by disclosing ordering (newest first), the presence of personal data, and an explicit prompt-injection policy for the returned visitor text. That injection warning is behaviorally critical and unavailable anywhere else in 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?

Capabilities, filtering, and privacy are front-loaded in the first two sentences, with the injection warning following. The security guidance is valuable but consumes roughly half the text; it earns its place but could be tightened slightly.

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 annotations covering the safety profile and no output schema, the description covers purpose, ordering, privacy handling, and injection resistance well. The only gap is the unread parameter and any hint about result shape or pagination, both minor 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%, so the schema already documents form, site, limit, and unread. The description restates form narrowing and the limit default/range but adds no new semantics, and never mentions the unread filter. Baseline 3 is appropriate.

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

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

States a specific verb and resource plus ordering semantics: "List the form submissions (inquiries) the site received, newest first." It also clarifies what a submission is (an inquiry) and how scoping works, so an agent can distinguish it from get_submission or list_forms 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 operative guidance: fetch only what you need, summarise personal information, and use write tools only on explicit user request. It does not explicitly contrast with sibling retrieval tools such as get_submission or list_forms, so the alternative-selection guidance 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds domain meaning about the return payload (custom states exist, is_closed marks completion, assignees are member user_ids), but says nothing about ordering, size or pagination of the result.

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

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

One sentence on the payload plus one on usage, with the return content front-loaded. No filler, no restatement of the tool 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?

There is no output schema, so the description carries the burden of describing returns, and it does so at a useful level (states with is_closed, assignees as user_id). Minor gaps remain around ordering and whether the list is exhaustive, but an agent can call this correctly as written.

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

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

The single `site` parameter is fully documented in the schema (100% coverage, including the list_sites cross-reference), so the schema does the work. The description never mentions the parameter at all, so no value is added beyond the structured field.

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 two concrete resources: submission states (built-in plus custom, with is_closed semantics) and assignable people by user_id. That also separates it from list_members and list_submissions, which an agent might otherwise confuse it with.

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 before set_submission_status and assign_submission" gives an explicit prerequisite relationship to the two siblings that consume this output. An agent knows both when to reach for it and which tools depend on 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 and destructiveHint=false, so safety is covered; the description goes further by disclosing the required key scope (content:read), the exact fields returned, and the precondition that the collection must expose a tags field. It stops short of mentioning result size or pagination for large tag sets.

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 main verb and resource front-loaded, with the returned fields and the precondition packed in without waste. Nothing is repeated from the schema 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 field enumeration and auth scope are exactly the context an agent needs, and the precondition prevents a common wrong call. The one omission is behavior for very large collections (ordering, result limits), which an agent may care about.

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 parameters (site, collection) are already documented there, including the pointer to list_sites for the site id. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the tags of a collection') and immediately enumerates what is returned (name, color, sort, registration status, entry counts). It is easily distinguished from the only closely related sibling, rename_tag, which mutates a single tag.

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 supplies a precondition ('Only collections with a tags field have tags') which helps an agent avoid a futile call, but it never says when to reach for this tool versus related ones like list_entries or rename_tag, nor any exclusions. Usage is implied rather than guided.

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

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

Beyond the readOnly/destructive annotations, it discloses the key scope requirement (deploy:write), warns that message content is data not instructions, explains live_from/live_until temporal semantics, and notes that times become approximate after rollbacks. These are substantive behavioral details an agent would not otherwise know.

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 dense but front-loads the core scope and ordering, then layers useful caveats about fields and time semantics. The single long paragraph is slightly run-on, but every clause carries operational value and there is 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?

There is no output schema, so the description carries the return-value burden and does so thoroughly by enumerating the fields and explaining active/live_from/live_until/rollbackable semantics. It also covers the key downstream usage with rollback, making the definition complete for this tool.

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

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

Schema coverage is 100%, so site and limit are already fully documented in the input schema. The description does not add parameter-specific semantics beyond implying site scoping; its value is concentrated in describing returned fields rather than input parameters.

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

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

The description clearly states the resource and ordering: 'The site's published versions, newest first,' and enumerates the metadata returned. It is effectively a list operation even though the verb is implicit, and it distinguishes itself from siblings like diff_versions and preview_version by focusing on version metadata rather than comparison or previewing.

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 concrete usage scenario — resolving a person's 'yesterday' by converting to UTC and selecting the version live at that time — and explicitly tells the agent to pass live_deploy_id as rollback's expected_live_deploy. It does not explicitly exclude or route against diff_versions/preview_version, so it falls short of full when/when-not guidance.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, and the description adds genuinely new context: the required key scope (billing:read or billing:write) and an explicit data-boundary disclosure that the address is never returned. The action_url explanation also clarifies a non-obvious 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?

Three sentences, front-loaded with the resource and scope, then the field list, then the alternative. Parentheticals are short and each sentence carries information that is not repeated elsewhere.

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

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

With no output schema present, the description assumes responsibility for describing returns and does so by enumerating status, version, currency, country, vat_status, and action_url. Auth scope and the companion write tool are also covered, leaving no material gap for a zero-parameter read.

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 no parameters, so the schema baseline is 4 and there is nothing for the description to compensate for. The description correctly does not invent parameter guidance.

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 and resource ('Read this account's billing profile') and then enumerates the exact fields returned, so an agent knows precisely what comes back. It also names the mutating counterpart, plan_profile_update, which distinguishes it from siblings like get_profile and plan_status.

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 the use case (reading the billing profile), names the alternative tool and the condition selecting it ('To change it, use plan_profile_update with the version read here'), and warns that the address is out of scope. An agent needs no further inference to choose correctly.

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), yet the description still adds real value: the required auth scope (billing:read or billing:write), the meaning of cap_jpy including the fallback behavior when unset (owner approves every time), and the fact that pending approvals come with URLs. What it lacks is any note on data freshness, failure modes, or cost of the call. The parenthetical about cap_jpy is also internally tangled ("before tax, the monthly contract total"), which blunts the disclosure.

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 purpose and followed by the actionable directive; nearly every clause names a distinct returned field, so the length is earned. The cap_jpy parenthetical is dense and hard to parse in one read, which is the only structural weakness.

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 parameters and no output schema, the description carries the full burden of explaining what comes back, and it does so by enumerating each returned element including approval URLs and the price list. Combined with the auth scope and the follow-up instruction, an agent has everything needed to call it and act on 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies the call is scoped entirely by the authenticated account rather than by any argument.

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 and resource ("Return this account's billing state") and enumerates exactly what is returned: contract existence, per-site plans and amounts, AI cap, contract total, pending approvals, and the price list. An agent can tell this is a read of billing/plan data. It does not distinguish itself from the closely related siblings plan_status and plan_profile, which is the main clarity gap.

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 sequencing guidance: "Call it before plan_set and tell the user how much it will increase," which tells the agent both when to call it and what to do with the result. However, it offers no guidance on choosing between this and plan_status/plan_profile, which appear to overlap, and plan_set is not even present in the sibling list, so the referenced alternative cannot be cross-checked.

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 past the readOnlyHint annotation by naming the required key scope (billing:read or billing:write) and the non-blocking behavior ('It does not wait: call again after a while'). It also enumerates the observable states and the recovery_url surfaced on action_required, which is exactly the behavior an agent needs to plan around.

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 read-only and scope, then the return values, then the action guidance. The parenthetical state enumerations are long but functional since there is no output schema. Every sentence carries information, though the nested parentheses make it denser than ideal.

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

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

With no output schema, the description carries the return-value burden and does so: it lists all request and contract states and mentions recovery_url. Combined with the deployment gate and polling instruction, an agent has everything needed to call and interpret 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 coverage is 100%, so both parameters are already documented, including the default-to-latest-request behavior the description repeats. The description adds the provenance link (request_id that plan_set returned), which is mildly useful, but no format or edge-case detail beyond the schema.

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

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

States a specific verb and resource pair: returns request state and the site's contract state, plus the key constraint. It is clearly distinct from plan_show/plan_profile in content, though it never names a sibling to contrast with, 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?

Explicitly says to omit request to get the latest, what to do once applied (you can deploy), what to do on action_required (hand recovery_url to the user), and that it doesn't wait so it must be re-called. Missing only an explicit 'use plan_show instead when...' comparison, but the polling and follow-up guidance is strong.

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?

Discloses extensive behavior beyond annotations: deploy:write scope, separate 24-hour address, exact live rendering, test-only form submissions with no mail/Slack/webhook, returned checks/manifest_sha256/publish_idempotency_key, and subdomain constraints. It also clarifies that the preview address is distinct from the site address.

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