Kleap

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?

Beyond the sparse annotations, the description discloses status semantics, wait-capping behavior, deployment_status interpretation, and exact error-code-to-action mappings for failed tasks. This gives the agent a complete picture of how the tool behaves and what consequences its results 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 each sentence carries operational value, with important status logic front-loaded. The dense flow of status cases could be more structured, but the content justifies the length and no sentence feels wasted.

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

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

The description fully covers statuses, next actions, retry behavior, deployment status, and sibling-tool routing, so the agent can act correctly without additional research. Since an output schema exists, not describing the raw return shape is acceptable.

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 documents all three parameters with 100% coverage, including the wait cap concept)Skip. The description adds only a specific default value (8 seconds) and restates task_id's source, so it contributes little beyond the schema baseline.

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

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

The description opens with a specific verb and resource ('Check a create/modify task') and then enumerates the possible status values, making the tool's purpose unambiguous. It also distinguishes itself from get_publish_status by explicitly pointing there for unknown/aged-out task IDs.

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 strong when-to-use guidance: report the current status immediately, don't repoll in the same turn, and use get_publish_status or retry_task for specific conditions. It even clarifies that out-of-credits failures belong to create/modify, not to this tool.

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

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

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 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 and destructiveHint=false, so the safety profile is clear. The description adds that plan status is included, but does not disclose additional behavioral details such as response format or data freshness. This is acceptable for a simple read-only tool.

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

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

The description is a single sentence with no wasted words. The trigger condition is front-loaded, making it immediately actionable for the 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?

For a simple read-only query with one well-documented parameter and an output schema present, the description is sufficient. It does not mention prerequisites or edge cases, but none are evident or necessary for this tool.

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

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

The single 'context' parameter has 100% schema description coverage with its own explanation. The tool description adds no extra parameter semantics, so the baseline 3 for high schema coverage applies.

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

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

The description clearly states that the tool addresses user questions about remaining credit balance or plan status. It uses a use-case framing rather than a pure verb+resource statement, but it is specific enough to distinguish from siblings like get_analytics or get_app.

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 when to use the tool: when the user asks about their remaining credit balance or plan status. No alternatives are mentioned, but none of the sibling tools overlap with credits, so the guidance is sufficient.

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 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?

The description adds significant behavioral context beyond the annotations: it can overwrite/remove content, automatically publishes to the live site, and consumes Kleap credits. These are important side effects not fully captured by the destructiveHint annotation alone. It also explains the dependency on app_id and how to resolve it.

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 concise sentences with zero redundancy. The primary trigger ('use this when...') is front-loaded, followed by essential side effects and a prerequisite. Every sentence contributes necessary information without 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 that an output schema exists (per context signals) and the input schema is fully described, the description covers the key operational aspects: what it does, when to use it, side effects, prerequisites, and an alternative path. Nothing critical for an agent 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 parameters are already documented. The description adds extra value for app_id by explaining the address-to-id resolution workflow, which is crucial for correct usage. It doesn't add detail for message or context, but the schema descriptions are sufficient, so this is above baseline.

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

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

The description clearly states the tool's purpose: to change or update an existing website, distinguishing it from creation tools and low-level file editors. It names the resource (website), the action (modify), and the side effect (auto-publish), making the intent unambiguous.

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

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

It explicitly states when to use ('when the user wants to change or update an existing website') and provides a specific alternative: if the user provides a site address, call find_app first to get the app_id. This gives clear routing guidance and prevents misuse.

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

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

The description goes well beyond the annotations. It discloses that publishing is VERIFIED-LIVE (never reports a false positive), that it audits internal links, content contradictions, and JSON-LD/sitemap/robots coverage, that the audit comes back via get_publish_status as `report`, and that the call returns immediately while going live takes minutes. This is rich behavioral context that annotations (readOnlyHint=false, destructiveHint=true) do not provide. 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 dense but well-structured, front-loading the core purpose and then adding critical behavioral details and usage warnings. Every sentence earns its place, though it is longer than the typical description. The structure is logical: purpose, verification behavior, audit behavior, return behavior, and polling guidance.

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

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

Given the tool's complexity (verified-live publishing, audit, async behavior) and the presence of an output schema, the description covers everything an agent needs: what it does, what to expect, how to handle the async nature, and how to follow up. The output schema handles return values, so the description needn't explain them. No gaps.

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 both parameters (app_id and context). The description does not add parameter-specific meaning beyond what the schema provides, but it does add context about the overall operation. 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 ('take a website LIVE at its public URL') and clearly distinguishes this from siblings like get_publish_status (which reports status) and check_domain/connect_domain (domain setup). It also names the sibling get_publish_status explicitly, making the tool's role 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 gives explicit when-to-use guidance ('Use this to take a website LIVE'), and also provides a clear when-not-to-use: do NOT poll get_publish_status in a loop; instead tell the user it is publishing and check once when they ask again. It also instructs to read the audit report from get_publish_status before telling the user the launch went well. 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?

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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds critical behavioral details: partial files are preserved, it returns a NEW task_id that must be polled instead of the original, and it spells out retry limits and non-transient errors never to retry. This is exactly the kind of context the annotations don't capture.

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 dense paragraph that front-loads the primary purpose, then adds usage conditions and retry budget. Every sentence earns its place; the only minor deduction is that the retry details could be structured as a list for faster scanning, but it's not bloated.

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 this complexity—retry logic, error-specific rules, and a returned new task id—the description covers all essential aspects: when to use, what to expect, and how to follow up. The presence of an output schema and complete parameter coverage means 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%, so parameters are already documented. The description adds little beyond what the schema states—it does tie task_id to the failed task from create_app/modify_app, but that's already in the schema description. No additional parameter-specific semantics are needed.

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

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

The description clearly states the tool resumes a failed or stalled create/modify task, preserving partial files. It explicitly contrasts with starting a brand-new create_app, which differentiates it from sibling tools.

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

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

It provides an explicit trigger condition ('when check_task reports failed'), names the alternative not to use (create_app), and gives a retry budget with specific error categories and a hard stop rule. This gives the agent unambiguous decision 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 annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context by stating results are availability names across TLDs and explicitly warning that purchase is user-confirmed in Kleap, which goes beyond the structured 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 concise and front-loaded with the core purpose, followed by return behavior, a critical limitation, and routing to the sibling tool. Every sentence earns its place without 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 modest tool complexity, a complete input schema, annotations, and an output schema, the description covers all essential context an agent needs: what to search, what comes back, the user-confirmation boundary, and which sibling to use for owned domains.

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 query, tlds, and context. The description adds minimal parameter-level meaning beyond the example 'mybakery', so it neither compensates for missing schema info nor significantly improves 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 clearly states the tool searches for available domains for a base site name and returns available names across TLDs. It also distinguishes itself from connect_domain by noting that tool is for domains the user already owns, so an agent can tell them apart.

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 guidance: use this tool to find available domain names, and use connect_domain when the user already owns a domain. It also notes that agents cannot buy domains, preventing an inappropriate downstream action.

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.