Ginta

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

Annotations already declare non-read-only, non-destructive, non-idempotent, open-world. The description adds real behavioral context beyond them: it copies (persists) the image into the account rather than referencing it, and returns a storage path for embedding in HTML or module data. It omits auth requirements, dedup/idempotency nuance, and size limits referenced only in the schema.

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

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

A single front-loaded sentence that opens with "Use for", states scope, then mechanics and return value. No filler or repetition.

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

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

Output schema exists so return values need not be explained, yet the description still names the returned path format. The one gap is that the schema marks zero required parameters while the description implies exactly one of url/data_base64 must be supplied, and that requirement is not clarified.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description restates the url-or-base64 choice, which the schema already conveys with "instead of url"; it adds no extra syntax, constraints, or precedence rules.

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 (copies), resource (one image, public link or base64), target (their account), and outcome (returns a /_g/u/… path). The scope phrase "owner's own photos and logo" separates it from the generic sibling upload_files.

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?

States where to use it (business sites and module content such as menu, shop, gallery, blog) and restricts it to the owner's own assets, which implies rather than names the contrast with upload_files. No explicit when-not or prerequisite conditions are given.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world behavior, so the bar is low. The description adds real behavior beyond them: it returns suggested alternatives when the name is taken and it normalizes input ("Bella Roma" -> "bella-roma"), which the 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?

A single sentence that leads with the usage trigger, then the output format, then the normalization rule. No filler and every clause carries information.

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

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

With a rich annotation set, an output schema, and a single fully documented parameter, the description only needs to add the ordering constraint and normalization behavior, which it does. Nothing needed to call this tool correctly is missing.

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

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

Schema coverage is 100% and there is only one parameter, so the baseline is 3. The description goes further by showing how the name string is interpreted and transformed during normalization, adding meaning the schema's "Wanted name" text does not convey.

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

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

States a specific verb and resource (check whether a site name is available) and ties it to the concrete output address pattern https://<name>.ginta.page. It is clearly distinguishable from siblings like create_site or get_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?

Gives an explicit trigger and ordering: use before create_site when the user wants a specific address. It does not state when the check is unnecessary (e.g., auto-generated names) or name an alternative tool, but the sequencing guidance is clear and actionable.

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

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

Goes well beyond the annotations (which only say non-read-only, non-destructive, open-world). It discloses the returned DNS record set, the critical gating rule that the site is not served until the TXT proof record is seen, and the enumerable statuses pending/verifying/active — exactly the operational context an agent needs before calling.

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 trigger condition and kept to a single, information-dense sentence with no filler. It is slightly run-on due to stacked parentheticals, but every clause 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?

Despite having an output schema, the description still conveys the return shape (DNS steps, status values, HTTPS reachability) and the verification dependency. Nothing needed to call this two-mode, 3-parameter tool correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains the present-vs-absent semantics of `domain` as the mode switch and that `with_www` governs which address is primary and which redirects. That goes past the schema's field-level text.

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

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

States a specific action pair on a specific resource: connecting the user's own domain to a site, or checking its current status. The dual-mode framing (with vs. without `domain`) leaves no ambiguity about what the tool does, and the example domain makes the outcome concrete.

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?

Opens with an explicit trigger: 'Use when the user wants their own domain ... on a site, or asks whether it works yet', and maps each mode to its invocation condition (supply `domain` to connect, omit it to check). No alternative tools are named or excluded, so it stops just 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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: a 1–3 minute build latency, the URL return, and a content constraint ('Pages should hold only real details the user gave'), which guards against fabricated reviews/prices. No auth or rate-limit context is given, hence 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?

Three dense sentences with the core action, its output, latency and a prerequisite front-loaded before the file/upload branch and the note requirement. Minor style slip ('note is required' starting a new sentence in lowercase) but no wasted 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?

An output schema exists, so return-value detail is unnecessary, and the description still surfaces the most decision-relevant outcomes (URL, build time). It covers the two invocation modes and the required note, though it omits any guidance on failure/validation behavior for a non-idempotent publishing 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 name, note, files, fonts, layout, aesthetic and notify_email in detail. The description mostly restates schema facts (note required, index.html required, omitting files yields an upload link) rather than adding new parameter meaning, 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 ('Publishes a NEW website in the user's account'), plus the observable outcome ('returns its URL'), which implicitly separates it from update_site and preview_site. The 'NEW' qualifier and the reference to get_guide give the agent enough to place it in the workflow without opening another schema.

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

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

Gives clear context and a decision branch: pass designed files (index.html required, see get_guide) or pass no files to receive an upload link for a build. It names get_guide as a prerequisite but never warns the agent to use update_site instead when the site already exists, so the sibling exclusion is left to inference.

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

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

Annotations already establish readOnly, idempotent and non-destructive behavior, so the safety profile is covered. The description adds useful semantic context about what the 'developers' and 'modules' topics actually contain, plus the default scope. It doesn't describe output shape, though that is partly mitigated by the presence of an output schema.

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

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

Three short sentences with the core purpose front-loaded and the parameter clarification trailing. Efficient overall, though the phrase 'the live parts' for 'modules' is vague enough to be worth sharpening.

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

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

For a single optional enum parameter with an output schema, the description covers purpose, timing and parameter meaning adequately. The topic list in prose ('design brief, functional blocks and SEO') does not fully enumerate the enum (editing, all), leaving a small gap.

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

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

Schema description coverage is 100%, and the enum values carry the parameter. The description goes beyond the schema by explaining the meaning of two opaque enum members ('developers' = file uploads, builds, redirects and API connections; 'modules' = the live parts), which is real added value for the remaining undocumented values such as 'editing'.

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

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

States a specific verb and resource ('Returns Ginta's building guide') and enumerates the content it covers (how sites work, design brief, functional blocks, SEO). This is clearly distinguishable from every sibling, which operate on sites, messages, stats or domains rather than documentation.

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 before building or editing a site' gives a clear triggering condition. It stops short of naming an alternative or stating when not to call it, but the context of use is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that: it discloses default ordering ('newest first') and that the records contain visitors' personal data belonging to the site owner, which signals sensitivity and expected access scoping.

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

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

A single dense sentence that front-loads the usage trigger and packs purpose, provenance, ordering and data sensitivity without filler. Every clause earns its place.

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

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

With an output schema present, return values need not be described, and the description covers purpose, trigger, ordering and data sensitivity. It omits any note on pagination or the 200-item cap, which is minor but the one remaining gap for a 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 both site_id and limit are fully documented in the schema; baseline is 3. The description adds only the ordering hint, not additional syntax or format detail for limit or site_id.

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 (form messages / enquiries / contact requests sent by visitors) together with scope (the site's forms) and ordering (newest first). An agent can distinguish this from siblings like get_stats or get_site without opening the schema.

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

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

The description explicitly names the trigger condition — 'Use when the user asks for their form messages, enquiries or contact requests' — and maps several plausible user phrasings onto the tool. It stops short of naming alternatives or exclusions (e.g. when to use a different retrieval path), so it is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds real behavioral context the annotations cannot: what is returned for text vs binary assets, that history surfaces the last 20 versions for restore_version, and that full reads may be size-limited ("if the site isn't too large"). The trailing Ginta UI .zip note is tangential but harmless.

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 usage trigger and return description in two tight sentences. The parenthetical about downloading a .zip from the Ginta website menu is extraneous to the tool's behavior and slightly dilutes focus.

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

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

Output schema exists, so return values need not be spelled out, yet the description still summarizes them helpfully. Combined with 100% schema coverage and non-destructive annotations, an agent has everything needed to invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by linking history:true to restore_version and clarifying that paths restricts the read to a subset of files. It doesn't add format or edge-case detail for paths beyond the schema's own limits.

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

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

States a specific verb and resource (returns a site's files and, with history, its saved versions) and details the return shape: text contents inline, images/fonts as a list of addresses. It is clearly distinguishable from siblings like restore_version, preview_site, and list_sites.

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

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

Gives an explicit when-to-use trigger ("Use before editing an existing site, or when the owner wants their code") and ties the history parameter to its downstream consumer, restore_version. It also tells the agent how to narrow scope with paths.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered. The description's only added behavioral fact is the 30-day aggregation window, which is genuinely useful scope information, but it discloses nothing about rate limits, auth, or freshness beyond that.

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

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

One front-loaded sentence that leads with the usage trigger before listing outputs; there is no filler. It is slightly dense with an embedded metric enumeration, but 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?

An output schema exists, so return values need not be re-explained, and the single required parameter is fully documented in the schema. The description supplies enough intent-matching context for an agent to select the tool correctly; only the absence of explicit alternatives keeps it from a 5.

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

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

There is a single parameter (site_id) with 100% schema description coverage, including a concrete format example ('bella-roma') and a pointer to list_sites. The description adds no parameter guidance, so the schema carries the full load and the baseline 3 applies.

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

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

The description states a concrete verb+resource ('how many visitors their site gets', 'how fast and well-built it is') and enumerates the returned metrics, so an agent can distinguish it from site-management siblings like get_site or list_sites. It stops short of explicitly naming an alternative, but the analytics framing is unambiguous.

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

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

It gives an explicit trigger: 'Use when the user asks how many visitors their site gets or how fast and well-built it is.' That maps user intent to the tool cleanly. There is no when-not guidance or named alternative, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful workflow context (this is the tool that yields a site_id) and mentions return content, but the output schema already carries the return shape.

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

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

Two tight sentences with the usage trigger front-loaded ahead of the content summary. Minimal waste, though the trigger sentence stacks several conditions that 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 parameters, complete annotations, and an output schema defining the return, the description only needs to establish purpose and routing — both are present. Nothing an agent needs to invoke this 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. No parameter-level claims are made or needed.

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

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

States a specific verb and resource ('Lists every site') and enumerates the returned content (URL, form message count, plan allowances). An agent can immediately distinguish this from the singular sibling get_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?

Gives clear trigger conditions ('need a site_id', or the user asks about websites, plan, limits, credits, page views), which is strong when-to-use guidance. It doesn't explicitly name a sibling alternative or an exclusion, 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 destructive=true and openWorld=true, so the bar is lower, yet the description adds real context: what admins can change (lists, menu, bookings, messages) versus what they never touch (design, code), and concrete password rules (owner-chosen or emailed invite, 8+ chars, never invent or repeat in chat). It does not, however, describe the consequence of the destructive remove action. This is useful added behavior 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?

The text is dense and mostly front-loaded, with the usage trigger first and action semantics after. It uses compact fragments ("add: ...", "set_password: ...") which are scannable, though the long capability sentence and run-on punctuation slightly reduce readability.

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

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

With an output schema present, return values are covered elsewhere; the description covers when to use, per-action meaning, password handling, and admin capability boundaries, which is sufficient for a multi-action mutation tool. The main gap is the absence of any note on the destructive remove behavior or required permissions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely enriches action semantics: it explains what each action does, the two modes of add (with a password vs. an email-invite), and that set_password can target the owner's own email. This adds meaning about parameter interplay beyond the schema text.

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

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

The description clearly establishes the resource (admin users who sign in at <website>/admin) and the operations via per-action notes (add, remove, set_password, send_setup_link, list). It is readily distinguishable from siblings like manage_secrets or manage_connections, though it never names a sibling to differentiate against. The opening frames usage rather than the action itself, leaving purpose slightly implicit.

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 trigger with a concrete example ("add maria@salon.lt as admin") and the situation that motivates it (after building a site with owner-filled parts). Per-action conditions are also described (add with/without password, set_password for admin or owner's email). No when-not-use or explicit alternative is stated, 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 readOnly=false, destructive=true, openWorld=true, and idempotent=false. The description adds useful behavior beyond that: Ginta injects the secret and forwards only to the configured base URL, and the list action reports connections plus this month's calls.

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 use case, then packs the save parameters, proxy path, and list behavior into two dense but efficient sentences. 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?

Given the rich input schema, output schema, and annotations, the description covers the main use case and behavior well. It omits the delete action from prose, but that is documented in the action enum, so the omission is minor.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds semantic value by explaining that the connection name becomes part of the fetch path and that the saved secret is attached automatically, though many individual parameters are left to the already-rich 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 clearly states the resource and core actions: saving a connection so a site's JavaScript can call an outside API, plus listing connections. It does not mention the delete action or explicitly distinguish itself from manage_secrets, though the use case is still easy to separate from most 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?

It gives a clear triggering condition: 'Use when the site's JavaScript must call an outside API.' It does not state when not to use the tool or name an explicit alternative, but the context is sufficient for selection.

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

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

Annotations blanket-flag this as destructive/non-idempotent, but the tool actually mixes safe reads (list, get) with irreversible writes (delete_item, delete_collection, delete_photo, cancel). The description enumerates those delete/cancel actions, implicitly signaling which are dangerous, but never states permissions, whether deletions are recoverable, or what the coarse destructive hint really applies to.

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 purpose is front-loaded in the first sentence, then the module/action matrix follows in a compact semicolon-delimited list. It is long but dense and non-repetitive; almost every token conveys valid values the agent must choose from.

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 mega-dispatcher with a nested free-form data object and an output schema (so returns need no explanation), the description supplies the module/action taxonomy and a discovery path (help) for the opaque payload. A little more on the data object's shape per module would make it fully self-sufficient.

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

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

Schema coverage is 100% so the baseline is 3, but the description arguably does more: it enumerates the valid module values and their per-module action verbs, and explains that the data object's fields must be discovered via action "help". That is meaningfully beyond the generic schema blurb.

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: "set up or change the live parts the owner manages," and enumerates the concrete domain (prices, bookings, products, posts, photos, events, quote requests, notices). An agent can tell this is the site-content administration surface, though it never explicitly contrasts itself with siblings like update_site or preview_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?

Gives operational instructions: use action "help" to see a module's fields, and omit module to see what the plan includes. It also maps each module to its allowed actions, which tells the agent what to pass. It stops short of stating when this tool should be preferred over a sibling, so no exclusions are given.

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

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

Beyond the annotations, the description discloses critical security behavior: values are stored encrypted, list shows names only, delete removes one, and values can never be read back by anyone. This is exactly the kind of write-only, destructive, non-retrievable behavior an agent must understand before invoking.

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

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

Two well-structured sentences: the first covers use case and per-action behavior, the second front-loads the irreversible write-only constraint and the alternative tool. Every phrase 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?

Given the annotations already cover safety hints, the input schema is fully described, and an output schema exists, the description supplies the remaining crucial context: write-only encrypted storage, no read-back, and the correct sibling for using the secrets. 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 100%, so baseline is 3. The description adds actionable meaning beyond the schema by clarifying that set stores encrypted values, list returns names only, and delete removes a single secret. It still does not discuss individual parameter constraints, but those are fully documented 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?

The description names the resource (API keys/secrets), the actions (set, list, delete), and the purpose (site needs an API key for weather, CRM, maps). It also distinguishes itself from manage_connections by stating that stored values can never be read back and must be used through connections instead.

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

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

It gives a clear when-to-use trigger ('when the site needs an API key') and explicitly routes key usage to the sibling tool manage_connections. The three actions and their effects are also described, so an agent knows which action to choose.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds context annotations cannot: a per-day quota that varies by plan and the prescribed behavior when the quota is exhausted. It does not say whether the screenshots are cached or how long generation takes.

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 sentence with zero waste: the trigger condition, the render specifications, the quota constraint, and the fallback all appear in tight, front-loaded order.

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

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

With an output schema present, the description need not describe return values, and annotations cover safety. It covers trigger, scope, viewport details, and quota, but leaves the quota-exhausted alternative tool unnamed, a small gap for an agent deciding what to call next.

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 (site_id format and the page default) are already fully documented in the schema. The description only adds 'one page', which is the schema default restated, so baseline 3 applies.

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

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

States a specific verb and resource — screenshots of one page — and specifies the two viewports rendered (desktop 1280 px top-to-bottom, phone 390 px). An agent can distinguish this visual-preview tool from HTML-oriented siblings such as get_site or get_stats 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 explicit timing guidance ('use after create_site or a bigger change') plus a fallback path when quota is exhausted ('review the HTML instead'). The fallback does not name the concrete sibling tool (get_site), so the agent must infer the target, which keeps 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?

Adds real behavioral context beyond annotations: the restore is non-destructive in the long run because it creates a new version that can itself be undone, which softens the destructiveHint. It doesn't state auth requirements or that the restore replaces current live content, but the key reversibility trait is disclosed.

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 that names the action, its undo purpose, the source of the parameter, and the reversibility. No wasted words.

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

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

For a mutation tool with full annotations and an output schema, the description covers purpose, parameter provenance, and the reversibility guarantee. Only minor gaps remain, such as whether the restored version becomes the live version immediately.

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 site_id and version are already documented, including an example site id format. The description only adds that version numbers come from get_site with history: true, which is a minor semantic addition over the schema.

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

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

States a specific verb (restore) and resource (a saved version), and frames the operation as an undo, which is precise and distinguishable from siblings like update_site or create_site. It also names where the version numbers come from (get_site with history: true).

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

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

Clearly contextualizes when to use it (to undo changes) and points to get_site with history: true as the source of version numbers. It doesn't name an explicit alternative for undoing the undo, but the mechanism is 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds genuinely new context beyond that: changes take ~1–3 minutes, all edits apply atomically as one new version, and undo is available via restore_version. It omits permission/auth prerequisites and failure/partial-apply behavior.

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

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

Front-loads the action and the preferred edit path, and every clause carries information (modes, latency, atomicity, undo, required note). Slightly dense in a single run-on sentence, but 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 an output schema present, return values need no explanation, and the description covers mode selection, timing, atomicity, and undo. It would be fully complete with a note on required permissions and what happens when an edit fails to match, but nothing essential to a correct call is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including the nested edit fields. The description reinforces 'note is required: what you changed and why' and maps the top-level modes to parameters, but adds little beyond what the schema already states, 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 (changes) and resource (an existing site's pages) and enumerates the exact mutation modes it supports: find/replace edits, whole files, deletions, form email. This clearly distinguishes it from siblings like create_site, preview_site, and restore_version.

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

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

Gives a real preference signal — small find/replace edits are '(preferred)' over whole-file replacement — and routes undo behavior to restore_version. It does not, however, state when to use this tool versus preview_site or create_site, so the exclusions are left implicit.

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

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

Annotations already declare write, non-idempotent, destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the no-files path returns an upload link that a .zip is POSTed to via curl, and it emphasizes that `note` is mandatory. It doesn't spell out that replace_all/delete destroy content, though the destructiveHint already flags risk.

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

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

A single dense sentence that front-loads the primary guidance ("Use for images, fonts...") before the mode mechanics. It packs several ideas via colons and clauses; slightly run-on, but every clause carries information and nothing is wasted.

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

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

With 5 params at full schema coverage, an output schema present, and annotations covering safety, the description supplies the one thing structured data can't: the two-mode workflow and the required note. The only gap is not surfacing the destructive replace_all/delete behavior in prose, which the destructiveHint partially covers.

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 every parameter including the files/delete/replace_all semantics, making 3 the baseline. The description reinforces the omit-files-means-upload-link behavior and repeats that note is required, but adds no format or constraint 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?

It states a specific action (upload files) and enumerates the resource classes it handles: images, fonts, other binaries, batches, and whole builds. The "many files at once" framing implies a batch tool, but it never names the sibling `attach_image` it could be confused with for the single-image case, so differentiation is inferential rather than explicit.

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

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

It gives clear conditions for use (images/fonts/binaries, many files, or a full Vite/Astro/Next build) and distinguishes two invocation modes: send files, or send none to receive an upload link. It stops short of naming when-not-to-use or routing to `attach_image`, so it's context-rich but not fully exclusive.

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