Kleap

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

Annotations only declare a non-read-only, open-world, non-destructive mutation. The description adds genuinely new behavior: the call does not complete a purchase, the URL expires in 30 minutes, the user must act, and app_id causes post-payment connection. This is exactly the extra context annotations cannot carry.

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

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

Three short sentences, front-loaded with the core action and the critical constraint that nothing is purchased yet. Every clause earns its place; no filler.

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

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

Although an output schema exists, the description still explains the key returned value and its time limit, and covers the post-payment app linkage. For a payment-initiation tool this is complete enough for an agent to call and report 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 for app_id beyond the schema's terse 'App to connect it to' by specifying the connection happens after payment. Other params (years, domain, registrant, context) are left to the schema.

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

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

States a specific verb+resource ('Start buying a domain') and immediately names the artifact produced (a Stripe checkout_url). It is clearly distinguishable from siblings like check_domain, search_domains, and connect_domain.

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 operational guidance: open the link and pay, nothing is bought until checkout completes, and the agent must never claim the domain is purchased. It does not explicitly name alternative tools such as search_domains for lookups, so it falls just short of full when/when-not routing.

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

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

The description adds useful context that the operation involves connection/DNS status, and annotations cover destructive intent. However, readOnlyHint is false, and the description does not clarify whether the check triggers any side effects, requires special permissions, or has rate limits.

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 focused sentence that front-loads the action and object with no wasted words. It is appropriately sized for the tool's simplicity.

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

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

The tool is simple, parameters are fully documented, and an output schema exists to describe return values. The only notable gap is the lack of explicit guidance on when to choose this tool over domain-related siblings.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description does not add extra parameter-level meaning beyond stating that the operation checks domain connection/DNS status.

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

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

The description uses a specific verb ('Check') with a clear resource ('a domain's connection / DNS status') and scope ('for a Kleap app'). This clearly distinguishes the tool from siblings like connect_domain and search_domains, which involve different operations.

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

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

The description gives no guidance about when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. An agent must infer usage from the tool name and sibling list, which is not enough for confident 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?

Far exceeds the annotations: it discloses timing expectations (5-15 min builds), the wait cap, the full status enum, the distinction between 'completed' and 'deployed', the 'pending means production_url is stale' trap, and which errors are transient vs terminal. This is exactly the operational context a poller needs.

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

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

Front-loads the core answer ('returns quickly, report it') before the status semantics, and every clause carries operational value. It is dense and parenthetical-heavy, but trimming would lose actionable guidance 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?

An output schema exists, so return shapes need not be described, yet the description still decodes the status values and deployment states that an agent most needs to interpret them. Nothing required to call and correctly report this tool 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 would be 3, but the description adds real meaning beyond it: why `wait` exists, that the server cap makes larger values no-ops, and the 'leave it unset' guidance. It does not restate the task_id origin beyond what the schema already says.

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 ('Check a create/modify task') and immediately scopes the return ('CURRENT status'), which cleanly separates it from retry_task and get_publish_status. An agent can identify this as the polling endpoint without opening the schema.

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

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

Gives explicit when-to-use, when-not-to-repeat ('report it to the user rather than calling again in the same turn'), and routes to named alternatives: retry_task for TASK_TIMEOUT/STALE_TASK, get_publish_status for unknown_task. Failure handling and the 402 credit case are spelled out.

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

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

Annotations already mark this as non-read-only, open-world, and non-destructive; the description adds useful behavioral context beyond that, including automatic TLS, A-record pointing, and the prerequisite that the app must be live. It does not contradict the annotations and explains the mutation's scope without overstating side effects.

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

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

Three sentences with no filler, front-loading the core purpose and immediately clarifying the most important prerequisite. Every sentence earns its place, and the mention of what the tool does not do is a compact differentiator.

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, full parameter coverage, and presence of an output schema, the description is largely complete: it covers prerequisites, user actions, and tool boundaries. It could mention what happens after connecting or how to verify the connection, but nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: app_id must be a published app, and domain must be a domain the user already owns. This goes beyond the bare schema descriptions, though the context parameter is not elaborated further.

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 a specific verb and resource: connecting a user-owned domain to a live Kleap app with routing and automatic TLS. It distinguishes itself from siblings like publish_app, check_domain, and search_domains by emphasizing that no purchase is made and no prior publish step is needed.

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

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

The description explicitly explains when to use this tool: the user must already own the domain and the app must be live. It also gives a concrete exclusion, saying publish_app is not required, and references create_app/modify_app to clarify what counts as live.

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 are sparse (readOnlyHint=false, destructiveHint=false), so the description carries the burden of behavioral disclosure. It does convey critical behavior: returns a consent_url, requires user action in a browser, and automatically binds the property. However, it doesn't describe what happens on failure (e.g., if consent is rejected) or any rate limits. This is sufficient but not comprehensive.

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 paragraph but contains multiple important points. It is lengthy but front-loads the key trigger and outcome, and each sentence addresses a distinct aspect (when to use, consent_url handling, custom domain requirement, avoiding duplicate consent). A bit long but justifiably so given the complexity.

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 output schema exists (not shown but signalled), the description doesn't need to detail the return format. It covers the key procedural steps: user consent in browser, automatic binding, and dependency on custom domain. It might be complete enough for an agent to execute the flow without additional help, though edge cases like failed consent are not addressed.

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 parameters are fully documented in the schema. The description adds no new parameter-level meaning beyond the schema, but it does explain the context parameter's purpose in a general way. As per calibration, baseline is 3 when schema fully covers parameters, and the description doesn't need to compensate.

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 tool's purpose: to connect or reconnect Google Search Console for a site. It includes specific context (when get_search_console reported connected:false) and distinguishes this action from reading data. It also clarifies that it returns a consent_url, so the agent knows the immediate outcome without needing to inspect the output 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 says when to use this tool (right after get_search_console reported connected:false) and when not to use it (if report says already connected). It also gives clear alternatives: connect_domain first if requires_custom_domain is true. This strongly routes the agent to the correct action among siblings.

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

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

Discloses wait time, auto-deploy, return of build_url, and real-time preview behavior. Annotations: readOnlyHint=false, openWorldHint=true, destructiveHint=false; description adds value beyond annotations and does not contradict them.

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

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

Concise, front-loaded purpose, and every sentence adds value (usage, timing, checking behavior, sibling alternative). No fluff.

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 output schema exists and annotations provide safety profile, description fully covers when/when not, behavior, and return info. Nothing critical 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 no parameter descriptions missing. The description adds context on prompt and context purpose indirectly, but not deeply.

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 ('create a full website via Kleap') and differentiates from write_files, which is a sibling. It also describes the output (build_url).

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

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

Explicitly says when to use (user wants a complete hosted website/web app) and when not to (prefer write_files for full-site? Actually it says prefer this over write_files for full-site creation). It also clarifies not to block or poll check_task in widget clients, which is a strong when/when-not.

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

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

Annotations already declare destructiveHint=true, but the description adds significant context: deletion is 'Permanent,' the where clause must be non-empty, exact matches, and the call 'Returns how many were deleted.' These details go beyond the annotation and materially shape an agent's expectations.

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 compact sentences with zero filler. The core operation and the critical constraint are front-loaded, followed by the two key behavioral facts (permanence and return value). Every sentence earns its place.

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

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

For a destructive 4-parameter tool with an output schema, the description covers the essential semantics: what gets deleted, the precise where constraint, permanence, and return information. A minor gap is the lack of a caution to verify rows with query_database_rows before deletion, but this is not strictly necessary.

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 value on the tricky `where` parameter by specifying it must be required, non-empty, exact matches, and providing an example ({"id":42}). This clarifies usage beyond the schema's bare 'Which rows (required)'.

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 ('Delete'), a resource ('rows'), and a precise condition ('matching where'), making the operation unmistakable. It clearly differentiates from sibling tools like insert_database_rows, update_database_rows, and query_database_rows through the explicit destructive verb.

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

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

The description implies its use case through the verb and resource, but it does not explicitly state when to prefer this tool over alternatives such as run_database_sql (which could also delete rows) or suggest verifying with query_database_rows first. No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes far beyond: it explains side effects (deleting a binary removes stored bytes), restrictions (Kleap-owned paths are refused because the build restores them; homepage refused because a site without one is broken), and the critical deferred publishing behavior ('The pages STAY LIVE until you call publish_app'). It also discloses the return value semantics (which paths were deleted and which did not exist). This fully covers behavioral expectations 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?

Although the description is lengthy, every sentence earns its place: it starts with the purpose, then gives usage guidance, then restrictions, then return semantics, then the publish behavior. There is zero redundancy or filler—each clause adds a distinct, necessary piece of information for correct usage. Front-loaded with the core action and sibling distinction.

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 operation with restrictions and a publish lifecycle, the description is exceptionally complete. It covers what can be deleted, what cannot, the side effects, the return value, and the fact that changes are not live until publish_app. With an output schema also present, an agent has everything needed to call this tool correctly and safely.

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 meaning beyond the schema by explaining which paths are project-relative (with examples) and which paths are explicitly refused (Kleap-owned, homepage), giving the agent a clearer mental model of valid inputs. While not exhaustive, it enriches the parameter understanding beyond the bare schema descriptions.

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?

Clearly states the action: 'Remove pages, components or assets from a site' and explicitly identifies itself as the counterpart to write_files, distinguishing it from that sibling. It specifies the resource type and scope, so an agent knows exactly what this tool does without guessing.

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

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

Provides explicit when-to-use guidance with concrete examples (wrong route, duplicate, outdated page, unreferenced image) and when-not-to-use: 'Do NOT overwrite the file with empty content instead.' It also names alternatives: for homepage, 'write a new one instead, writing replaces it,' and points to publish_app for making changes live. This is exemplary usage 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 mark the tool as destructive, and the description adds substantial behavioral detail beyond that: edits are validated together so nothing is written if any are invalid, writes are sequential across files, late failures name what was already applied, and old_string must be unique unless replace_all is set. This gives an agent an accurate model of failure and side effects.

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

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

The description is dense but every sentence earns its place, covering purpose, mechanics, usage conditions, prerequisites, uniqueness rules, atomicity, ordering, edge cases, and follow-up. The most important differentiator is front-loaded in the first sentence, making the description scannable despite its length.

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-file editing tool, the description covers all essential operational context: when to use it, how to prepare inputs, what happens on validation failure, how writes behave across files, what cannot be edited, and what to do afterward. The presence of an output schema means return-value details are not required here.

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

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

The schema already provides 100% coverage and detailed descriptions for all parameters, so the baseline is strong. The description enhances this by clarifying how to use old_string (copy exactly after read_files, add context or use replace_all when non-unique) and reinforcing that new_string "" deletes the match, but most core semantics are already present 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 opens with a precise statement of what the tool does: 'Change PART of a file without resending it — the counterpart to write_files.' This names the specific verb (change), the resource (existing files), and differentiates the tool from its closest sibling, write_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?

It explicitly says when to use this tool: whenever the file exists and only a line, block, or URL changes, with a concrete token-waste rationale. It also gives prerequisites (read_files first, copy text exactly), exclusions (not for new files or binaries), and the follow-up step (then publish_app).

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

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

Annotations already mark it read-only and non-destructive, so the description adds useful behavior beyond that: what address formats are accepted, that it returns an app_id, and the critical display rule about showing site_url and not the internal {slug}.kleap.io host. No contradiction with 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?

Every sentence earns its place: the first defines what the tool resolves, the second gives the workflow trigger, and the third conveys the display caveat. It is front-loaded with the core purpose and contains no filler, despite covering several nuances.

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 and annotations covering safety, the description supplies the remaining essential context: accepted inputs, when to invoke it, what to do with the result, and how to present the resolved address to the user. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% with descriptions for query and context, so the baseline is 3. The description goes further by explaining the query forms with examples and linking the resolution result to site_url/custom_domain semantics, which adds meaning beyond the schema alone.

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

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

The description states a specific action: resolve an address to an app_id, and enumerates accepted address forms (custom domain, kleap.io URL, slug). It clearly differentiates itself from siblings like get_app and list_apps by framing itself as the entry point when a user names a site by address.

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

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

Explicitly instructs to use this tool FIRST when the user references a site by address instead of app_id, and directs the agent to pass the returned app_id to get_app / modify_app / publish_app. It implies not to use it when an app_id is already known, though it does not enumerate more distant sibling alternatives like list_apps or search_domains.

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

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

The description explains the underlying model (Cloudflare FLUX.2), the binary-asset behavior, default size, hd mode, and a critical caching pitfall when overwriting paths. It adds substantial behavioral context beyond the annotations, and does not contradict 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?

Although dense, every sentence earns its place: core behavior, defaults, use cases, a critical warning, and post-call deployment. The most important distinction is front-loaded, and the risk warning is clearly highlighted.

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

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

For a tool with 7 parameters IMPORTANT and an output schema, the description covers purpose, parameters, behavioral quirks, deployment follow-up, and the main failure mode. An agent has enough context to call this tool correctly without guessing.

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 schema carries a lot of the parameter meaning. The description still adds value by explaining path replacement semantics, the 256–1440 range, and what hd:true means in practice, all of which help the agent use parameters correctly.

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 tool generates a real image asset from a text prompt, with the distinguishing notion that no image bytes need to be sent. It also contrasts with write_files, making it easy for an agent to pick the right tool.

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

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

It explicitly lists use cases (hero photos, illustrations, OG images, replacing broken images) and distinguishes this tool from write_files, noting this is the only dependable way to add a generated image. It also instructs to call publish_app afterward, which is actionable 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 readOnlyHint and destructiveHint, so the safety profile is covered. The description goes well beyond that by revealing that unpublished apps return zeroed data with configured:false, that analytics is set up automatically on publish, that the analytics:read scope is required, and that older sessions may 403 with INSUFFICIENT_SCOPE along with a concrete remediation step.

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 primary trigger and each subsequent sentence carries distinct value: data provenance, unpublished-app behavior, and scope/error remediation. No sentence is redundant or filler relative to the structured schema and annotations.

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

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

For a read-only analytics tool with an output schema and complete input schema, the description covers the key missing context: when to call it, what happens before publication, required scope, and how to recover from auth failures. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents app_id, period, and context thoroughly. The description adds meaningful semantic context: app_id must refer to a published site, and unpublished apps produce configured:false results. It does not need to repeat period details because the schema already provides the enum and default.

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 + resource combination: fetching analytics for traffic, visitors, and page/referrer performance on published sites. It also grounds the tool by referencing the Kleap dashboard's Visitors view, which clearly distinguishes it from siblings like get_search_console or get_form_submissions.

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

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

It explicitly says 'Use this when the user asks about traffic, visitors, or which pages/referrers are performing on their PUBLISHED site,' which gives a clear trigger. It also covers the unpublished-app edge case and the insufficient-scope handling path. It does not explicitly name when-not-to-use alternatives, 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=true and destructiveHint=false, so the read-only safety profile is covered. The description adds valuable behavioral context beyond that: it is the tool that lets the user actually SEE the built site, and it warns about stale-version rendering during active builds and custom-domain address preference. There is no contradiction with 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 description is longer than a one-liner but every sentence earns its place: purpose, timing, exclusion, and address rules are all packed in without filler. The main action is front-loaded and the operational constraints come after, which reads naturally for an agent.

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 that an output schema exists and annotations cover the read-only safety profile, the description supplies the missing operational context: when to call, when not to call, and which URL to present. Nothing an agent needs to invoke 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?

The input schema covers both parameters (app_id and context) with descriptions, so schema coverage is 100%. The description does not add param-level meaning beyond the schema; its address guidance concerns output behavior rather than parameter semantics. 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: it shows the finished-site card (screenshot, name, live address) and returns plain details (name, slug, URLs, dates, status). It also distinguishes itself from siblings by calling itself the ONE tool that renders the finished-site card, so an agent can tell it apart from get_screenshot and check_task.

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

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

The description gives explicit when-to-use guidance: call once after a build/edit has deployed and check_task reports deployment_status deployed, and also use it for plain details. It gives a clear exclusion: never call it while a build is still running, because it would show the previous version as if it were the new one. It also specifies address selection behavior (custom_domain vs. slug host), leaving no ambiguity.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds nothing behavioral beyond that — no note about what is returned or any auth/rate context, though the output schema covers return values. Adequate but not additive.

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

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

A single short sentence with no filler, and the invocation condition is front-loaded. It is well-sized for a one-parameter read tool, though it could have spent those few words stating the actual return instead of only the trigger.

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

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

With annotations covering the safety profile and an output schema covering return values, most of the burden is lifted, so the description need not explain outputs. However, for a tool whose title and name hint at different concepts (credits vs. usage vs. plan), the description could have disambiguated what 'usage left' means; it remains minimal viable.

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 required 'context' parameter whose purpose is fully documented in the schema (100% coverage), so the baseline of 3 applies. The description contributes no additional meaning about the parameter, which is acceptable here.

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

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

The description is phrased as a usage trigger ('when the user asks how much usage they have left or about their plan status') rather than stating what the tool does. Combined with the title 'Check usage' and name 'get_credits', an agent can infer it retrieves credit/plan usage data, but the description itself never says what it returns or that 'credits' equals usage/plan status. It is implied 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?

It gives a clear activation condition: user asks about remaining usage or plan status. That is concrete context for invoking it. It does not mention the adjacent 'upgrade_plan' sibling or any when-not condition, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description adds no contradiction. It adds valuable context about the meaning of provisioned:false and the action to take if no database exists, which goes beyond the annotations.

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

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

Two concise sentences that front-load the tool's purpose and then provide essential usage guidance. No wasted words, well-structured.

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

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

The description covers what the tool returns (tables, row counts, columns), when to call it, and the edge case for a missing database. With an output schema present, the information is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so both app_id and context are already well documented. The description adds no additional parameter-specific information, so the baseline of 3 applies.

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

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

The description clearly states the tool retrieves the app's Kleap Database schema including tables, row counts, and columns. It uses a specific verb and resource, and the context distinguishes it from sibling tools like query_database_rows or insert_database_rows.

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

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

The description explicitly instructs to call before reading or writing rows, and explains the provisioning edge case (provisioned:false) with a direct pointer to modify_app. This gives clear when-to-use and when-not-to-use 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 mark it read-only and non-destructive, and the description adds meaningful behavioral context: newest-first ordering, empty-list normality, PII sensitivity, the forms:read scope requirement, and the exact 403 INSUFFICIENT_SCOPE remediation flow. No contradiction with 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 description is front-loaded with the primary trigger and every sentence earns its place: use case, return behavior, empty-result expectation, and auth/error handling. It is dense but not bloated, and all content is directly actionable.

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

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

Given the output schema exists and annotations cover the safety profile, the description is complete for successful invocation: it covers when to call, what to expect, the normal empty case, required scope, and how to handle the likely auth failure. An agent has everything needed to use the tool correctly.

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

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

The input schema covers all 4 parameters with 100% description coverage, so the schema carries the documentation burden. The description adds general behavioral details like ordering and scope, but it does not add meaning to limit or since beyond what the schema already provides.

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

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

The description clearly states it returns form submissions from KleapForm-built forms and frames it around the user's intent ('who filled out their contact form', 'see/export leads'). It is specific about the resource and scope, though it does not name or distinguish itself from a sibling tool such as get_analytics.

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 opens with explicit use-case triggers ('when the user asks who filled out their contact form, or wants to see/export leads') and adds context about empty results for new sites. It does not explicitly state when not to use this tool or point to an alternative, so it falls just short of full 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?

The description adds substantial behavioral context beyond the annotations: report.checked:true means the audit ran, empty lists mean nothing was found, findings must be reported in the report's own words, and the state is instantaneous. It also warns against describing a site as clean when findings exist. No contradiction with the readOnly/destructive 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 description is front-loaded with its purpose and every sentence carries operational value. It is dense and perhaps longer than typical, but the complexity of the report justifies the length. A bulleted report-field breakdown would improve structure, hence not a 5.

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

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

The description covers the status enum, report fields, field meanings, the meaning of checked:true, and the correct user-facing behavior when findings exist. Given the output schema is present, this is complete enough for an agent to invoke the tool correctly and interpret the response.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add meaning for app_id or context beyond what the input schema already provides, but it does not need to compensate for any schema gap.

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

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

The description clearly states a specific verb and resource: 'check whether a website is actually published and live.' It also distinguishes this tool from publish-related siblings by focusing on checking current state rather than performing an action.

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

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

The description gives clear context for when to use this tool: after a publish has run, to check live status, and to inspect the publish report. It also explicitly warns against repeated calls in one turn. However, it does not name sibling alternatives or state when to prefer another tool, so it falls just short of full 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 are all false (readOnlyHint, openWorldHint, destructiveHint), so the description carries the behavioral burden. It discloses the rate limit (1/min per app), the output format (PNG on the asset host), and the critical constraint that image_url is not the site's address and must only be rendered as an image. These are valuable behaviors beyond the structured fields, with no contradiction to 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 description is four sentences, each earning its place: the primary use case, rate limit, output handling, and the crucial not-a-link warning. It is front-loaded with the main purpose and contains no fluff 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?

Given the simple two-parameter tool with 100% schema coverage and an output schema present, the description covers all needed context: when to use, what to expect (PNG URL), how to handle the output (render as image only), and what not to do (treat as site link or fetch it). It also names the alternative for the real address, making it complete for correct invocation and result handling.

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%—both app_id and context already have meaningful descriptions in the schema. The tool description adds no parameter-specific semantics, which aligns with the baseline score of 3 for high coverage; it does not need to compensate for schema gaps.

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 explicitly states the tool's action and resource: 'Use this when the user wants to see a visual screenshot of their website.' It also differentiates from siblings by explicitly saying the returned image_url is NOT the website's address and directing agents to get_app/find_app for the production_url, making the tool's unique purpose unmistakable.

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

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

The description gives a clear when-to-use trigger ('when the user wants to see a visual screenshot'), states the rate limit, and provides explicit anti-guidance: never present the image_url as the site link and never open/fetch/web-search it, instead using production_url from get_app/find_app. This covers both selection and exclusion criteria.

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

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

The description discloses real behavioral traits beyond annotations: the ~2 day data lag and instruction not to report it as a drop, that the data is real Google data not an estimate, what the response includes (totals, top queries, top pages), and the required analytics:read scope. This substantially enriches the safe read-only picture annotations already imply.

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 long but every sentence earns its place: use case, data source, return content, lag caveat, setup routing, alternative tool, and auth failure handling are all distinct and actionable. It is front-loaded with the primary use case and structured logically.

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 output schema exists, return values need no further explanation. The description covers setup fallback, scope requirements, error behavior, data freshness caveat, and sibling routing, so an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents app_id, period, and context. The description adds minimal new parameter-level meaning beyond noting the per-site connection model for app_id and the lag caveat tied to period interpretation, which is enough to justify a baseline 3.

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 and resource: fetching Google Search Console performance data (queries, impressions, clicks, CTR, position). It also explicitly distinguishes itself from get_analytics, making the tool's scope unmistakable.

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

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

It gives explicit when-to-use context (user asks about Google Search performance), when-not-to-use (site visitors/pageviews → get_analytics), and even routes the agent to connect_search_console when no property is connected. Error handling for the 403 scope issue is also specified.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so no contradiction. The description adds behavioral detail that insertion returns the inserted rows with generated ids/defaults, and imposes a 500-row limit. This goes beyond annotations, which are minimal, and clarifies expected side effects and return 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?

The description is two sentences with no redundant verbiage. The core action and limit are front-loaded, and the return behavior is stated efficiently. Every part adds value.

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 an output schema (per context signals), the description covers the essential constraints (500-row limit) and return behavior. It doesn't waste space on return details already in the output schema. Minor gap: no mention of relationship to other database tools, but that's not critical for correct invocation.

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

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

Schema description coverage is 100%, and each parameter (rows, table, app_id, context) already has a clear description in the schema. The tool description adds no further semantic detail, so the baseline of 3 applies.

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

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

The description clearly states the action ('Insert'), the resource ('up to 500 rows into one table of the app's database'), and differentiates from siblings like query_database_rows, update_database_rows, delete_database_rows. The verb–resource pairing is specific and unambiguous.

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

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

The description does not explicitly mention alternatives or when-not to use this tool. Sibling tools like query_database_rows and update_database_rows are present, but no routing guidance is provided. The limit of 500 rows and the action verb implicitly suggest usage, but explicit guidance is missing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds useful behavior beyond annotations: it returns only paths, not contents, and names typical Astro directories. It does not discuss pagination or ordering, but the output schema and read-only nature reduce the need for that detail.

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

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

The description is concise and front-loaded, with the core purpose stated first and the supporting workflow and Astro paths provided in a compact, scannable format. Every sentence earns its place.

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

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

The description is complete for a list-only tool: it states what is returned, what is not returned, how to proceed afterward, and provides relevant file-path hints. The output schema covers return-value details, so nothing critical is missing.

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

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

Schema description coverage is 100%, so both parameters (app_id and context) are already documented in the schema. The description adds no further parameter-level detail, but none is needed because the schema fully explains them.

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

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

The description clearly states the tool lists source file paths (names only, not contents), which is a specific verb and resource. It also differentiates from read_files by explicitly noting that contents are not included, so an agent can identify the correct tool without ambiguity.

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 tells the agent to use this tool to see the project structure and then use read_files to get contents before editing. This provides a clear when-to-use and an explicit alternative, making the routing decision straightforward.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral detail that the tool returns a list of all websites with specific fields, but does not mention pagination behavior or any other runtime traits. This is acceptable but not richly transparent.

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 sentence that is front-loaded with the trigger condition and includes the key return fields. There is no wasted text, and it is easy for an agent to parse quickly.

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

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

For a read-only list tool with full parameter documentation, annotations, and an output schema, the description covers purpose and scope well. The only minor gap is that saying 'all' websites could imply a single response, while limit/offset parameters suggest pagination may be needed. Overall, the definition is nearly complete.

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

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

Schema description coverage is 100%, so the parameters limit, offset, and context are already fully documented in the schema. The description mentions output fields rather than parameter details, adding no parameter semantics 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 clearly states the operation: list all websites, and enumerates the returned fields (name, slug, preview URL, production URL). It distinguishes itself from siblings like get_app and find_app by emphasizing 'all' websites. This is a specific, non-tautological purpose.

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 says when to use this tool: when the user wants to see all their websites. It does not name alternatives or exclusions, but the scope is clear enough that an agent is unlikely to confuse it with get_app or find_app. A 4 is appropriate because the usage context is clear, though alternatives are not discussed.

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

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

Annotations already declare destructiveHint=true, but the description adds meaningful beyond-annotation context: it specifies that existing content can be overwritten or removed, that the result is auto-published to the live site, and that the call consumes Kleap usage. Auto-publish and cost are behavioral traits the annotations do not encode.

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 when-to-use clause, then behavior, cost, and the prerequisite in descending priority. Every sentence carries information, though 'change or update' and 'Needs the app_id' could be tightened slightly.

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

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

An output schema exists so return values need not be described, and annotations carry the safety profile. Together with the description's coverage of triggers, destructive scope, auto-publish side effect, cost, and the find_app prerequisite, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further on the key parameter, explaining how to obtain app_id via find_app when only a site address is known — genuine semantic value beyond 'The app ID to modify'.

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 (change/update/modify) and resource (existing website), and 'existing' implicitly separates it from create_app and rename_app. The meaning is unambiguous without opening the schema.

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

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

Explicitly says when to use it ('when the user wants to change or update an existing website') and gives a concrete prerequisite routing rule — call find_app first if the user only gave a site address. It does not clarify its relationship to adjacent file-level siblings like edit_files/write_files, so it falls short of full when/when-not coverage.

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 signal mutation and destructiveness, but the description adds substantial non-obvious behavior: verified-live confirmation, no false-positive reporting, built-site auditing, bounded waiting, and the slow-deploy fallback. This goes far beyond the structured annotations and prevents agent misjudgment.

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 long but densely packed with operational instructions that earn their place. It is front-loaded with the primary purpose and then structured around critical behaviors. Slightly verbose, but the length is justified by the high-stakes, multi-step behavior it must communicate.

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 publish action with an output schema, the description fully covers what the agent needs: the verified-live guarantee, audit findings, bounded wait, slow-deploy behavior, and follow-up actions. Business-specific rules like fixing broken links are included, leaving no major operational 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 both parameters are already self-explanatory in the schema. The description adds no additional parameter-level semantics, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb-resource pair: 'take a website LIVE at its public URL.' It clearly distinguishes this tool from its sibling get_publish_status by describing the end-to-end publish action versus a status check.

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

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

It explicitly says when to use the tool (to go live), what to do after calling it (read the returned report and fix findings), and how to handle slower deploys without abusing get_publish_status. The instruction 'do not poll get_publish_status in a loop' gives concrete negative 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?

Beyond annotations (readOnlyHint=true, destructiveHint=false), the description adds the 500-row cap, pagination via offset, and the has_more continuation flag—crucial runtime behaviors an agent must know. It also clarifies that 'where' uses exact matching. These disclosures exceed annotations and help prevent failed or oversized 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?

Two sentences deliver purpose, filter semantics, row cap, and pagination instruction with zero fluff. The example for 'where' is compact but illustrative. Information is front-loaded with the action first, followed by key constraint.

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 tool's complexity (8 parameters, nested objects) and existing output schema, the description covers the primary usage, pagination boundary, and filter behavior. It does not explicitly mention ordering expectations or response shape, but those are documented in the schema/output schema. The description is sufficient for correct invocation in most cases.

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 high (88%), but the description adds meaning for two sparse parameters: 'offset' (pagination) and 'where' (exact matches, with an example). The 500-row limit also gives context for 'limit' and 'offset'. This pushes beyond the schema's 'Column equalities' and the bare offset field.

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

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

The description clearly states a specific action ('Read rows') on a specific resource ('one table of the app's database'). This distinguishes it from sibling tools like insert_database_rows, delete_database_rows, and update_database_rows, and the 'one table' qualifier helps separate it from run_database_sql.

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

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

The description implies the intended usage (reading rows with equality filters) and provides operational details like pagination and max rows, but it does not explicitly contrast with alternatives (e.g., when to use run_database_sql for complex queries or why not to use this for updates). Usage context is present but not explicit.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses meaningful behaviors: 256 KiB per-file cap, 1 MiB per-call cap, explicit truncated marking, the missing set in the response, and the Read-only key requirement. No contradiction with 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 description is front-loaded and information-dense, with workflow, alternatives, use cases, and constraints all earning their place. It slightly over-explains the return shape, which is likely already covered by the output schema, but this is a minor redundancy.

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

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

Given the read-only annotations and existing output schema, the description supplies everything an agent needs: workflow context, sibling alternatives, authentication expectations, size limits, truncation behavior, and the missing-field response. The tool can be selected and invoked correctly without additional 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 description coverage is 100%, so the baseline is 3. The description adds some workflow context for paths and aggregate call limits, but it does not materially deepen parameter semantics beyond what the schema already documents.

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

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

The description states a specific verb and resource: 'Read existing file contents.' It also frames the tool within a safe-editing workflow and contrasts it with write_files, making it clearly distinguishable from siblings like list_app_files and edit_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?

It gives an explicit workflow loop: list_app_files → read_files → edit_files → publish_app. It also states exactly when to prefer write_files instead ('when writing a whole new file') and lists concrete use cases such as fixing headers/footers, wrong phone numbers, broken links, and dead forms.

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 that the live URL and links stay intact—a key behavioral detail agents need. It also notes the absence of a delete-app tool, further clarifying limitations. This complements the readOnlyHint and destructiveHint annotations without contradiction.

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

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

The description is compact and front-loaded with the core purpose. Each of the three sentences adds essential information—purpose, URL behavior, and alternative tools—without redundancy or filler.

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

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

For a simple rename operation, the description covers the critical behavioral constraint (URL unchanged) and the exact scope (display name only). An output schema exists, so return values are covered elsewhere; nothing an agent needs 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?

The input schema already provides full descriptions for all three parameters, and the tool description adds no additional parameter-level detail. With 100% schema coverage, the baseline of 3 applies; the description neither enhances nor detracts from parameter understanding.

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 explicitly states the action ('Rename an app's display name') and clarifies the scope by noting that the URL and links remain unchanged. It also distinguishes this tool from delete_files, making its purpose unambiguous relative to 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?

The description gives clear context on what the tool does and does not change (display name vs. URL), implicitly steering agents away from using it for domain changes. It references delete_files as an alternative for file removal, but does not explicitly contrast with other app-modification tools like modify_app.

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

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

Adds substantial behavioral context beyond the annotations: partial files are preserved, a NEW task_id is returned (so the caller must poll the new id), and hard retry budgets per error class (TASK_TIMEOUT/STALE_TASK twice, TASK_FAILED once). The annotation destructiveHint=true is consistent with the resume semantics described.

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

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

Front-loaded with the core action and then layered with the critical caveats (new task_id, retry budget, error classes). Dense but every sentence carries load-bearing information; the em-dash list is efficient.

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 a mutation tool with an output schema already present, the description covers what an agent needs to invoke it correctly: trigger condition, side effects on existing artifacts, the returned handle change, and retry policy. Nothing material is missing.

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

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

Schema description coverage is 100%, so both parameters (task_id, context) are already documented. The description reinforces that task_id comes from the failed create/modify task, but adds no format or syntax detail beyond the schema. 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 (resume) and a specific resource (a failed/stalled create/modify task), and distinguishes it from the sibling create_app by framing it as resumption rather than a brand-new build. An agent can tell exactly what this does without opening the schema.

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

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

Explicit trigger ('Use this when check_task reports failed'), the named alternative it is not ('instead of starting a brand-new create_app'), and the polling follow-up ('poll check_task on that NEW id'). Exclusion conditions are also stated for non-transient errors.

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

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

Annotations already mark it as destructive and not read-only, but the description adds critical behavioral context: row/byte caps, RLS-enforced rollback, and permission requirements. These go beyond the annotations and give the agent a clear picture of side effects and constraints.

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

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

The description is compact (four short sentences) with zero fluff. The core capability and permission are front-loaded, followed by limits, RLS behavior, and the alternative. Every sentence earns its place.

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

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

For a powerful SQL execution tool with side effects and an output schema, the description covers all essentials an agent needs: what it does, permissions, parameter binding, result caps, RLS enforcement, and the read alternative. Nothing critical 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 already documents all parameters, including the $1/$2 placeholder semantics for params. The description repeats that binding ('values as $1, $2 in params') but adds no new meaning beyond the schema. Thus 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 clearly states 'Run SQL on the app's database' – a specific verb and resource. It also differentiates from sibling tools by explicitly mentioning that reads should use query_database_rows, so an agent immediately knows this is for arbitrary SQL, not just reads.

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 provides explicit guidance on when not to use the tool ('To just read rows, prefer query_database_rows') and states the required privilege (owner-level, database:write). This leaves no ambiguity about the appropriate context versus alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating that the tool returns available names across TLDs and that buying/connecting are separate follow-up actions, giving the agent a clearer model of what this call does and what it does not do.

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

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

Three sentences, each earning its place: the first states the core action and example, the second describes the return value and buy path, and the third covers the connect alternative. It is front-loaded and free of 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, the return value is already documented, and the description covers purpose, follow-up actions, and alternatives. The annotations handle safety and open-world behavior, and the schema covers parameters, so nothing necessary for correct invocation or selection 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%, and the schema already documents query, context, and tlds with examples. The description reinforces that query is a base name and that availability is checked across TLDs, but it does not add meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Search'), a clear resource ('available domains'), and the output ('available names across TLDs'), with a concrete example ('mybakery'). It also distinguishes itself from sibling tools by naming buy_domain and connect_domain, so an agent can immediately tell what search_domains does and does not do.

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 routes to alternatives: 'To buy one, call buy_domain' and 'Use connect_domain for a domain the user already owns.' This gives clear when-to-use versus when-to-use-another guidance, leaving no ambiguity about the choice between searching, buying, and connecting.

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

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

Annotations already declare `destructiveHint: true` and `readOnlyHint: false`, so the agent knows this is a mutating operation. The description adds valuable behavioral context: `where` must be non-empty and exact-match, which implies a safety guard against accidental mass updates. It also states that updated rows are returned, which is useful. No contradiction with 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 description is a single sentence that packs the essential semantics: target rows, match criteria, update values, and return value. It is front-loaded with the action and immediately clarifies the critical constraint on `where`. 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?

The tool has an output schema, so return values are already documented. The description covers the key behavioral constraint (non-empty exact-match `where`) and the mutation semantics. It doesn't mention edge cases like what happens if no rows match or if `set` contains invalid columns, but the output schema and annotations cover the safety profile. For a straightforward update tool, this is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds meaning to `where` (required, non-empty, exact matches) and `set` (new values), which goes slightly beyond the schema's terse descriptions. However, it doesn't explain `app_id`, `table`, or `context` beyond what the schema already says, so the added value is modest.

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 operation: update rows matching a `where` condition with values in `set`, and mentions it returns updated rows. It distinguishes itself from siblings like `insert_database_rows`, `delete_database_rows`, and `query_database_rows` by naming the specific action and the `where`/`set` semantics. However, it doesn't explicitly name a sibling or contrast with `run_database_sql`, which could also perform updates.

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

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

The description gives concrete usage guidance: `where` is required, non-empty, and must be exact matches (e.g., `{"id":42}`). This tells the agent when to use this tool and how to construct the filter. It doesn't explicitly state when not to use it or mention alternatives like `run_database_sql` for complex updates, but the context is clear enough for a straightforward update operation.

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

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

Goes well beyond the readOnlyHint annotation by disclosing the full side-effect model: it only returns a URL, nothing is charged before the user pays, and the agent must not claim subscription or quote prices. This is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with the usage trigger, then consequences, then parameter semantics. Every sentence is load-bearing and none repeats structured fields verbatim.

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 no elaboration, and the description covers triggers, side-effect boundaries, parameter meaning, and pricing behavior. 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 the baseline is 3, but the description adds real meaning the schema lacks — 'credits' is a legacy name and only applies to users who already have a paid plan, and 'monthly' is the default. It clarifies the enum beyond the schema's terse 'Default monthly'.

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 (obtaining a paid plan) with concrete triggers and names the exact artifact returned (upgrade_url). No sibling tool overlaps with plan upgrades, so differentiation is inherent. An agent can identify this tool's function immediately.

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

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

Explicitly lists the trigger conditions ('wants a paid Kleap plan, runs out of usage, or needs a feature that requires one') and adds behavioral guardrails ('never say they are subscribed', 'do not quote a price'). What is left is only the absence of a named alternative tool, which isn't needed since no sibling performs upgrades.

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 adds meaningful behavioral context: the operation takes ~30-60 seconds to restart, which sets latency expectations. It also explains why the preview may be sleeping. There is no contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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

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

The description is two sentences, front-loaded with the usage trigger and followed by the key latency detail. Every word earns its place and nothing is redundant.

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

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

For a simple 2-parameter tool with an output schema and annotations, the description provides all necessary operational context: when to use it and how long it takes. No critical information 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%, with both app_id and context already described in the input schema. The description itself adds no additional parameter-level meaning, so the baseline score of 3 applies.

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

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

The description clearly states the action ('wake', 'restart') and the resource ('website preview'), and it is specific about the trigger condition ('preview is sleeping'). It is easily distinguished from sibling tools like get_app or get_publish_status, even though no explicit alternative is named.

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 tells the agent when to use the tool: 'Use this when the user's website preview is sleeping.' It also provides a helpful context detail about sandboxes auto-stopping after 15 minutes. It does not list exclusions or alternatives, but none are needed given the unique purpose.

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 far beyond the destructiveHint annotation by disclosing that omitted content is silently dropped (wiping headers/footers on large layouts), that output is byte-for-byte without a Kleap-AI step, that overwrites occur by path, and that DB/auth code pushed here silently does nothing without modify_app. This level of disclosure prevents serious misuse.

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 long but well-structured with clear sections (NPM PACKAGES, IMAGES AND BINARIES, DATA & ACCOUNTS) and front-loads the core purpose. Each sentence adds value, though it could be tightened without losing essential details.

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?

Comprehensive for a complex tool: covers alternatives, silent-drop pitfalls, binary handling, package restrictions, the need for modify_app for DB/auth, and the workflow of calling publish_app afterward. With an output schema present, nothing essential for correct invocation is missing.

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

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

Even though schema coverage is 100%, the description adds critical semantics: explains encoding:"base64" for binaries with a 512KB limit, warns not to write package.json because the build replaces it, and details supported npm packages, directly enriching the files parameter's meaning beyond the schema.

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

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

The description opens with 'Write WHOLE files DIRECTLY' and immediately contrasts with edit_files for modifying existing files and delete_files for removal, making the tool's specific purpose and its distinction from siblings unmistakable.

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

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

Explicitly states 'Best for scaffolding exact pages/components' and provides clear when-not-to-use guidance by naming edit_files, delete_files, generate_image, and modify_app as alternatives for specific scenarios (modifying existing files, removing pages, adding prompt-based images, provisioning databases).

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