Ginta

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

Annotations already flag it as non-read-only, open-world, non-idempotent and non-destructive, so the safety bar is partly covered. The description adds real behavioral detail beyond that: the drop link is scoped to one website and expires in an hour, requires no sign-in, and 'dropped' returns each photo's name and a /_g/u/… path. It does not say what happens to an existing image on overwrite or what the default save returns.

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

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

Front-loads the purpose, then walks the actions in a single dense paragraph. Every clause carries information, though the run of parentheticals and semicolons makes it harder to scan than a short bulleted action 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?

An output schema exists, so return values needn't be spelled out, and the annotations carry the safety profile. The description covers all three action paths, the site scoping, the link's lifetime and the no-sign-in property — enough for an agent to choose a path and 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%, so the schema already defines url, action, site_id, filename and data_base64, including that site_id applies only to drop_link/dropped. The description reinforces the site_id prerequisite and hints that data_base64 should be a 'small' image, but adds little else in the way of format or constraint 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 concrete verb and resource — putting the owner's own photo or logo online — and enumerates the surfaces it serves (pages, menu, shop, gallery, blog). The three action modes are each given a distinct meaning. It does not, however, distinguish itself from the sibling upload_files, which an agent could plausibly confuse with this.

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 for when to use it (owner's own photos and logo, not third-party imagery) and ties each action to a scenario: drop_link for bulk phone/computer uploads, dropped for retrieving what was dropped, default for a single image. It lacks an explicit exclusion rule such as 'use upload_files instead for X'.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds behavior beyond them: it surfaces alternatives when the name is taken and discloses the slugification rule applied to input, though it says nothing about rate limits or whether the check reserves the name.

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

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

Two dense sentences with no waste: the usage directive and sibling reference come first, followed by a concrete normalization example. Every clause carries information an agent would otherwise have to guess.

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

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

For a single-parameter, read-only check with an output schema and rich annotations, the description covers the remaining gaps: when to call it, how the input is normalized, and what happens on a taken name. Nothing needed 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 100%, so a 3 is the baseline; the description goes beyond it by explaining normalization semantics — "Bella Roma" becomes "bella-roma" — which tells the agent how raw user input is transformed before lookup. Format details like the 80-char max stay 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 a specific verb (check) and resource (a site name at https://<name>.ginta.page) and implicitly contrasts with the create_site sibling. The agent can immediately tell this is a pre-flight availability check rather than a mutation.

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 create_site when the user wants a specific address" gives an explicit trigger condition and correct sequencing relative to the sibling write tool. It does not state an explicit negative case (e.g., skip this if no custom address is wanted), so it falls short of the strongest tier.

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 write/openWorld/not-idempotent; the description adds the substantive behavior: it returns exact DNS steps, requires an A record, a www CNAME and a proving TXT record, and states the site is not served until verification is observed. It does not address re-running the connect for a different domain, how to undo a connection, or propagation timing, which keeps this 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?

Front-loaded with the triggering condition, then the two argument-driven modes and their consequences in a single dense but well-ordered sentence plus a closing clause. Every clause carries distinct information (trigger, action, returned DNS records, gating rule, check mode).

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 write tool whose output schema already documents returns, the description covers prerequisites, the verification gate, the www variant, and the check mode, which is enough to call it correctly. Residual gaps are lifecycle questions (changing or removing a domain) rather than invocation correctness.

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: omitting `domain` switches to status-check mode, and `with_www` flips which hostname is primary and which redirects, illustrated with bakery.com/www.bakery.com. `site_id` is left to the schema, which already documents it well.

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 (connect the user's own domain to a site) and explicitly covers the second, distinct behavior (status check) selected by the presence or absence of `domain`. The mode split is spelled out with a concrete example, so an agent knows exactly what it is calling for either case.

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 trigger: "Use when the user wants their own domain on a site, or asks whether it works yet," and the argument-based branch (with `domain` = connect, without = check) functions as an implicit when-to-use rule. It never names alternatives among siblings such as manage_connections or preview_site, so there is no explicit exclusion 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 declare the write/non-destructive/open-world/idempotent=false profile, and the description adds genuinely new behavior: builds take about 1–3 minutes, the photo endpoint /_g/photo?q=... returns real images, and image URLs that fail to load are replaced. Content policy ("pages should hold only real details the user gave") is also disclosed. It does not cover failure modes such as name collisions, which check_name exists for.

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 return value are front-loaded, then constraints follow, so the agent gets the essentials first. The paragraph is dense and jumps between file requirements, content policy, note, and photo URLs, which makes it harder to scan than a short bulleted structure 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?

For a six-parameter publishing tool that already has full schema coverage and an output schema, the description covers the remaining agent-relevant unknowns: latency, the two input modes, required content, and the fake-image trap. Nothing essential to invoking it correctly is left unstated.

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

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

Schema coverage is already 100%, so the baseline would be 3; the description earns above that by adding meaning the schema does not, notably that omitting files switches the tool into an upload-link mode rather than being a no-op, why note is mandatory (the owner and Ginta's AI read it), and the accepted photo URL pattern for image paths.

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?

"Publishes a NEW website in the user's account and returns its URL" gives a specific verb (publishes), a specific resource (website), and an explicit scope marker (NEW) that separates it from the update_site / manage_site siblings. It also states the primary outcome (the returned URL), so an agent knows what a successful call yields without opening the schema.

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

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

It states both invocation modes clearly: pass the files you designed (index.html required) or omit files to receive an upload link for a .zip build, and it routes to get_guide for details. What is missing is an explicit exclusion against the obvious alternative — nothing says to use update_site instead when the site already exists, leaving that inference to the word "NEW".

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 agent knows this is a safe, repeatable, self-contained read; the description adds nothing about caching, versioning, or size of the returned guide. Its only behavioral-adjacent content is the topic mapping, which is parameter semantics rather than 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?

Three short sentences, front-loaded with the return value, then the trigger, then the enum disambiguation. Nothing is padded; the semicolon-separated topic gloss keeps the mapping compact.

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 format need not be described, and the one optional parameter has a default. The only shortfall is that five of the seven enum values rely on the reader's inference rather than being glossed like "developers" and "modules".

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% but the schema text is only "Default all.", so the description carries real weight by decoding two non-obvious enum values: "developers" (uploads, builds, redirects, API connections) and "modules" (live parts). It leaves the remaining five values (all, design, blocks, editing, seo) undescribed, assuming their self-evidence.

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 ("Returns Ginta's building guide") and enumerates the covered subject areas: site model, design brief, functional blocks, SEO. That scope is unmistakably documentation, so an agent can separate it from data-fetching siblings like get_site, get_stats or list_sites without inspecting 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?

"Use before building or editing a site" gives explicit timing and ties the tool to a concrete task class (create_site / update_site / manage_site work). There is no when-not guidance or note about whether repeated reads are needed, but the positive trigger 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 cover read-only, idempotent, non-destructive and closed-world behavior. The description adds important context beyond annotations: the returned record contains the visitor's personal data, intended for the site's owner. It does not mention auth requirements explicitly, but the owner framing covers the access scope.

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

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

The description is a single, front-loaded sentence that begins with the usage condition and then covers return content and privacy. It is slightly long but every clause contributes useful information; no filler 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?

Given the low complexity, 100% schema coverage, existing output schema, and rich annotations, the description provides sufficient context: when to use, what is returned, and the personal-data sensitivity. Minor gaps like error behavior are reasonable to omit.

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 message_id are already documented in the schema. The description reinforces that message_id comes from get_messages, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'returns one message, order, booking, sign-up or quote request' with 'the visitor's full contact details'. It also distinguishes itself from the sibling get_messages by naming it as the source of the id.

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 condition: 'Use when the owner wants to reply to, call or deliver to one visitor.' This implies a retrieval-then-contact workflow. It does not explicitly state when not to use it or name alternatives beyond the id source, but the context is largely 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description still adds real behavioral context the annotations cannot: results are ordered newest first and visitor emails, phone numbers and addresses are masked, which materially affects how an agent should interpret and relay results. It stops short of describing pagination behavior or how the limit interacts with the newest-first ordering, which is the only notable gap.

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

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

Front-loaded with the usage trigger, then behavior (ordering, masking), then sibling routing; no sentence is redundant. The long parenthetical enumerations and the reference to Ginta's Messages add slight density, but they carry genuine disambiguation value rather than 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 tool with an output schema (so return shape needn't be explained) and full annotation coverage, the description supplies everything an agent needs: trigger conditions, scope, ordering, PII masking, and where to go for the full record or for mutations. Nothing material is left to inference.

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 (site_id with a URL-derived example, limit with default 50 and a 1-200 bound) are fully documented in the schema itself. The description adds no parameter-level meaning beyond the schema — the ordering note describes results, not an input — 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 messages), enumerates the concrete content types it covers (shop orders, quote requests, bookings, event sign-ups) and explicitly distinguishes itself from get_message, manage_site and manage_module. An agent can identify exactly what comes back 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?

Opens with an explicit trigger ("Use when the user asks for their messages, enquiries, orders or bookings") and names three alternatives with the conditions that select them: get_message for a single full message, manage_site for mark-read/delete, manage_module for acting on an order or booking. Both when-to-use and when-not-to-use are 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 readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds real context beyond them: images and fonts are returned as references rather than bytes, history yields 'saved versions for restore_version', and there is a size caveat on default file retrieval. The trailing note about the editor's Code tab is mildly promotional rather than behavioral.

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 usage trigger is front-loaded, and the return-shape clause follows immediately. It is appropriately sized for a three-parameter read tool. The parenthetical about seeing files in the Code tab and downloading a .zip is tangential to invoking this tool and costs a little tightness.

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 enumerated, yet the description already characterizes them. Usage, narrowing via paths, the history option, and the restore_version relationship are all present. Nothing an agent needs in order to call 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?

Schema coverage is 100%, so the baseline is 3 even without description help. The description nonetheless adds meaning the schema does not: it frames the history flag as the input that pairs with restore_version, and reinforces paths as a partial-read mechanism. It does not explain the default size threshold that governs behavior when paths is omitted.

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

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

States a specific verb and resource: reads a site and returns its files plus, optionally, saved versions. It goes further than the title by specifying that text files come back with contents while images and fonts come back as a list of addresses, which lets an agent distinguish this from list_sites, get_stats, 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 an explicit trigger ('Use before editing an existing site, or when the owner wants their code') and a narrowing instruction ('Pass paths to read only some files'). It also links the history flag forward to restore_version. It lacks an explicit when-not or a direct pointer to sibling reads like list_sites, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behaviour, so the safety profile is covered. The description adds genuinely useful behavioural context beyond them: the fixed 30-day aggregation window and the specific metric families returned. It does not discuss data freshness, rate limits, or permission requirements, so it is not fully complete.

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, front-loaded with the usage trigger and followed by the returned metric inventory. No filler, no repetition of the title, and 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?

An output schema exists and annotations cover safety, so the description need only frame intent and content, which it does. The 30-day window and metric list give enough to decide to call it. Minor gaps remain around result freshness and any limits on historical data available.

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

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

With a single required parameter at 100% schema description coverage, the schema already explains site_id with a concrete URL example and a pointer to list_sites. The description adds no further meaning about that parameter. Baseline 3 is appropriate 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?

The description names the resource and scope concretely: views per day over 30 days, top pages, referring websites, and phone scores for performance, accessibility, best practices and SEO. It is clearly distinguishable from sibling tools like get_site or list_sites by the metrics it returns. It stops short of explicitly naming a contrasting sibling, so a 4 rather than 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 opens with an explicit trigger condition: 'Use when the user asks how many visitors their site gets or how fast and well-built it is.' That maps user intent to this tool well. There is no when-not guidance or named alternative for adjacent questions (e.g. site metadata), which keeps it below 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 elsewhere. The description's extra content is a summary of returned data, which the output schema also covers, so it adds only marginal behavioral context such as the completeness guarantee that all sites are 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?

Two sentences, with the usage trigger front-loaded before the payload description. There is no filler, no restatement of the title, and every clause carries information an agent can act 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?

A zero-parameter, read-only listing tool with full annotation coverage and an output schema needs only a clear when-to-use and a note on contents. Both are present, so nothing required 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The mention that it is used when a site_id is needed hints at how the result feeds other tools, which is a small useful addition.

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 payload ('URL and form message count, plus what the plan allows'). The 'every site' scope implicitly but clearly distinguishes it from the single-site 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 an explicit trigger ('Use when you need a site_id, or the user asks about their websites, plan, limits, credits or page views'), which is strong and covers the main call sites. It stops short of naming a when-not condition or pointing to alternatives such as get_site when only one site's detail is needed.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is known. The description adds real behavioral value beyond that: admins authenticate with email+password rather than a Ginta account, they can edit content but never design or code, and add-without-password triggers an invitation email while send_setup_link sends a fresh one. It does not explain the consequences of remove (does access drop immediately?), what set_password does to an existing password, or any rate/repeat limits — with destructive operations present, those gaps keep it at 3.

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, then the behavioral context, then per-action notes — a sensible order with no filler. The per-action clauses are crammed into one run-on paragraph, which makes scanning harder than a short bulleted 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?

Given an output schema and full annotation coverage, the description supplies what structured fields cannot: who these admins are, how they log in, what they may change, and which action sends email. The main omission is the effect of remove and whether password changes propagate immediately, which matters for a tool flagged destructive.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by tying parameters to actions: password is optional on add and means the owner supplied one, email applies to every action except list, and set_password accepts either an admin's address or the owner's own email. That resolves the ambiguity an agent would otherwise face when choosing between add and send_setup_link.

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 (the set of admin users behind /admin) and the operations (list, add, remove, set_password, send_setup_link), and it scopes what those admins can touch — lists, menu, bookings, messages — while explicitly excluding design and code. It never states the purpose in a single crisp opening clause (that lives in the title), and it doesn't name a sibling it is distinct from, so an agent must infer that manage_site/manage_module are different concerns.

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 triggering guidance: "Use when the owner says who should keep the website up to date" with a concrete example and the situation "after building a site with parts the owner fills in." Each action variant gets its own cue (add with vs. without a password, set_password for an admin or the owner's own email, send_setup_link for a new choose-your-password email). No explicit when-not-to-use or named alternative tool appears.

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, openWorldHint=true, and idempotentHint=false, so the safety profile is supplied. The description adds genuinely non-obvious behavior: Ginta injects the key so the page never sees it, and forwarding is restricted to that base URL only — a meaningful security boundary. It still does not say what deletion removes or whether it affects live traffic.

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 guidance is front-loaded in the opening clause and the total length is small. The single dense sentence with embedded fetch() syntax is slightly hard to parse, and the escaped quotes add noise, but no sentence is wasted.

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

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

An output schema exists, so return values need not be explained, and the list action's output is still helpfully summarized (connections plus this month's calls). With 8 parameters and three actions, the only real omission is delete semantics, which the action enum's own description 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 auth enum and methods default. The description only echoes a subset (name, base URL, secret, how it's sent) and adds the useful detail that the connection name becomes the URL path segment. That is baseline-level added meaning, not a substitute for schema detail.

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

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

The description names a concrete resource and operation (save a connection with name, https base URL, secret, and auth style) and explains the resulting proxy endpoint pattern. It clearly covers save and list, but never describes what the 'delete' action does, so the multi-action scope is only partially stated.

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

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

"Use when the site's JavaScript must call an outside API" gives an explicit triggering condition, which is strong. However, it offers no exclusions or sibling comparison (e.g. manage_secrets is only referenced indirectly through the secret parameter), and the delete action's use 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?

Beyond the destructiveHint/openWorldHint annotations, the description discloses a genuinely important side effect: some actions email the business's customers (cancelled or moved bookings, order updates). That is behavior an agent cannot infer from annotations or schema. It stops short of describing what data is destroyed by destructive actions, which is the biggest residual gap given destructiveHint=true.

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

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

Purpose is front-loaded, followed by the discovery path and then the side-effect warning. The long module enumeration is dense but earns its place by implying the enum's scope; a reader can scan the first sentence and act.

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 no explanation, and the discovery flow plus email side effect are covered. For a destructive, non-idempotent, open-world dispatcher spanning ten modules, the description never says what deletion or overwriting means here, which is a real gap. Adequate for navigation, thin on risk.

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 all four parameters already carry descriptions including the omit-module and help/no-site_id behaviors. The description restates those rules and adds only the detail that the module listing includes plan inclusions; it adds little on `data` or `action` values beyond pointing at "help".

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," then enumerates the concrete modules (menu, bookings, shop, blog, gallery, events, quote, announcements, reviews, collections). The scope is distinguishable from page-editing siblings via "without rewriting pages." However, the actions themselves remain opaque (only examples like setup/get/list/save_item appear in the schema, not the description).

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 discovery workflow: omit `module` to see the parts and plan inclusions, and use action "help" to list a module's actions and fields. It does not name an alternative sibling (e.g. manage_site, update_site) or state when-not to use this dispatcher, so routing to it versus page-level tools is 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?

Beyond the destructiveHint/readOnlyHint annotations, the description discloses the key behavioral fact an agent cannot infer: values are write-only and can never be read back by anyone, and set without a value returns an out-of-band owner link instead. It is slightly less explicit about what delete destroys (whether the name or the stored value) than it could be, given destructiveHint=true.

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 front-loads the trigger ('Use when…') and then enumerates the three actions compactly, with no filler sentences. The middle sentence about the owner's key box is dense and slightly nested, but every clause carries actionable information.

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

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

For a destructive, multi-action, write-only tool with four parameters and an output schema, the description covers the trigger, per-action behavior, the out-of-band value path, and the follow-up tool. Nothing an agent needs in order to call it without leaking secrets is missing.

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

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

Schema coverage is 100%, and the schema already documents name format, the site_id derivation, the action enum, and the instruction to omit value. The description largely restates the omit-value path ('set without value returns that link'), adding little meaning the schema does not already carry, 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 names the resource (a site's API keys) and spells out each of the three actions — 'list shows the names only, delete removes one, set stores one encrypted' — so an agent knows exactly what the tool does per action value. It also separates itself from the sibling manage_connections by saying keys must be 'use[d] through manage_connections'.

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 opening clause gives an explicit trigger — 'Use when the site's code needs an API key (weather, CRM, maps…)' — and the closing sentence routes consumption to the alternative tool, manage_connections. It also states hard exclusions ('never ask for one in the chat and never invent one') that prevent a common misuse.

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?

Against annotations that already declare destructiveHint=true and idempotentHint=false, the description adds real operational context: destructive calls first return what would be lost, they require confirm: true, moves require the other account's acceptance, moving redirects old addresses, and offline visibility deletes nothing. This is meaningful disclosure beyond the structured 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?

The scope is front-loaded well, but the first sentence is a long run-on that lists all eleven actions, duplicating the action enum in the schema. The highest-value sentence — the confirm gate for destructive actions — is buried at the end rather than surfaced early.

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 15-parameter, multi-action mutation tool that already has annotations and an output schema, the description covers the risky paths (delete, remove_domain, move send) and the semantics of several actions. It leaves the boundary with update_site unexplained, which is the main residual gap.

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

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

Schema description coverage is 100%, so the schema already defines all 15 parameters, and the description largely re-enumerates the same action list. It does add a few facts the schema does not, notably that old Ginta addresses redirect after a move and that a new password signs everyone out. Baseline 3 is appropriate because the schema carries most of the semantic 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 opens with a concrete scope statement ("Use for a whole website, as in its Settings in Ginta") and enumerates the specific operations it performs: delete, rename, address, move, visibility, badge, form_emails, remove_domain, mark_read, delete_message, webhook. That is a specific verb-and-resource framing rather than a restatement of the name. It stops short of naming the sibling it differs from (update_site), so an agent must infer the split from the 'Settings' 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?

It gives clear situational guidance by tying the tool to a website's Settings surface, and it adds a strong procedural rule: delete and remove_domain first answer what would be lost and run only with confirm: true. What's missing is an explicit contrast with update_site, the sibling most likely to be confused with this one for site-level changes.

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 readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is covered. The description adds genuinely new operational context: a per-plan daily quota and what to do when it is exhausted. It does not say what the screen dimensions mean for output shape or how failures (page not found, site unpublished) surface, but with output schema present that is a minor 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?

A single sentence, front-loaded with the usage trigger, then capability, then the quota constraint and fallback. No filler and nothing repeated from the title or 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?

For a two-parameter read tool with an output schema and full annotation coverage, the description covers purpose, timing, quota and fallback. The one omission is naming the tool to fall back to when the daily screenshots are used up.

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 carry examples ('menu', 'bella-roma'). The description adds only that exactly one page is captured, which does not materially extend the meaning of site_id or page 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: it produces desktop (1280 px, full-page) and phone (390 px) screenshots of one page 'like a visitor' would see it. That is concrete enough to separate it from read-oriented siblings like get_site or get_stats, which return data rather than visuals.

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 triggering context ('after create_site or a bigger change') and a fallback when quota is exhausted ('review the HTML instead'). The only gap is that the fallback does not name the sibling tool to use for reviewing HTML, leaving the agent to guess among get_site/manage_site.

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, yet the description still adds real value: it explains that the restore is written as a NEW version and is therefore itself undoable, and it enumerates what is never touched (visitors' messages, bookings, orders). The 'first answer lists it' / confirm flow is only implied here and fully documented 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?

One front-loaded sentence with the purpose first, then scope, then exclusions. The stacked parentheticals ('menu prices, products, posts…') add minor clutter but each 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?

For a destructive mutation with rich annotations and an output schema, the description covers the origin of the version identifier, the blast radius, undoability and what is preserved. The mandatory confirmation-on-partial-restore path is delegated to the schema's confirm description, which is acceptable but leaves a small gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns more by explaining where version numbers come from (get_site with history: true) and that a restore may proceed even when part of the state cannot be reverted. That adds meaning beyond the bare 'Version number to restore' property text.

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

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

States a specific verb and resource ('restores a saved version') with concrete scope: pages and live parts such as menu prices, products and posts. It is unmistakably distinct from update_site or manage_site because it operates on a numbered historical version rather than current 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?

Opens with an explicit trigger ('Use to undo changes') and points to get_site with history: true as the source of valid version numbers, which tells the agent how to obtain the input. It stops short of naming an alternative tool or an explicit when-not-to-use condition.

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

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

Annotations already flag destructive=true and idempotent=false, but the description adds substantial context beyond them: edits apply atomically as one new version, the operation takes 1-3 minutes, note is mandatory and owner-visible, and memory-written image URLs are often fake. This is exactly the extra behavioral detail 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-loads the core action and change modes in the first clause, then layers constraints and undo path. The trailing photo/URL guidance is tangential to the tool's mechanics but earns its place by preventing a common failure mode; no sentence is pure filler.

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

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

Complete for a destructive multi-mode mutation tool with full schema coverage and an output schema. Timing, atomicity, undo path, required note rationale, and image-sourcing caveat cover everything an agent needs before invoking it.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema, which sets a baseline of 3. The description adds only marginal meaning beyond that: the preference for edits and the purpose of note, both of which the schema also conveys. The photo URL pattern is useful but is guidance, not parameter 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 ('Changes an existing site's pages') and enumerates the exact change modes: find/replace edits, whole files, deletions, and form email. It also names a sibling by function ('undo with restore_version'), so an agent can separate this from rollback tooling 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 preference signal ('small find/replace edits (preferred)') and routes undo behavior to restore_version. It stops short of explicit when-not guidance (e.g. when to use whole-file replacement instead of edits, or when preview_site is warranted first).

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 non-idempotent, so the safety bar is partly met; the description adds genuinely useful non-obvious behavior: the no-files mode returns an upload link that must be POSTed a .zip with curl. It does not restate the destructive consequences (that replace_all wipes unlisted files) or note any auth/rate-limit context, which keeps it off 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 short, front-loaded sentences with no filler; the primary use case leads and the note requirement is deliberately last. The first sentence is a long comma-spliced run-on that takes a second pass 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 full schema description coverage, rich annotations, and an output schema, the description only needs to explain the non-obvious contract, and it does explain the zip-link workflow and mandatory note. It is slightly thin on the destructive replace_all branch for a tool flagged destructiveHint=true.

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

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

The description clarifies the three input modes for files (text, base64, or a link) and that omitting files yields an upload link, which adds a little meaning beyond the schema. The critical replace_all semantics (upload becomes the whole site, other files deleted) and the delete array are not mentioned at all in the description, so the riskiest parameters 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?

"Use for images, fonts and other binary files, many files at once, or a whole build (Vite/Astro/Next export)" names the resource and the scope (bulk/binary/build), which implicitly separates it from the singular sibling attach_image. It never names attach_image explicitly, so the separation is inferred rather than stated.

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

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

Gives a clear selection rule: use this for multiple files, binary assets, or a full build export, and describes the alternative in-tool path (omit files to get a zip upload link for curl). No explicit "do not use for X, use sibling Y" exclusion is stated.

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