Layero

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

The description says 'Stop a build', which is a mutating operation, but the annotations declare openWorldHint: true, meaning the tool does not modify the world. This is a direct contradiction. The description does add a useful note about the live address staying unchanged, but the core contradiction makes it severely misleading.

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 primary action ('Stop a build that is still running') followed by a clarifying side-effect. Every sentence earns its place, with no redundant information.

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

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

The description covers the main behavior and the key non-effect (live address unchanged). The output schema exists, so return values are documented. It does not mention error cases or prerequisites, but for a simple cancel operation this is adequate. The annotation contradiction, however, is a flaw in the overall tool definition, though the description itself is fairly 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?

The input schema has 100% description coverage, with detailed explanations for both parameters (deploy and project). The description adds no additional parameter information, so the baseline of 3 is appropriate. The schema already explains the deploy ID source and project naming nuances.

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 ('Stop'), a resource ('a build'), and a condition ('that is still running'). This clearly distinguishes it from siblings like retry_deploy, list_deploys, and rollback. The effect is unambiguous: cancelling an in-progress deployment.

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 provides clear context: use it when a build is still running. It does not explicitly mention alternatives or exclusions, but the purpose is evident. There is no guidance on when not to use it, but the condition 'still running' implies that it is not for finished builds, which is a clear usage boundary.

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 the tool as read-only and idempotent, and the description adds meaningful behavioral detail: it is deterministic CODE rather than model judgment, the same input yields the same findings, and each finding includes a ready replacement. This helps the agent predict outcomes and follow the tool's recommendations.

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 a one-sentence definition, followed by behavioral certainty, concrete examples of caught errors, and a clearly labeled exclusion section. Every sentence earns its place and the structure makes the boundaries easy to scan.

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

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

The description covers purpose, behavior, output style, and the key alternative. The output schema handles return-value details, and the input schema fully documents parameters. An agent has everything it needs to decide when to call this tool and how to interpret its results.

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

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

Schema description coverage is 100%, so the schema already explains `path`, `text`, and `project` including the exact-one-of constraint. The description adds no parameter-specific semantics beyond the general behavior, so the baseline of 3 is appropriate.

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

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

The description states a precise verb-object pair: checking Russian copy for mechanical typography errors, and contrasts it with the editorial resource that handles style and judgment. It clearly distinguishes 'check_copy' from the semantic alternative so an agent understands exactly what this tool is for.

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 'WHAT IS NOT HERE' section explicitly names the alternative resource (`layero://editorial/ru`) and tells the agent to use it for 'make the text better' requests, while this tool is for 'fix the typography' requests. This is explicit 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 mark the tool as read-only, and the description adds useful behavioral context: it triggers the check immediately and treats non-propagation as a normal temporary condition. This goes beyond what readOnlyHint alone conveys, though it does not discuss rate limits or other edge cases.

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

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

The description is short, front-loaded with the main purpose, and every sentence adds meaningful guidance. There is no redundant or filler content.

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

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

With an output schema present, readOnlyHint annotation, and fully documented parameters, the description provides all necessary context for an agent to call this tool correctly. The propagation warning is a valuable addition that covers the main real-world failure mode.

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 100% coverage for both parameters, including project slug/id alternatives and domain format. The tool description itself adds no additional parameter guidance, 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 states a specific verb and resource: 'Check whether a connected domain has started working.' It also differentiates itself from siblings by mentioning the immediate DNS re-check behavior, which is not covered by tools like check_copy or site_status.

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

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

The description clearly conveys when to use the tool: right after a domain is connected, when an immediate DNS check is needed instead of waiting for the background re-check. It also instructs the agent on how to handle non-propagated records. However, it does not explicitly name alternative tools or state when not to use it.

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

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

Beyond the readOnlyHint annotation, the description discloses that a run takes tens of seconds, wait=true blocks, a parallel measurement occupies the queue, and the score behaves differently from raw timings. This is substantial, useful behavioral context that the annotations alone do not provide.

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 paragraphs, no filler. The purpose is front-loaded, and every sentence earns its place: the statistical caveat is essential for correct interpretation, and the queue warning is actionable 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 output schema exists, return-value details are not required. The description covers how to invoke, how long the call takes, wait behavior, concurrency constraints, and how to judge the verdict. An agent has enough to call it correctly.

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

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

Schema coverage is 100% and the schema already describes both parameters. The description adds value by explaining the operational consequence of wait=true ('do not start a second measurement in parallel — it will occupy the queue'), which enriches the wait parameter semantics even though the schema handles the basics.

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

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

The first sentence states a specific verb plus resource: 'Measure a site's speed and say whether it got worse after a deploy.' This clearly distinguishes it from siblings like site_status or site_analytics by naming the exact purpose and the regression verdict.

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 the tool (after a deploy), explains how to interpret results (3+ point difference is meaningful, smaller is noise), and warns against parallel runs. It does not name alternative sibling tools explicitly, so it falls just short of the top score.

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 key behavioral traits beyond the openWorldHint annotation: the authorization requires user action in a browser, the tool returns a link to show the user, and checking later is done differently. This meaningfully informs the agent how the operation actually behaves.

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 well-structured: a one-sentence purpose, then the crucial browser-authorization warning, then follow-up instructions. Every sentence earns its place, and critical operational guidance is prominently placed and emphasized.

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 moderate complexity, the description covers everything an agent needs: the auth limitation, the returned link, the no-polling rule, and how to check status later. Since an output schema exists, the description does not need to enumerate return values and remains 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 fully explains both `project` and `branch`. The description adds one practical detail about omitting `branch` for later checks, but it does not redefine or enrich the parameter semantics beyond that. 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 action and resource: 'Connect Yandex Metrika to a site.' This clearly identifies the tool's purpose and differentiates it from siblings like site_analytics and read_site, which are about reading or checking data rather than establishing the connection.

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 practical usage guidance: it warns that authorization happens in a browser, tells the agent not to poll in a loop, and directs follow-up checks through the same tool without the branch argument or via site_analytics. It stops short of an explicit when-not-to-use statement, but the context is clear.

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

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

Beyond the sparse openWorldHint annotation, the description discloses critical behavioral traits: the result is DNS records that require human action at a registrar, the platform re-checks asynchronously, and the input URL is normalized automatically. This gives an agent a realistic model of the tool's non-immediate, externally dependent 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 compact yet information-dense. The purpose is front-loaded, followed by the most critical operational warning, then a useful clarification about URL normalization. Every sentence earns its place without redundant phrasing.

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 asynchronous, human-in-the-loop nature of this operation, the description covers the essential flow: the user receives DNS records, must apply them at a registrar, and should not wait because the platform re-checks automatically. With an output schema present and only two fully covered parameters, no necessary context 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?

Although the schema covers both parameters, the description adds important semantics: the domain can be passed as a full URL and will be reduced to a bare host, and the project can be a slug, id, or site address with a caveat that the address host is not always the slug. This directly improves correct invocation and resolves likely confusion.

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: 'Connect a custom domain to a site.' This clearly distinguishes the operation from siblings like check_domain and list_domains. The title also reinforces the action, but the description goes beyond a tautology by stating the actual effect.

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 behavioral guidance: show DNS records to the user, ask them to update the registrar, and do not poll for readiness. It names the follow-up tool check_domain for verifying status later and warns that spinning wastes time and context, effectively saying when not to keep waiting.

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 indicate openWorld and destructive, and the description reinforces with 'OPENS DATA TO THE INTERNET', mentions row-level security warnings, exact command matching and refusal if grants changed. It adds significant context beyond annotations, including admin token requirement for preview.

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 few paragraphs, front-loads purpose, then provides sequential usage steps and warnings. It is efficient and well-structured, though slightly verbose in places; every sentence contributes to usage or behavior.

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 11 parameters, output schema, and complexity, the description covers the core workflow (preview→apply), consent handling, and key warnings. It doesn't detail every parameter but schema handles that. It is complete for an agent to safely use the tool.

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

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

Schema covers all parameters with descriptions (100%), so baseline is 3. The description adds semantic context for confirmed and expected_sql, linking them to the preview step and explaining when they are required. It enriches param understanding without redundancy.

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 the tool grants access to a table or function method, showing SQL and applying after consent. It is specific about the resource (method of table/function) and distinguishes it from listing tools like data_api_methods, though it could more explicitly name alternatives.

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 step-by-step guidance: call without apply first to preview, then apply with consent (through forms or chat), pass confirmed=true with expected_sql. It warns about grants changing and refusal, and states admin scope requirement. This is 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?

Beyond the destructiveHint annotation, the description thoroughly explains destructive and sensitive behaviors: list never exposes key values, issued keys are shown once and not stored, revoking breaks all users including in_build usage, and admin scope is required. This is exactly the behavioral detail an agent needs.

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

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

The description is front-loaded with the tool's actions, then adds only operationally critical details in a logical order: consent, secret handling, revocation impact, and auth. There is no filler or redundant restatement of schema fields.

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 security-sensitive key-management tool, the description covers the essential operational, consent, and side-effect information an agent needs. Combined with the rich input schema and output schema, nothing important is missing for safe 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. The description adds genuine extra meaning beyond the schema by explaining the consent flow, the one-time return of secret values, and the in_build blast radius of revocation, which helps an agent reason about the confirmed, kind, and key parameters.

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

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

The description states a specific verb+resource combination: Data API keys can be listed, issued, and revoked. This clearly distinguishes it from sibling tools like data_api_grant or data_api_methods without needing to inspect schemas.

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

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

The description gives concrete usage context: consent requirements, when to set confirmed=true, admin-scope needs, and the one-time secret handoff. It does not explicitly name alternative sibling tools or say when not to use this tool, but the action-oriented instructions are clear enough for an agent to act correctly.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds valuable behavioral context by defining the four access levels (closed, visitor, user, server) and stating that the data is read from role grants 'exactly as the gateway sees them.' This clarifies both the source and the freshness semantics, which goes beyond the annotation.

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

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

The description is compact and front-loaded: the first sentence states the resource and scope, the second defines the access levels, and the third explains the source of truth. Every sentence earns its place with no filler or repetition.

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

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

With an output schema present, the description need not explain return values, and the parameters are fully documented in the schema. The description sufficiently explains the access-level semantics and source. It is slightly incomplete only because it does not provide any guidance on when to choose this tool over siblings, but that is a usage-guidance gap rather than a completeness gap for invocation.

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

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

Schema description coverage is 100%, so the meaning of database and organization is already fully documented. The description does not add parameter-level details, such as which database is selected by default or how organization disambiguation works. Given the high schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly identifies the resource: the database's REST and RPC methods and their per-HTTP-method access levels. It distinguishes this from sibling tools like data_api_status and data_api_grant by focusing on method-level access. However, it lacks an explicit verb such as 'lists' or 'returns', so the action 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?

The description explains the meaning of access levels and the source of the data, but it never states when to use this tool versus alternatives. There is no mention of data_api_grant for changing access, data_api_probe for testing, or data_api_status for overall API status. The agent is left to infer appropriate usage from the tool name and sibling context.

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 indicate destructiveHint and openWorldHint. The description adds valuable context: a removed site is refused on every request, adding a site opens no data by itself (access levels decide), and consent is required. This 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?

Four sentences, front-loaded with the core purpose, then practical constraints. No fluff; every sentence adds necessary context.

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

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

Given the 6-parameter tool with an output schema and annotations, the description covers the essential behavior: actions, consent, automatic addresses, and token scope. It could mention error handling but that's not required. It is complete enough for an agent to call correctly.

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

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

The schema has 100% coverage with detailed descriptions for every parameter, including the 'confirmed' consent warning. The description adds a high-level caution about not adding automatic addresses but does not substantially expand on individual parameter semantics 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 clearly states the resource (sites allowed to call the database from a browser) and the actions (list, add, remove). It distinguishes itself from sibling tools by focusing on origin management, and the specific resource is unambiguous.

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

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

It explicitly warns against adding automatically allowed project addresses and mentions the consent requirement for add/remove. It also states the admin token requirement. It doesn't name alternatives but the resource is specific enough to infer when to use it.

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

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

Annotations indicate openWorldHint=true and destructiveHint=false, and the description adds substantial behavioral context: writes are rolled back, but sequence numbers, external calls, session locks, and quota are not rolled back; answer is real; needs admin scoped token. This goes beyond the annotations significantly. Minor gap: no mention of rate limits or errors, but the rollback caveat is valuable.

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, front-loaded with the core purpose, and every sentence contributes: purpose, rollback caveats, realness of response, and auth requirement. No fluff; 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 9 optional parameters, output schema presence, and annotations, the description covers purpose, safety, auth, and key side effects. It could mention what the response contains (real response body), but output schema existence and the statement 'The answer is real' suffice. Small gap: no mention of idempotency or concurrency, but not necessary for a probe tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by clarifying role semantics ('visitor — a visitor with the public key', 'user — a signed-in user (needs user_id)', 'server — the secret key') and schema resolution order ('api → public → app'). This exceeds schema-provided descriptions and helps 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 states a specific verb ('probe' / 'A real request to a method through the gateway') and a specific resource (Data API method via gateway). It distinguishes from siblings like data_api_grant, data_api_keys, data_api_methods by emphasizing execution and real response with rollback. Clear and actionable.

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 explains when to use it: for a real request with real grants, row policies, refusals; clarifies that writes are rolled back but side effects remain; notes admin scope token requirement. It contrasts with sibling tools implicitly by focusing on probing a method vs managing keys/grants. This is explicit enough for an agent to select correctly.

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

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

Annotations declare readOnlyHint=true, and the description reinforces this by stating the API cannot be enabled. It adds valuable specifics: keys are shown only as prefixes, secrets are never returned or stored, and enabling is a manual dashboard decision. This goes well beyond the annotation and fully discloses behavior.

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

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

Three concise sentences, each carrying meaningful information. The first states the primary purpose, the second discloses key security behavior, and the third explains a critical constraint. No 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?

The description covers what the tool returns and its constraints. An output schema exists, so return format details are not needed. The only minor gap is not explicitly stating how defaults work for omitted parameters, but the schema descriptions cover that. Overall, sufficient 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?

The input schema descriptions already cover both parameters (database and organization) with defaults and explanations. The description does not add parameter-specific details, but the schema is sufficient. Since schema description coverage is 100%, a baseline of 3 is appropriate.

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

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

The description explicitly states what the tool returns: enabled status, address, keys (as prefixes), and allowed sites. This clearly differentiates it from sibling Data API tools like data_api_keys, data_api_origins, and data_api_methods, which focus on individual aspects. The verb is implicit but the resource and scope are specific.

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 conveys a key usage constraint: the API cannot be enabled via this tool, which sets expectations for read-only behavior. It implies the tool is for checking status, not for modifying. It doesn't explicitly contrast with alternatives like data_api_probe, but the purpose is clear enough from the context.

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

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

Annotations only provide readOnlyHint=true, so the description carries the burden of explaining behavior. It discloses that only the tail is returned, that `truncated` indicates dropped earlier lines, and that build-log noise is hidden before tail cutting with `include_noise=true` to override. This is substantial value beyond 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 compact and well-structured: it fronts the purpose, gives usage guidance, then explains the tail and noise behavior. Every sentence earns its place with no filler or repetition.

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

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

Given the read-only annotations, complete parameter schema, and existing output schema, the description covers what an agent needs: when to choose this tool, what to expect in the response, and how to handle edge cases like truncated tails and hidden noise.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining the interaction between `include_noise`, `noise_hidden`, and the tail, which adds meaning beyond the schema's per-parameter 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?

The description clearly identifies the tool as returning raw log lines and positions it as the fallback when `diagnose_deploy` analysis is insufficient. It distinguishes the tool from the sibling by contrasting analyzed diagnosis with direct log inspection.

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 to start with `diagnose_deploy` and to use this tool only when the cause is vague or when interested in app behavior rather than failure. This is concrete when-to-use and when-not-to-use guidance naming the relevant alternative.

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

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

Beyond the readOnlyHint annotation, the description reveals substantial behavioral detail: the response is a parsed cause, not a log tail; log excerpts are untrusted; `(as built)` vs `(current settings)` values differ; missing keys are normal and not a problem; and `next_actions` codes like `runtime_idle` are explained. This is rich, non-obvious context that directly affects how an agent interprets results. 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 long, but the tool is complex and the length is largely justified by important caveats about data provenance, missing fields, untrusted logs, and machine-readable action codes. It is organized into themed paragraphs and front-loads the core purpose and deployment-selection behavior. A bit of redundancy around `next_action` and `next_actions` could be trimmed, so 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?

Given the tool's complexity, the description is remarkably complete: it explains what the response contains, what each semantic group of fields means, how to interpret missing keys, which log excerpts are untrusted, and what the agent should do next. The presence of an output schema means return-value structure does not need to be repeated, and the description covers the non-obvious behavioral context thoroughly.

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 reinforces what the schema says about `deploy` and `project`, adding a bit of context like the deploy id coming from `list_deploys` and the address host not always being the slug, but most of this is already in the schema. It provides no substantial new parameter-level meaning.

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

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

The description opens with a specific verb+resource: diagnosing why a deploy failed, with the parsed cause rather than a raw log. It explicitly contrasts itself with log tails and clearly differentiates from sibling tools like deploy_logs, list_deploys, and retry_deploy. No ambiguity about what this tool does.

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 usage context: call it to find why a deploy failed, use the latest build by default, and pass a specific deploy id to inspect an older one. It also tells the agent to read `verdict`, fix the code, and deploy again, framing the expected workflow. It does not explicitly name alternative tools or say when not to use it, which keeps this from 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?

This is a strong disclosure: it explains that values are deliberately never returned, why that is so, how to respond if a user asks for a key, and that variables apply only at build time. These behaviors go well beyond the destructiveHint annotation and materially protect both the agent and the user from leaking secrets.

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 average but every sentence earns its place: the purpose is front-loaded, the critical never-read-back rule is emphasized, and the set/unset semantics plus deploy requirement are cleanly separated. It is dense without being 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?

Given the tool's destructive potential and the risk of secret leakage, the description covers all critical operational facts: what is returned, what is never returned, how set and unset behave, and the post-change deployment requirement. The output schema handles structural return details, so nothing an agent needs to call this safely is missing.

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

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

The input schema already has 100% description coverage, and descriptions for action, keys, values, and project are explicit. The tool description reinforces key semantics like 'set does not require knowing the other variables' and 'unset removes only the named ones', but these are largely restatements of the schema's own parameter descriptions rather than new meaning.

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

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

The description opens with a clear resource (project environment variables) and three specific verbs (list, set, remove), so an agent knows exactly what the tool is for. It also differentiates itself from sibling tools like list_environments by focusing on environment variables with mutating actions, not just environments.

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 operational context: values are never read back, set preserves other variables, unset only affects named keys, and changes require a new deploy. It does not explicitly name alternatives or when-not-to-use conditions, but the action enum and resource scope make the intended usage evident.

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

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

Annotations only include openWorldHint, so the description carries full behavioral burden. It discloses that creation is a mutation, explains the setup wizard behavior, notes that detection values are NOT pinned (contradicting common assumptions), describes provider-specific shapes (GitHub vs others), and mentions the historical bug in 2.1.1. It also explains the `needs_connection` result and webhook registration. Extremely 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 long, but every section adds necessary context for a complex tool. It is front-loaded with the core purpose, then logically organized into behavior, provider shapes, and monorepo/duplicate handling. While it could be tightened, the density is justified given the tool's complexity. Slightly verbose but 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?

Given the 7-parameter complexity, the provider differences, and the detailed output semantics (already_linked, linked_projects, app_dir_candidates), the description is comprehensive. It explains return values in the output schema and covers edge cases like multiple organizations and nested GitLab paths. An agent has everything needed to call it correctly.

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

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

Schema covers 100% of parameters, but the description adds substantial nuance: `name` defaults to repo name and must be distinct for second monorepo app; `deploy` controls whether setup wizard finishes; `root_directory` has specific rules for re-importing linked repos. These details go beyond the schema's basic descriptions, enriching the agent's 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 states the primary action clearly: 'Create a Layero project from a repository'. It differentiates from siblings by explaining the push-to-preview behavior and explicitly mentioning `my_projects(repo=…)` as an alternative for duplicate checks. The verb and resource are unambiguous, and the scope is well defined.

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: explains the workflow after linking (push to branch = preview, push to production = production), and covers edge cases like monorepo (separate calls per app) and duplicate prevention (must provide a new root_directory). It also names the alternative tool `my_projects` for checking existing links. Clear context and exclusions are present.

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 idempotentHint, so the safety profile is covered. The description adds meaningful behavioral details beyond that: the meaning of `source` (`git` vs `cli`), `duration_s` being null while running, `failure_stage` for failed builds, and `is_active` indicating the live build. It also notes timestamps are UTC. These details clarify the tool's behavior without repeating what annotations already say.

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 well-structured: purpose first, then usage guidance, then field details. Every sentence contributes useful information, and the structure makes it easy to skim. It is longer than the simple examples but appropriately so given the richness of the return object.

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 list operation with a comprehensive output schema, the description covers the essential context: what the tool returns, how to use it, and how it differs from related tools. It explains key edge cases like null duration and failure stages, and it references the output schema implicitly by detailing fields. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add additional meaning for the request parameters (`project` and `limit`); it focuses on the shape of each build object rather than the input parameters. The schema already fully documents the parameters' semantics, so the description adds no extra value 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 opens with a clear, specific statement: "The project's latest builds: how each one ended, how long it took and which one is live now." This identifies the verb (list), the resource (project builds), and the key outputs, distinguishing it from sibling tools like rollback and site_status.

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

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

Explicit usage guidance is provided: "Use it to pick a target for `rollback` or `diagnose_deploy`." It also gives a clear alternative: "For 'what is up with the site right now' `site_status` is enough and cheaper." This tells the agent exactly when to choose this tool over others.

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 idempotentHint, so the safety profile is covered. The description adds scope ('project's own domains') and result content ('state'), which is useful context beyond annotations, but it doesn't disclose pagination, filtering, or any additional behavioral traits.

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

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

A single, front-loaded sentence with no filler. Every word contributes meaning, and the noun-phrase structure works because the tool name supplies the verb.

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 low-complexity read-only tool with one well-documented parameter and an output schema, this is nearly complete. It could be richer by referencing alternatives or stating return-shaped details, but the existing schema and annotations cover most invocation needs.

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

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

Schema coverage is 100% and the project parameter is already well documented with slug/id/address examples. The description itself adds no parameter-specific meaning beyond implying the listing is scoped to a project.

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

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

The description identifies the resource ('project's own domains') and the info returned ('their state'), which is clear from the name and title. It doesn't explicitly distinguish itself from sibling tools like check_domain or connect_domain, though 'own domains' hints at project-scoped domain listing.

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

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

No guidance is provided about when to use this tool instead of check_domain, connect_domain, or site_status. The description gives no exclusions, alternatives, or selection conditions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: environments are one per branch, the url host ends with -<branch>, production is ALSO served at a canonical address, and addresses must not be assembled. These are non-obvious details that help the agent interpret results correctly.

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: first defines the resource and its structure, then states the exact questions it answers ben, and ends with a critical usage constraint. Every sentence carries necessary information with no filler.

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

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

For a single-parameter read-only tool with an output schema and both safety annotations, the description covers the essential semantics: environment-to-branch mapping, address construction rules, build state availability, and the canonical production address exception. Nothing critical is missing for an agent to invoke and understand results.

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

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

Schema description coverage is 100%, so the schema already fully documents the sole project parameter, including slug, id, working site address forms, and the caveat that the host is not always the slug. The tool description itself adds no further parameter-level semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: it lists the project's environments, explains they are one per branch or the single cli one, and states that each has an address and latest build state. It explicitly answers concrete questions ('where is the preview of my branch', 'what is on production now') and distinguishes itself from related sources like site_status and my_projects.

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 clearly states when to use the tool by framing it as the answer to preview/production location questions resources, and gives a strong behavioral rule: 'Take addresses from here, never assemble them.' It references site_status/my_projects for the canonical production address, which implies alternatives, though it does not explicitly enumerate when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context: that connecting tokens is done by a human in the dashboard, not via this tool, and that the tool is a prerequisite check. This goes beyond the annotations without contradicting 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?

Three sentences: purpose first, then when to use, then a critical behavioral note. No wasted words, information is front-loaded, and every sentence carries meaningful guidance. Very 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?

For a simple read-only listing tool with one optional parameter and an output schema, the description covers purpose, usage timing, and a security-relevant instruction. Nothing an agent needs to call it correctly is missing, especially with annotations covering safety and idempotency.

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 parameter 'organization' is fully described in the schema, including default behavior and ambiguity resolution. The description adds no extra parameter detail, so with 100% schema coverage the baseline of 3 is appropriate. The description's focus is on usage context rather than parameter semantics.

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

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

The description explicitly states the tool lists supported git providers and which are connected (GitHub App installations and provider tokens). It clearly identifies the resource and action, and distinguishes itself from siblings by referencing import_repo and the provider connection context.

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 usage guidance: call before import_repo when unsure about provider connection. It also gives a critical behavioral instruction about never asking users to paste tokens, which prevents misuse. This clearly routes the agent to the right time and context.

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 idempotentHint=true, so the safe read behavior is covered. The description adds value by explaining the semantics of the returned fields (url, repo, branch, root_directory) and their null cases, as well as the context-flooding concern behind the default limit. This goes beyond the annotations without contradicting 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?

The description is compact and well-organized: a single-sentence purpose, a rationale for the default limit, and a separate paragraph for field semantics. It is front-loaded with the core function and avoids fluff, though it could be trimmed slightly without losing meaning.

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 safety, the description fully covers the essential behavioral and field details. It explains default behavior, when to adjust the limit, and the meaning of null values, leaving no critical gaps for an agent to call 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 coverage is 100%, so both parameters (repo and limit) are documented. The description adds extra guidance: for repo, it suggests using it to check repository linkage and folders; for limit, it explains when to raise it. This enhances the schema definitions without redundancy.

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 'The user's sites on Layero,' which clearly indicates a listing of the user's projects. It further clarifies the default limit and the fields returned, so an agent can infer it is a read-only list. It does not explicitly use a verb like 'list,' but the intent is unambiguous and distinct from any sibling 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?

The description provides context on when to adjust the default limit ('raise it only when the user is looking for an old site'), and it explains the rationale for the 30-item default. However, it does not mention any alternative tools or explicitly state when to choose this tool over others, though no sibling appears to directly compete with it.

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

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

Beyond the destructiveHint=false annotation, the description discloses that nothing is built or served and that the address only answers after the first publish. This is valuable behavioral context. It doesn't discuss permissions or idempotency, but for a create tool this is a minor gap.

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

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

Three concise sentences with the core action first, followed by the sibling alternative and the key behavioral caveat. No wasted words and the structure supports quick understanding.

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

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

Given the low complexity, complete input schema, and existing output schema, the description covers everything an agent needs to decide when and how to call this tool. The workflow and non-availability behavior are clearly stated.

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 name and organization in detail. The description adds workflow context but no additional parameter-level meaning, matching the baseline of 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?

States a specific verb and resource: 'Create an empty project with no repository'. It also explicitly distinguishes itself from import_repo, so an agent can tell them apart 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?

Gives explicit when-to-use and when-not-to-use guidance: for empty projects use this tool, for projects from a repository use import_repo. It also clarifies that this is a prerequisite for a later publish_site or deploy.

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

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

Beyond the destructiveHint annotation, the description discloses that `update` changes how the project is built, that nothing is rebuilt by the update itself, and that applying it requires `retry_deploy(redeploy=true)` or a push. It also explains precedence and locked_by_file behavior, which is meaningful behavioral context not derivable from 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 every sentence earns its place: purpose, return semantics, precedence, safety warning, and follow-up action are all covered without repetition. The key scoping statement is front-loaded, and the update warning is placed clearly before the usage guidance.

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

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

For a complex tool with 13 parameters and two actions, the description covers the critical high-level context: what each action does, what the return data contains, how precedence works, what the safety expectation is, and how to trigger a rebuild. The rich schemas handle parameter-level detail, so nothing essential 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 schema already documents each parameter. The description adds value by grouping parameters by where they belong (`layero.json` vs this tool), explaining the precedence semantics that affect `build_command`, `framework`, and related fields, and clarifying that `policy: "locked_by_file"` means changing the project setting will not affect the build.

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: 'Build settings of a project: read them, or change them without the dashboard.' It also names the two actions (`get` and `update`) and the motivating case (detection guessed wrong on folder, type, or command), making the tool's identity 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 explicitly says when to prefer `layero.json` in the repository versus this tool, and names what this tool is for: 'what the file cannot hold (`root_directory`, `project_type`) and for projects you cannot push to.' It also tells the agent to ask the person before updating unless they asked for exactly that change.

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 deprecation status, compatibility window, and eventual removal — useful context beyond the minimal `openWorldHint` annotation. However, the actual behavior is only conveyed via 'same behaviour' as `publish_site`, without detailing what the operation does, side effects, or failure modes. For a deprecated compatibility alias this is acceptable but not fully 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 compact, front-loads the critical deprecation directive, and has no filler. Every sentence contributes to the deprecation message and usage guidance. The structure is ideal for a tool that exists only as a compatibility shim.

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 deprecated alias, the description is nearly complete: it identifies the replacement, explains why it still exists, and gives a removal timeline. The only gap is that it does not describe the underlying publish behavior, but that is intentionally delegated to `publish_site`, and the provided schema plus output schema cover invocation details.

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 descriptions for all parameters, so the baseline is 3. The top-level description adds no parameter information itself; the schema descriptions reference `publish_site` and give brief explanations like 'the project slug', but they rely on the sibling tool for full meaning. This is adequate but not exceptional.

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 immediately identifies the tool as deprecated and points to `publish_site` as the replacement, which clearly distinguishes it from the sibling list. It states the intended action ('use publish_site') and the resource it refers to, so an agent can correctly decide not to invoke this 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?

The description explicitly states when to use this tool (legacy configs/prompts written before 17.09.2026) and when not to use it (new instructions must call `publish_site`). It also tells that the tool will be removed in the next release, providing complete routing 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 sole openWorldHint annotation, the description discloses statelessness ('the server does not remember the bundle between calls'), silent corruption of binary files sent as text, async return behavior (~40s with status 'building' and deploy_id), non-idempotency (a second call starts a SECOND build), overwrite risk from git push, and the sign-in requirement. These are exactly the behaviors an agent must know before calling. 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 long (~14 sentences) but front-loaded with purpose, and each sentence carries an operational warning or routing decision rather than filler. Minor redundancy with the schema (encoding rules, file limits) prevents a 5, yet the length is justified by the tool's many foot-guns and by the cost of an agent getting any of them wrong.

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 high-complexity, mutating tool with an output schema, the description covers every practical edge case: repository state, build steps, authentication, binary encoding, statelessness, re-publishing, and asynchronous completion. Since an output schema exists, it need not spell out the full return shape, and it still explains the crucial async/retry behavior. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine semantics beyond the schema: the files parameter carries the warning to send ACTUAL current file contents because the server is stateless, and project is framed as 'when republishing the same site' with fallback lookup behavior. Some encoding and limit details duplicate the schema, but the description meaningfully enriches 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 first sentence states a specific verb and resource: 'Publish a static site to Layero — from here, with no terminal.' The phrase 'Takes ANY ready static bundle' plus the build-step exclusion distinguish it from the landing-specific sibling publish_landing and from CLI-based deploy flows. An agent can tell immediately what this tool is for.

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

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

Usage is spelled out explicitly with conditions: use it when the project has no connected repository; do NOT use it when site_status shows a repo (the next git push would overwrite), when a build step is needed (publish build output or use the CLI), or when no Layero account exists (CLI `npx layero@latest deploy --claim`). It also routes empty projects to project_create, leaving nothing to inference.

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

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

Beyond the readOnlyHint annotation, the description discloses key behaviors: the result is a structured summary rather than raw HTML, the full source lives on the disk, and `served_fallback=true` indicates a missing page served via the home page. This adds deep behavioral context that annotations alone do not provide.

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 essential outcome ('What is really published'), then gives precise usage cues, then explains output structure and edge-case behavior. Every sentence earns its place; nothing is redundant 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?

Given the output schema covers return structure and annotations cover safety, the description is complete: it explains when to use, what to expect, why the structured view matters, and how to interpret the critical fallback flag. An agent has enough context to call and trust 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?

Input schema already fully documents both parameters, so baseline is 3. The description adds meaningful behavioral semantics around the `path` parameter by explaining what `served_fallback=true` means for resolving a path, and clarifies that the result is not raw source. This goes beyond schema definitions.

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 the specific verb 'read' and resource 'site page,' and precisely defines the subject as 'what is really published' — headings, copy, forms, meta, links. This clearly distinguishes it from sibling write/publish/check tools and makes the tool's scope immediately obvious.

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 timing guidance: call it 'BEFORE changing anything on a live site and AFTER a publish.' It also explains the underlying reason (disk vs served content drift), so an agent knows when the tool is necessary and when relying on local state would be unsafe.

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?

Even with readOnlyHint and idempotentHint already present, the description adds substantial behavioral context: it publishes nothing, returns changed HTML, answers changed=false on repeated calls, treats an empty change list as a non-error, and insists on not silently rewriting someone's site. This goes well beyond the annotations.

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

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

The description is well structured and front-loaded: core behavior first, then safety, exclusions, and measurement guidance. Every sentence earns its place, and the bolded 'WHAT IS NOT HERE' section makes the boundaries easy to scan.

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

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

Given the schema, annotations, output schema, and sibling context, the description is complete. It covers what the tool returns, what the agent must do before publishing, idempotency semantics, excluded transformation types, and how to evaluate results with check_performance.

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 input schema already documents both html and fix, including the enum meanings. The description adds no new parameter-specific semantics beyond referring to a 'named markup transformation,' so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'One named markup transformation — with a predictable result.' It immediately clarifies the tool's narrow scope and explicitly contrasts itself with publishing and file-dependent transformations, so an agent can tell it apart from publish_site and site_issues without confusion.

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 workflow guidance: the tool returns changed HTML and the agent must show it, get consent, and call publish_site. It also names site_issues for problems the tool does not handle and check_performance for measuring gain, making when-to-use and when-not-to-use unambiguous.

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

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

The description goes far beyond the single `openWorldHint` annotation. It discloses that refusal on running builds is protection rather than an error, that `redeploy=true` can push resulting changes live on the production branch, that changed `project_settings`/`env_vars` are applied, and that repository-less projects are redeployed via CLI or `publish_site`. This is thorough behavioral disclosure.

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

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

The description is structured with a one-line summary, dedicated paragraphs for the default and redeploy modes, and a warning paragraph. Although it is long, every sentence carries operational information and the key distinction is front-loaded. It is dense but not padded.

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 definition covers state constraints, parameter interactions, the non-repository fallback, production impact, and when to use `diagnose_deploy` instead. Since an output schema exists, explaining return values is unnecessary. There are no significant gaps an agent needs 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?

All 4 parameters already have complete descriptions in the schema (100% coverage), so the baseline is 3. The description adds value by explaining how `redeploy` switches between the two execution modes, how `deploy` is ignored when `redeploy=true`, and how `branch` defaults to the production branch. This extra interaction context justifies a 4.

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

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

The opening sentence 'Run a build again — a failed one as is, or the latest commit afresh' clearly states the operation and its two core modes. It is highly specific about the resource (build) and the state conditions, and it distinguishes itself from sibling tools like `diagnose_deploy` by naming them when relevant.

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 states when the default mode is allowed (`failed`/`cancelled`) and when it is refused (`queued`/`building`/`ready`) with a pointer to use `redeploy=true`. It also gives clear guidance to run `diagnose_deploy` first for code-related failures and only then retry, providing an explicit when-to-use vs alternative decision path.

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

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

Annotations already mark this as destructive and open-world, but the description adds meaningful behavioral detail: it changes what visitors see, is reversible in one sense but not in lost visitor time, and behaves differently for app deployments. This goes well beyond the annotations without contradicting 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?

The description is longer than two sentences, but every section earns its place: the visitor-impact warning, the reversibility nuance, and the app-specific caveat are all essential. The main purpose is front-loaded, and the structure is clear. Slightly more verbose than necessary, hence 4.

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 only two parameters, no nested objects, and an output schema, the description covers all necessary operational context: what it does, when to call, risks, failure modes, and fallback behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and both parameters already have detailed descriptions in the schema. The tool description does not need to repeat that information. It adds no significant parameter-level semantics, so a 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 a specific action and resource: 'Put the previous working build back on the live address.' This distinguishes it from sibling tools like retry_deploy or cancel_deploy, which deal with deploys differently. The purpose is unambiguous.

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

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

The description gives explicit when-to-use context, instructs the agent to ask the person before calling unless explicitly requested, and provides detailed guidance for app-type projects where rollback often fails, including what to do instead and not to repeat the call. This is strong 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 already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond those annotations: the meaning of score (relative within one answer, rare query words in titles weigh most, pages matching every word rank higher), the fact that the index is refreshed hourly, and the fact that searching requires no token. These go beyond what annotations convey.

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

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

The description is compact and front-loaded: the most operationally important fact (no token needed, use before guessing) comes first, followed by the scope list, then return format/usage of results, then scoring semantics, then index freshness. Every sentence earns its place; no filler or redundancy with the schema.

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

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

For a read-only search tool with an output schema, the description is complete: it explains the search subject scope, the result contents, what to do when a snippet is insufficient, how the relevance scoring works, the freshness of the index, and the auth situation (no token). Nothing needed to select or invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining what kinds of queries are appropriate ('environment variables', 'layero.json node version', 'rollback', 'monorepo root directory') and clarifying the Russian/English matching behavior. The score semantics also indirectly help the agent interpret the relevance of the returned results. It does not repeat schema field mechanics, so it earns 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 names a specific resource (docs.layero.ru), a specific verb (search), and states its exact scope: platform documentation covering build settings, layero.json, environments, preview URLs, custom domains, env vars, runtime apps, Data API, CLI flags, and JSON events. It is unambiguously distinct from siblings — all other tools are domain/deploy/data-api operations, none of which is a documentation search.

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 an explicit usage rule: 'Use it before guessing how the platform works,' followed by a concrete list of topics to search. It also tells the agent what to do with the result — open the returned URL with its own fetch tool when the snippet is insufficient — which resolves the ambiguity around the lack of a fetch capability inside 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 declare readOnlyHint=true, and the description adds meaningful context beyond that: the time series is collapsed into a direction, breakdowns are capped at five, and detailed chart points are deliberately omitted. This prevents an agent from expecting raw time-series output and is genuinely useful behavioral disclosure.

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

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

Two compact sentences with the core output front-loaded in the first sentence. The second sentence explains the collapse/truncation and its rationale, earning its place, though the informal phrasing is slightly cryptic.

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 available and readOnlyHint annotation present, the description does not need to detail return values. It conveys the tool's scope, a key data transformation, and the absence of interpretive help. Minor gaps, like defining 'direction' and 'breakdowns', are acceptable given the output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions that time series are collapsed and breakdowns are cut to five, which indirectly relates to the period parameter, but it adds no parameter-specific semantics 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 names the resource (site traffic) and the three output dimensions: totals, direction, and top sources. It is clearly distinguishable from sibling tools like check_performance or site_status, though it uses a noun phrase rather than an explicit verb like 'retrieve' or 'list'.

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

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

Usage is implied: this is the tool to call when a site-traffic summary is needed. However, it does not name alternatives or give explicit when-not-to-use guidance, so an agent must rely on the title and sibling names to infer routing. The 'conclusion is yours to draw' note is behavioral, not an alternative.

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, so no safety disclaimer is needed. The description adds behavioral context beyond that: findings are sorted by importance, limited to actionable issues, and each finding has a location and action. The instruction not to dump the list clarifies expected interaction 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 definition is front-loaded with the core purpose, then a short contrast with check_performance, then illustrative examples, then an agent instruction. All sentences earn their place and there is 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?

With an output schema present, the description doesn't need to detail the return structure. It covers scope (page), actionable nature, sorting, and output handling. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the schema already explains path defaults and project lookup semantics in detail. The description does not add parameter-level detail beyond reinforcing 'page' context for path. 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 opens with a precise definition: 'Concrete problems of a page — each with its location and what to do', naming the resource and output. It also differentiates itself from check_performance by explicitly stating it is NOT a score. The examples (blocked indexing, missing meta/alt, etc.) make the tool's scope concrete.

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

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

It explicitly contrasts itself with check_performance: scores give nothing to fix, while this tool returns only items with a location and clear action. It also tells the agent exactly how to behave: sort by importance, surface only two or three main findings, and ask before fixing. This is crisp when-to-use and how-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?

The readOnlyHint annotation already marks it as read-only, but the description adds crucial behavioral context: the screenshot is taken at build time, not now, and a fresh one does not appear instantly after a publish. It also warns about the high context cost of images. These are behavioral traits not derivable from annotations alone.

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

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

The description is well-structured: purpose in the first line, then complementary relationship, then timing warning, then cost advice. Each paragraph earns its place, though it could be slightly tighter. The key warnings are front-loaded after the purpose.

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

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

For a single-parameter read-only tool with full schema coverage, the description fully covers purpose, usage context, timing behavior, and cost trade-offs. Nothing an agent needs to invoke it correctly is missing.

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

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

The schema already provides 100% coverage of the single `project` parameter, including accepted formats (slug, id, or URL) and the caveat that the address host is not always the slug. The description adds no parameter-level information beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource: 'A screenshot of the latest built version of the site — how it looks.' It explicitly differentiates from sibling tools by naming the complementary questions read_site and site_issues answer, so an agent can immediately tell what this tool is for.

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

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

It gives clear when-to-use ('Useful before and after a visual change') and when-not-to-use ('Do not call it "just in case"') guidance, and explicitly routes the 'what is wrong' question to site_issues as cheaper and more specific. 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 provide readOnlyHint=true, and the description does not contradict this. The description adds substantial behavioral context beyond the annotation: it explains what `serving` means (any response that is not a Layero platform screen and not a 5xx), how `answered_by` distinguishes site/platform/none, that redirects are not followed, that static sites may serve a fallback home page with code 200, and that the call may block when `wait_s` is used. This is rich behavioral disclosure that goes well beyond the read-only hint. It loses one point because it doesn't explicitly state that the tool is read-only/non-destructive, but the annotation already covers that.

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

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

The description is well-structured with clear paragraph breaks by topic: overview, serving semantics, build waiting, and static site fallback. It is front-loaded with the core purpose. It is somewhat long, but every section earns its place by explaining non-obvious behavior. It loses one point because it is dense and could be tightened in places (e.g., the `answered_by` enumeration could be more compact), but overall it is appropriately sized for the complexity it covers.

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 (three concerns consolidated, nuanced serving semantics, build-waiting behavior, static fallback), the description is remarkably complete. It covers the key output fields (`serving`, `answered_by`, `platform_screen`, `redirect_to`, `poll_after_s`, `waited_s`, `served_fallback`), explains edge cases (API 404s, redirects, missing files), and provides operational guidance (timeout warnings). An output schema exists, so return values don't need full documentation, but the description still explains the non-obvious semantics. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds meaningful context beyond the schema: it explains how `path` interacts with API servers that lack a `/` route, how `wait_s` interacts with client timeouts, and how `project` can be a slug, id, or site address with the caveat that the address host is not always the slug. This is valuable semantic enrichment. It doesn't add much about the `serving`/`answered_by` output fields, but those are output, not parameters. A 4 is appropriate because the description genuinely enhances parameter understanding 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 a clear, specific statement of what the tool does: 'How a site is doing: where it is built from, whether the address is answering, and how the latest build ended.' It names the resource (site status) and the three distinct concerns it consolidates (project, deploys, live check). It also explicitly distinguishes itself from sibling tools by saying 'One call instead of three (project, deploys, live check of the address).' This is a specific verb+resource with clear differentiation from 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 provides explicit guidance on when to use this tool and how to interpret its results. It explains the `serving` field semantics, tells users to check a real route with `path` for API servers, explains redirect behavior, and gives explicit instructions for waiting on builds ('call again after that many seconds' or 'pass `wait_s`'). It also warns about client tool-call timeouts. While it doesn't name specific sibling alternatives to use instead, it clearly states what this tool consolidates and how to handle its edge cases, which is strong 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?

The annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds behavioral detail about error handling ('a clear error here') and indicates that the tool validates token configuration, which goes beyond 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 two sentences, front-loads the purpose, and every sentence contributes. 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?

The tool has no parameters, an output schema exists, and the description covers purpose, usage, and behavioral context. The combination of annotations and description fully equips an agent to invoke this simple 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 tool has zero parameters, so parameter semantics are trivial. The description appropriately omits parameter details. Baseline for zero-param tools is 4.

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 what the tool does: 'Who is connected to Layero and how many projects they have.' It specifies the resource (Layero) and the output (connection status and project count). This distinguishes it from sibling tools like my_projects or site_status, which have different scopes.

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 states when to use the tool: 'Call this first when you are unsure the token is configured.' It also provides a rationale ('a clear error here is cheaper than one halfway through a deploy'), giving clear context for usage. It does not name alternatives, but the guidance is explicit.

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