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

Annotations already disclose readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds genuinely new context: the host requires verification after creation, and that delete-host is irreversible and needs confirmation. It does not describe return values, but those are less critical here.

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 tight sentences, front-loaded with the action, then the protocol requirement, then sibling routing. Every sentence carries distinct information with no 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?

For a one-parameter mutation tool with full schema coverage and annotations covering the safety profile, the description covers trigger, format constraint, post-condition (verification), and alternatives. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter's description matches the schema text verbatim ('Site URL with protocol'). The description adds no syntax or format detail beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add a new site (host) to Yandex Webmaster') and immediately disambiguates from siblings by naming verify-host, start-verification, and delete-host. An agent can distinguish this from the many get-* siblings without opening a schema.

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

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

Provides explicit trigger ('Use when the user asks to add a new site') plus two negative routings: ownership checks go to verify-host/start-verification, and removal goes to delete-host. This is the full when/when-not/alternatives pattern.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the description's own contribution is the daily quota constraint (a rate limit), the returned task_id, and the follow-up workflow. It does not say what happens when the quota is exhausted or what errors surface, but it adds solid operational context 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?

Front-loaded with the action, then constraints, then alternatives, in four tight sentences. The second quota sentence mildly repeats the parenthetical 'check get-recrawl-quota', which is the only bit of redundancy.

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

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

With no output schema, the description correctly discloses the return value (task_id) and the handoff to get-recrawl-task, plus the quota gate. For a two-parameter enqueue tool this is 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 both url and host_id are already documented with format hints in the schema. The description adds no syntax or format detail beyond that, making the baseline 3 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?

States a specific verb (enqueue) and resource (URL for Yandex re-crawl), and explicitly differentiates itself from siblings get-recrawl-quota and get-recrawl-task. An agent can distinguish it from every other recrawl tool without opening a schema.

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

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

Gives an explicit when-to-use condition ('when the user asks Yandex to recrawl one URL and the daily quota still has room') and two explicit exclusions naming the correct alternative for each. Nothing is left to inference.

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

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

Annotations only declare the mutation/idempotency profile (readOnly=false, idempotent=false, destructive=false, openWorld=true); the description adds substantial context beyond that: the verified-host prerequisite and its 404 HOST_NOT_VERIFIED failure, and the 409 SITEMAP_ALREADY_ADDED duplicate case, including that the error payload carries the existing sitemap_id. This is exactly the behavioral detail annotations cannot express.

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

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

Purpose and return value are front-loaded, then prerequisites, error cases, and routing guidance in priority order. Six short sentences, each carrying distinct information, though the error-code detail could be marginally tighter.

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

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

For a two-parameter mutation with no output schema, the description covers the return value (sitemap_id), the host-verification prerequisite, both known failure modes, and sibling routing. Nothing an agent needs to call 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%, so both parameters (url, host_id) are already documented with format examples in the schema. The description adds no syntax or format detail beyond it, so the baseline 3 applies.

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

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

States a specific verb (Add) and resource (Sitemap file to Yandex Webmaster, user-added sitemaps) and immediately names the return value (sitemap_id). It also explicitly distinguishes itself from siblings get-user-sitemaps and delete-host, so an agent can route correctly without opening another schema.

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

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

Gives an explicit positive trigger ("Use when the user asks to register a sitemap URL on an already verified host") plus two explicit exclusions with the correct alternatives: listing goes to get-user-sitemaps, host deletion goes to delete-host. Nothing is left to inference.

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

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

Goes well beyond the destructiveHint annotation by enumerating precisely what is destroyed (verification, indexing/query history, sitemaps, important-URL settings), stating that re-adding starts from scratch, and disclosing the confirm-gate refusal behavior. This is exactly the consequence detail a mutation tool needs.

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

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

Front-loads the action, then the irreversibility, then the confirm gate, then routing guidance. Dense but every sentence carries distinct, non-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?

For a destructive, non-idempotent tool with no output schema, the description covers consequences, guardrails, and alternatives completely. An agent has everything needed to invoke it safely.

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

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

Schema coverage is 100%, so both params are already documented (baseline 3). The description adds value by emphasizing that confirm must be true for the tool to act at all, clarifying that a behavioral requirement exists beyond the schema's required[] list (which only lists host_id).

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

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

States a specific verb and resource ('Remove a host (site) from Yandex Webmaster') and explicitly distinguishes itself from siblings add-host (adding) and URL-drop operations. An agent can identify exactly what this tool does and what it does not.

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 ('user has explicitly asked to remove a site and accepts its history is lost') and two when-not cases with the correct alternative named ('call add-host', and don't use it to drop a single URL). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial semantics beyond them: records can be months old, source_last_access_date == discovery_date signals no re-verification, and such rows are flagged stale/'never re-checked' with a warning not to treat the count as a live failure. That is genuine, non-obvious behavioral context.

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

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

Front-loads the core purpose, then dense but relevant caveats and routing instructions; nearly every clause carries information. Slightly long and cluttered with quoted tokens, keeping it just below ideal.

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

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

For a read-only list tool with no output schema, the description supplies the key return-field semantics and staleness caveat an agent needs. The only omission is any mention of pagination behavior for limit/offset.

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 only 33% — host_id is documented but limit/offset are not. The description mentions source_last_access_date and discovery_date, but those are response fields, not parameters, so it adds no meaning for the three inputs. However, limit/offset are conventional pagination params with bounds in the schema and are self-explanatory, so the gap is minor rather than severe.

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

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

States a specific verb+resource ('List broken internal links') and immediately enumerates what a record contains (destination URL, source page, last-checked time). It is unambiguous against siblings like get-external-links and get-broken-internal-links-history, which it names directly.

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

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

Explicitly says when to use ('user asks which internal links look broken and whether Yandex has rechecked them') and names two exclusions with their correct alternatives: history over time goes to get-broken-internal-links-history, links from other sites go to get-external-links.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuine interpretation context beyond that: a row should not be treated as a live failure until source_last_access_date is read. It does not, however, disclose the return shape (time-series points) or date-range semantics, so it stops short of full transparency.

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

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

Three short sentences, front-loaded with the action, then the trigger, then the exclusion and caveat. No filler and no repetition of the tool name or title.

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?

There is no output schema, so the description is the only source of return-value information; it implies a count-over-time series but never states what a row contains beyond the borrowed source_last_access_date caveat. Selection and invocation are fully covered, making this near-complete for a simple read tool, with only the return shape and date-parameter semantics 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 only 33% (host_id is labeled 'Host ID', which is tautological), and date_from/date_to have no documented format, timezone, or default in either the schema or the description. With low coverage the description is expected to compensate, and it does not mention the parameters at all.

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 ('Get broken internal links count history') and immediately differentiates scope from the sibling get-broken-internal-links by contrasting 'count history' with 'source and destination URLs'. An agent can tell the two apart without opening either schema.

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

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

Explicit when-to-use ('when the user asks how the broken-internal-link count changed over time') and an explicit when-not-to-use with the named alternative ('Do not use it for the source and destination URLs; call get-broken-internal-links'). This is textbook 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?

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful behavioral detail: text lists problems in state PRESENT with code/severity/date, and the full response lives in structuredContent. It stops short of explaining what PRESENT means, other states, or pagination, keeping it at a strong 4.

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 front-loaded, then usage trigger, then the negative routing. No filler; every sentence earns its place.

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

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

For a single-parameter read tool, the description covers purpose, trigger, exclusions, and even compensates for the absent output schema by explaining that text lists PRESENT problems while the full payload is in structuredContent. 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 description coverage is 100% and there is only one parameter (host_id), which the schema already documents. The description adds no additional meaning about the parameter. Baseline 3 applies.

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

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

States a specific verb and resource ('Get site diagnostics') and immediately clarifies scope by contrasting with sibling tools. An agent can distinguish it from get-excluded-pages and get-search-events-samples without opening any schema.

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

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

Gives an explicit when-to-use trigger ('user asks what site problems Yandex currently reports, such as mobile or security issues') and an explicit when-not with named alternatives ('Do not use it for pages that dropped out of search; call get-excluded-pages or get-search-events-samples'). Routing is unambiguous.

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

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

Adds substantial context beyond annotations: data is built from REMOVED_FROM_SEARCH events, not a live index snapshot; deduplication is per URL with latest event winning and spans only one call; pages that returned are listed separately under returned_to_search; window bounds and max_requests cap behavior; retries not counted; and the need to pass returned_urls when continuing with offset. Annotations already cover read-only/idempotent/non-destructive, but the description carries crucial operational behavior.

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

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

Front-loaded with the core definition before diving into caveats, and most sentences earn their place by explaining non-obvious data semantics. It is long but justified for a tool with several tricky behaviors, though minor repetition (deduplication explained twice) and heavy capitalization keep it from being perfectly tight.

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 no output schema, the description still describes return shape sufficiently: url + excluded_url_status, bad_http_status, target_url, returned_to_search, and next_offset/exhausted for continuation. It covers all complexity around event-stream walking, pagination, and result interpretation, leaving no significant gaps.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including limit (excluded pages), max_requests (page fetch cap), offset, host_id, and returned_urls continuation semantics. The description largely reinforces these meanings rather than adding new parameter-level syntax or constraints beyond what the schema provides, so 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?

States a specific verb+resource: pages dropped from search inside a time window, with reasons. Explicitly distinguishes from sibling results by saying it is not the aggregate from get-summary and not a single mixed page of events, naming get-search-events-samples as the alternative.

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 (user asks which pages dropped out of search and why inside a scanned window) and when-not-to-use, naming get-summary for aggregate excluded_pages_count and get-search-events-samples for a single mixed page of events. No inference required.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact – that results are samples rather than an exhaustive list – but says nothing about pagination or result volume despite limit/offset existing in the schema.

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

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

Three short sentences, all load-bearing, with the core purpose front-loaded and the disambiguation clauses following. Zero filler.

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

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

For a simple read-only list tool with no output schema, the routing and scope information is complete enough to invoke it correctly. The remaining gap is pagination semantics for limit/offset, which neither the description nor the schema explains.

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 only 33%: host_id has a token 'Host ID' description and limit/offset have none. The description never mentions parameters, so it does nothing to compensate for the two undocumented pagination 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?

States a specific verb+resource ('Get external links pointing to the site') and immediately scopes it ('sample pages on other sites that link to this host'). It also names the two siblings it is not, so an agent can separate it from get-external-links-history and get-broken-internal-links without opening any schema.

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

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

Explicitly gives the when ('user wants sample pages on other sites that link to this host') and two when-nots with the correct alternative named for each. Nothing about routing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and purity profile is fully covered. The description adds the key behavioral nuance that this is a count-over-time (trend) tool rather than a listing tool, but says nothing about time-series return shape, default date window, or granularity.

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

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

Three short sentences, zero filler, with the core purpose front-loaded and the disambiguation clauses following. Every sentence earns its place.

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

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

For a 3-parameter tool with no output schema, the routing information is complete, but the two undocumented date parameters and the nature of the returned history (points, granularity, units) are left entirely unaddressed.

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 only 33% — host_id is documented but date_from and date_to are bare strings. The description never mentions the date range parameters, their format, whether they are inclusive, or what happens when omitted, so it fails to compensate for the coverage gap.

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

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

The description states a specific verb and resource ('Get external links count history') and immediately contrasts it with two sibling tools (get-external-links for the URLs, get-broken-internal-links-history for internal broken links). An agent can distinguish it from every neighbor without opening a schema.

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

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

It gives an explicit trigger ('when the user asks whether the number of external links rose or fell') plus two explicit exclusions naming the alternative tools for each. This is exactly the when/when-not/alternatives pattern.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds return-content context the annotations cannot supply (verification flag, data status), which matters because there is no output schema, though it does not describe error cases or how the verification flag is reported.

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

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

Three short sentences, front-loaded with the purpose, then routing rules. Every clause carries routing or scope information and there is no filler.

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

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

For a single-parameter read-only getter with no output schema, the description covers purpose, scope, alternatives and the gist of the return payload. It stops short of detailing the response fields or error behavior, which is a minor gap given the absence of an 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?

Only one parameter exists and schema description coverage is 100%, so the schema fully documents host_id including the URL-encoded format example. The description adds nothing about the identifier's form or encoding, so this is the baseline case where structured data does the work.

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

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

States a specific verb and resource ("Get details for a specific host") and narrows it further by naming the payload an agent should expect: the verification flag and data status. It explicitly separates itself from list-hosts, start-verification and verify-host, so an agent can choose correctly without opening any schema.

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

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

Gives positive usage (when the user wants the verification flag / data status of one host) and two explicit exclusions with named alternatives: use list-hosts to enumerate sites, use start-verification for the ownership check. This is exactly the when/when-not/alternative structure.

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, destructiveHint=false and openWorldHint=true, so the safety and idempotency profile is covered. The description adds only scoping semantics (one URL vs. a list), not behavioral detail such as pagination, retention window, or how the history is sampled. Adequate but no value 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?

Three short sentences, no filler, with the core purpose front-loaded before the two disambiguation clauses. Every sentence carries routing 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?

Purpose and routing are fully covered, and no output schema exists so return values need not be explained. However, with 4 parameters at 50% description coverage, the undocumented date_from/date_to range semantics leave the agent guessing about how to narrow or bound the history query.

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 only 50%: url and host_id are described, but date_from and date_to carry no description in the schema. The description never mentions the date-range narrowing capability at all, so it fails to compensate for the coverage gap on half the 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?

States a specific verb and resource ('Get history for a specific important URL') and immediately scopes it to a single URL. It explicitly names the two siblings it is not (get-important-urls, get-search-events-samples), so an agent can disambiguate without opening any schema.

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

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

Gives an explicit positive trigger ('when the user asks how one important URL changed over time') plus two named exclusions with the correct alternative tool for each. This is exactly the when/when-not/alternative structure that removes routing ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered structurally. The description adds routing context but no additional behavioral detail such as pagination behavior, result volume, or what 'configured important URLs' means operationally. Adequate but not additive.

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

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

Three sentences, zero filler, with the purpose front-loaded and the exclusion rules following immediately. Every sentence carries routing information an agent needs to pick between siblings.

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?

Sibling disambiguation is complete, but the description omits any pagination guidance despite limit/offset being the only non-trivial parameters, and there is no output schema to explain the return shape. For a list endpoint this leaves a real gap, though the routing burden is well handled.

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 only 33%: host_id is documented only as 'Host ID' and limit/offset carry no descriptions. The description says nothing about pagination, defaults, or how limit/offset interact, so it fails to compensate for the coverage gap on a listing tool where pagination semantics matter.

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 ('Get important URLs for a site'), with a scope qualifier ('configured for the host') that separates it from the many other URL-related siblings. An agent can identify the tool without opening the schema.

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

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

Gives an explicit positive trigger ('when the user wants the important URLs configured for the host') and two explicit negative triggers naming the correct alternatives (get-important-url-history for per-URL history, get-indexing-samples for indexed samples). This is a textbook routing instruction.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds usage context but says nothing about return shape, pagination, or granularity of the time series. With annotations carrying the behavioral burden, a 3 is appropriate.

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 tight sentences, purpose first, then the positive usage trigger, then the two exclusions. Every sentence earns its place and nothing is redundant.

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

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

For a history/read tool with no output schema and annotations covering safety, the description covers purpose and routing well. It falls short only on the date-parameter semantics, which an agent would need 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 only 33%: host_id has a (tautological) description while date_from and date_to are undocumented. The description says 'over time' but never specifies date formats, ranges, or how host_id scopes the result, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Get indexing history over time') and clarifies the measured quantity ('the number of indexed pages'). It explicitly names the two siblings it is not (get-indexing-samples, get-insearch-history), so an agent can disambiguate without opening any schema.

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

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

Provides explicit when-to-use ('how the number of indexed pages changed over time') plus two when-not-to-use clauses, each routed to a named alternative with the distinguishing condition. This is textbook sibling routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the scope that results are 'sample' URLs rather than exhaustive or historical, but says nothing about pagination behavior or ordering, which matters for a sampled list tool.

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

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

Three short sentences, zero waste, and the primary purpose is front-loaded ahead of the routing guidance. Every clause earns its place by steering tool selection.

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, no-output-schema tool the routing guidance is complete, but limit/offset paging behavior is undocumented in both schema and description, leaving a real gap for an agent that needs to page through samples.

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 only 33% – host_id is described, but limit and offset carry no schema description and the tool description never mentions them. With low coverage the description should compensate for pagination parameters, and it does not.

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

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

States a specific verb+resource ('Get sample indexed URLs') and immediately distinguishes itself from two named siblings with different scopes. An agent can tell it apart from get-indexing-history and get-search-events-samples without opening any schema.

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

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

Explicitly states when to use it ('user wants example URLs Yandex has indexed') and two when-not cases, each paired with the correct alternative tool to call instead. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety and idempotency are covered structurally. The description adds only the implicit notion of a time series ('over time'); it says nothing about granularity, aggregation, pagination, or whether a date range is required.

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

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

Three short sentences, purpose first, then positive usage, then the two exclusions. No filler and no repetition of structured data.

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?

There is no output schema, and the two date parameters are undocumented everywhere, so an agent knows when to call this tool but not how to bound the range or what shape the returned series takes. Purpose and routing are complete; operational detail is not.

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 only 33% — host_id is documented as 'Host ID' while date_from and date_to have no descriptions at all. The description's phrase 'over time' hints that dates matter but supplies no format, defaults, inclusive/exclusive bounds, or required-range semantics, so it fails to compensate for the schema gap.

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

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

States a specific verb and resource ('Get in-search history') and immediately disambiguates the jargon with a parenthetical gloss ('appearing in results'). It also explicitly distinguishes this tool from two similar-sounding siblings by name, so an agent can select it without opening 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?

Gives a concrete triggering condition ('when the user asks how many pages were present in search results over time') plus two explicit exclusions that each route to the correct alternative (get-insearch-samples for example URLs, get-indexing-history for the indexed-page series). This is a textbook when/when-not/alternative block.

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 destructiveHint=false, so the safety profile is covered structurally. The description confirms it returns a sample set of currently-indexed URLs but adds nothing about pagination or result freshness. Adequate but not rich.

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

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

Three short sentences, front-loaded with the purpose then the exclusion rules. Slight redundancy between 'Get sample URLs appearing in search' and 'example URLs that currently appear in search', but no filler.

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

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

For a read-only sampling tool with no output schema and four annotations, the description covers purpose and routing well. It is incomplete on the pagination parameters and on what a 'sample' means (how many, how selected), which are the remaining gaps an agent would face.

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 only 33% (limit and offset are undocumented; host_id is merely described as 'Host ID'). The description does not compensate — it says nothing about what limit/offset mean, valid ranges, or default paging behavior. With low coverage, the description should have filled this gap and does not.

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 ('Get sample URLs appearing in search') and immediately distinguishes itself from close siblings by naming the alternatives. An agent can tell this apart from get-search-events-samples and get-insearch-history without inspecting 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?

Gives explicit when-to-use ('user wants example URLs that currently appear in search') and two explicit when-NOT-to-use cases, each routed to a named sibling. Routing logic is fully spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the ranking semantic but nothing about pagination behavior, result limits (the schema mentions a default of 100), or date-range scoping effects. Adequate but not rich beyond structured fields.

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 tight sentences: purpose first, then the two exclusions. No filler, no repetition of schema detail, and the routing information is front-loaded.

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 7-parameter read tool with no output schema, the description covers purpose and routing well and annotations cover safety. Minor gap: it doesn't clarify result volume/pagination expectations or how date_from/date_to bound the aggregation, though the schema names them.

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 every parameter including order_by, device_type, and date ranges is already documented in the schema; the description's 'shows or clicks' merely restates the order_by enum. Baseline 3 applies when the schema does the heavy lifting.

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 (Get) and resource (popular search queries) scoped to a site, and immediately clarifies the two ranking dimensions (shows or clicks). It distinguishes itself from siblings by naming get-query-history and get-insearch-samples as the wrong tools for adjacent jobs.

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

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

Explicitly gives the use case ('top queries for a site by shows or clicks') plus two negative routing rules with the correct alternative tool named in each. This is the ideal form of when/when-not 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is handled. The description adds useful scope context (aggregate site-level time series rather than per-query detail), but it says nothing about date-range defaults, auth requirements, or result granularity/limits beyond the annotations.

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

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

Two sentences, zero filler, and the core capability plus the routing rule are front-loaded. Every clause earns its place.

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

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

There is no output schema, so the description's mention of shows, clicks, and average position does useful work in describing what comes back, and the sibling routing is complete. However, with only 25% parameter documentation and no notes on date handling or defaults, the definition is adequate but leaves meaningful gaps for a 4-parameter time-series 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 only 25%: host_id carries a trivial 'Host ID' label and date_from, date_to, and the device_type enum are undocumented. The description does not compensate for this gap — it explains no date format, no default range, and no meaning for the device_type enum values, so an agent must guess at three of four 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?

States a specific verb and resource ('Get search query totals history') and immediately clarifies the scope is site-wide aggregate metrics over time. It explicitly distinguishes itself from get-popular-queries, so an agent can separate the two without opening either schema.

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

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

Gives an explicit trigger ('when the user asks how shows, clicks, or average position moved over time for the site as a whole') and an explicit exclusion with a named alternative ('Do not use it for the ranking of individual queries; call get-popular-queries'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and side-effect profile is fully covered. The description adds useful context about what the queue represents (submissions from add-recrawl-url and their states), but says nothing about pagination behavior, ordering, or result size limits beyond what the schema states.

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

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

Three short sentences, with the purpose front-loaded and the routing rules following. The one inefficiency is mild redundancy between 'URLs submitted via add-recrawl-url with their state' and 'the list of URLs already sent for recrawl and their states', which restate the same fact.

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, fully schema-documented list tool with no output schema, the description covers purpose, contents, and sibling routing adequately. It could optionally note return ordering or that results are paginated, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so host_id, limit (default 10), and offset are all documented in the schema itself. The description only restates the host scoping ('for a host') and adds no syntax, format, or default details beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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 (List) and resource (recrawl queue for a host), and parenthetically defines the queue's contents as URLs submitted via add-recrawl-url with their state. It explicitly distinguishes itself from get-recrawl-task and add-recrawl-url, so an agent can route correctly without opening any schema.

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

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

Gives explicit positive usage ('Use when the user wants the list of URLs already sent for recrawl and their states') plus two exclusions with named alternatives: one known task id -> get-recrawl-task, enqueueing -> add-recrawl-url. When/when-not/alternatives are all covered.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive, open-world operation, so the safety profile is covered. The description adds only the daily-quota framing ('left today'), which is useful but modest. It says nothing about quota reset semantics, units, or what happens when the quota is exhausted, so it does not go much beyond the structured fields.

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

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

Three short sentences, zero filler, front-loaded with the action and followed by routing exclusions. Every sentence earns its place.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the definition provides enough to invoke correctly. The only minor gap is that the return value's shape (remaining count vs. a quota object) is only hinted at by 'how many recrawl requests are left today'.

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?

Single required parameter with 100% schema description coverage, so the schema already carries the parameter documentation. The description contributes no additional meaning about host_id (e.g. where to obtain it or whether it differs from a URL). Baseline 3 applies when the schema does the heavy lifting.

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 ('Get recrawl quota for a host') and immediately anchors it to a user intent ('how many recrawl requests are left today'). It also names the two nearest siblings it must not be confused with, so an agent can route without opening any schema.

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

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

Explicit when-to-use (user asks about remaining recrawl requests) plus two explicit when-not clauses with named alternatives (add-recrawl-url for sending a URL, get-recrawl-queue for queued tasks). This is the full when/when-not/alternative pattern.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds useful behavioral context the annotations do not: the dependency chain (task_id originates from add-recrawl-url) and the fact that this call does not consume quota. It stops short of describing the possible state values, which would be the remaining 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 short sentences, front-loaded with the core action before the routing rules. The third exclusion sentence is slightly tangential to the primary purpose but still earns its place as disambiguation against the quota-spending tool.

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

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

For a two-parameter read with full annotations and no output schema, the description covers origin, scope and exclusions adequately. The only missing piece is what the returned state values look like, which is a minor omission given the annotations already establish this as a safe read.

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 host_id and task_id are already documented, giving a baseline of 3. The description adds meaningful semantics on top by telling the agent where task_id comes from, which is the critical piece for constructing a valid call.

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 ('Get state of a single recrawl task by task_id') and immediately scopes it against siblings by naming get-recrawl-queue and add-recrawl-url. An agent can distinguish it from every other get-* tool without opening a schema.

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

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

Gives an explicit when-to-use condition ('when the user has a task id from add-recrawl-url') plus two explicit when-not-to-use cases with the correct alternative named for each. Nothing is left to inference about routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing that this tool returns COUNTS (aggregate) rather than the underlying URLs or exclusion reasons, which is the key behavioral distinction from its siblings. It stops short of describing time granularity, formatting, or pagination.

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 tightly written sentences, front-loaded with the verb+resource, followed by usage and then the exclusion. Every sentence earns its place with zero redundancy.

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

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

With no output schema, the description usefully conveys the return semantics (appeared/removed counts over time) and routes alternatives, so an agent can call it correctly in principle. The remaining gap is the undocumented date_from/date_to format and semantics, which is the only thing an agent lacks for a correct invocation.

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

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

Schema coverage is only 33% (host_id documented, date_from/date_to undocumented) and the description does not compensate: it never explains the date range parameters, their format, or their behavior. 'Over time' only weakly implies that date parameters apply, adding almost no semantic meaning beyond what the bare 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?

States a specific verb and resource ('Get search URL events history') and immediately qualifies the scope with '(appeared/removed)' and 'the count of appeared and removed search URLs over time.' An agent can distinguish this aggregate-history tool from get-search-events-samples (which returns the URLs themselves) without opening either schema.

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

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

Provides explicit when-to-use ('Use when the user wants the count of appeared and removed search URLs over time') plus an explicit exclusion and routing ('Do not use it for the URLs themselves or the exclusion reason; call get-search-events-samples or get-excluded-pages'). Names the alternative siblings and the condition that selects them.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds non-obvious behavior: there is no server-side event filter, so event_type is applied client-side and offset/limit paginate the unfiltered stream. It also notes this is the only v4 endpoint exposing per-URL exclusion reasons — valuable context 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?

Information-dense and front-loaded with the purpose and the key caveat, then the routing rules. Every sentence carries weight, though the two negative routing sentences plus the API-caveat sentence make it slightly longer than strictly necessary.

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?

Covers purpose, the unique return value, a pagination/filtering caveat, and both alternative tools. With no output schema, the description still tells the agent exactly what it gets back (sample URLs plus exclusion reasons). Nothing needed to call it correctly is missing.

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

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

Schema coverage is 75% and the schema already documents event_type as a client-side filter, but the description goes further by explaining how that filter interacts with pagination (the unfiltered stream is paginated, then filtered). It adds meaning beyond the schema for the parameters that matter most; host_id/limit/offset are self-evident.

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 ('Get sample URLs for search events') and immediately names the distinguishing payload ('excluded_url_status'). It explicitly separates itself from get-summary, get-excluded-pages, and get-search-events-history, so an agent can route without opening any schema.

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

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

Gives an explicit when-to-use clause plus two explicit when-not-to-use clauses, each naming the correct alternative tool (get-excluded-pages for dropped-page walks, get-search-events-history for counts). This is textbook 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds no further behavioral context such as permission requirements, error behavior, or what 'details' actually contains, so it does not exceed the annotation baseline.

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

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

Three short sentences, zero waste: purpose first, then positive usage condition, then two negative routing rules. Every clause earns its place and routing information is front-loaded.

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

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

With no output schema and a tiny two-parameter input, the description supplies everything needed for correct selection and routing. It is slightly thin on the host_id requirement and on what the returned details comprise, but no critical calling information is missing.

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

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

Schema coverage is 100%, including the URL-encoded note on sitemap_id, so the schema carries parameter semantics. The description only alludes to sitemap_id ('already has a sitemap id') and never mentions the required host_id, adding no format or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Get details for a specific sitemap') and explicitly scopes it to the case where the user already has a sitemap id. It distinguishes itself from sibling list/upload tools by name, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use ('user already has a sitemap id') plus two when-not-to-use clauses with named alternatives: get-sitemaps/get-user-sitemaps for listing and add-sitemap for uploading. Nothing about selection is left to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral scope beyond annotations by clarifying that results include 'every sitemap Yandex knows ... including ones it discovered,' which is useful context for interpreting the data. It does not mention pagination, rate limits, or return format, so it is not fully complete.

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

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

Three sentences, zero waste. The core purpose is front-loaded, followed by positive usage guidance and then precise exclusions with named alternatives.

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

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

For a read-only list tool with rich annotations and no output schema, the description covers purpose, usage, and sibling routing well. The main gap is the undocumented limit parameter, but an agent can still invoke the tool correctly with the required host_id.

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 50%: host_id has only a minimal 'Host ID' description, and limit is undocumented. The description implies the host parameter but adds no meaning for limit (e.g., maximum 100, behavior), leaving a required parameter inadequately explained.

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: 'List all sitemaps for a host.' It further distinguishes itself from sibling tools get-user-sitemaps and add-sitemap by explicitly naming them and describing scope including discovered sitemaps.

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

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

It gives explicit when-to-use criteria ('Use when the user wants every sitemap Yandex knows ... including ones it discovered') and explicit when-not-to-use alternatives ('Do not use it for only the files the user uploaded; call get-user-sitemaps. Do not use it to add a file; call add-sitemap.').

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the time-series/date-range nature of the operation, which is genuinely useful context, but says nothing about pagination, result granularity, or limits.

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

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

Three tightly-scoped sentences with zero filler; the core purpose is front-loaded and the routing exclusions follow immediately.

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, three-parameter history tool with no output schema, the description covers purpose, routing, and date scoping, and annotations carry the safety profile. Only the return shape and pagination behavior are unaddressed, which is a minor gap.

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

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

Schema description coverage is 100% and all three parameters (host_id, date_from, date_to) are documented in the schema, so the baseline of 3 applies. The description's 'over a date range' hints at the date parameters but adds no format or range 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?

States a specific verb and resource ('Get SQI (Site Quality Index) history over time') and even expands the acronym. It explicitly distinguishes itself from the two nearest siblings, get-summary and get-indexing-history, so an agent can route without opening any schema.

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

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

Explicitly states when to use it ('when the user asks how the Site Quality Index changed over a date range') plus two when-not cases with named alternatives. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by enumerating the payload (SQI, page count, problem totals), which matters because there is no output schema; it does not mention freshness/latency or required permissions, keeping it short of a 5.

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

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

Three tight sentences: purpose first, then trigger, then two disambiguation rules. Every sentence earns its place and the most important routing information is front-loaded.

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 tool with no output schema, the description supplies both the content of the response and the routing rules against two plausible near-siblings. An agent has everything needed to select and call it correctly.

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

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

There is a single parameter (host_id) at 100% schema description coverage, so the schema does the documentation work. The description adds no scoping or format detail about host_id, which is the expected baseline when coverage is this high.

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 (Get) and resource (site summary) and enumerates the returned content: SQI, page count, problems. It also distinguishes itself from get-excluded-pages and get-sqi-history by name, so an agent can route without opening any schema.

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

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

Explicitly gives the trigger condition ('when the user wants the current SQI, page counts, and problem totals for a host') and two named exclusions with the correct alternative tool for each. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the behavioral burden is light. The description adds that the call yields the account id used by downstream non-host-scoped tools, which is useful operational context, though it doesn't detail the shape of the returned user object.

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

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

Three short sentences, front-loaded with purpose followed by use/avoid conditions. Every sentence carries routing or scoping information; no filler.

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

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

With no parameters, no output schema, and no nesting, the description supplies everything an agent needs: what it returns (user info and user_id), when it is the right call, and which sibling to use instead for host listing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4 with no parameter semantics to explain. The description does not need to bridge any schema gap 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?

States a specific verb and resource ('Get current Webmaster user info and user_id'), and explicitly distinguishes its scope from the sibling list-hosts. An agent can identify this as the account-identity lookup without opening a schema.

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

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

Gives both when to use ('when the user needs the Webmaster account id before a call that is not already scoped to a host') and when not to use ('Do not use it to list sites'), naming the alternative tool list-hosts. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds manual-vs-discovered semantics, which is useful context, but says nothing about pagination, ordering, or how the limit shapes the result for what is potentially a large list.

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

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

Three short sentences, front-loaded with the purpose, then the trigger, then the exclusions. Every sentence earns its place and none restates the tool name.

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

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

For a read-only list tool with no output schema and annotations covering the safety profile, the routing information is essentially complete. The only real gap is that limit's meaning and default behavior are undocumented anywhere.

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 only 50%: host_id is documented merely as 'Host ID' and limit carries only min/max bounds with no explanation of what is being limited. The description mentions no parameters at all, so it does not compensate for the coverage gap on limit.

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 ('List user-added sitemaps') and immediately scopes it against the two nearest siblings, get-sitemaps and add-sitemap. An agent can distinguish this tool from every other get-* sibling by the 'user-added' qualifier alone.

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

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

Gives an explicit positive trigger ('when the user asks which sitemap files were added by hand') plus two explicit exclusions that name the correct alternative tool for each case. Nothing about routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: it tells the agent the host_id format and that the value should be taken from this tool rather than assembled by hand, which is a behavioral/usage nuance. It stops short of describing pagination or the full return shape, so not a 5.

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

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

Front-loads the action and the key output (host_id), then the usage conditions, then the exclusion. Every sentence carries distinct information (what it returns, the identifier format, when to use, when not to use) 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?

No output schema exists, so the description must carry the return-value burden; it names the returned entities and the crucial host_id format, which is largely sufficient. It does not mention pagination or the full field set of each host, leaving a minor gap for a list tool.

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

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

Zero parameters, so the baseline is 4. The description still adds semantic value by explaining that the returned host_id follows the format "https:example.com:443", which is the critical value an agent must extract and reuse.

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 ('List all hosts (sites) in Webmaster') and immediately clarifies the key artifact returned: the host_id with its exact format ("https:example.com:443"). An agent can distinguish this from sibling tools like get-host or add-host without opening any schema.

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

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

Explicitly names both trigger conditions ('which sites are in Webmaster' or 'needs a host_id for any later call') and the exclusion ('Do not use it for one site SQI or problems'), routing to get-summary or get-diagnostics instead. This is the full when/when-not/alternative triad.

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

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

Goes well beyond the annotations, which only say it is non-read-only, non-destructive, non-idempotent and open-world. The description discloses that the check is asynchronous, that the call returns the current state (usually IN_PROGRESS), how to reach a terminal outcome by polling verify-host, where the failure reason lives (fail_info), and the prerequisite that the verification artifact must be placed first.

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

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

Front-loaded with the action, then prerequisites, then async semantics, then exclusions — a sensible order. Slightly repetitive in the two parallel 'Do not use it to...' sentences, but every sentence carries a distinct fact.

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

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

With no output schema, the description carries the return-value burden and does so: it names the returned state, the terminal states, and the failure field. Combined with the prerequisite ordering and the cross-tool polling loop, an agent has everything needed to call and follow up correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning by spelling out the payload each enum value expects — file `yandex_<uin>.html` for HTML_FILE, the `<meta name="yandex-verification">` tag for META_TAG, a TXT record for DNS — and by tying verification_type to `applicable_verifiers` from verify-host. No extra guidance on host_id formatting beyond the schema.

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

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

States a specific verb and resource ('Start the Yandex Webmaster ownership check for a host') and immediately scopes it against siblings by naming verify-host and add-host as the tools for adjacent tasks. An agent can distinguish this from verify-host, add-host, and delete-host without opening any schema.

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

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

Explicit when-to-use ('when the verification file, meta tag, or DNS record is already in place and the user wants the ownership check started') plus two explicit when-not clauses with the correct alternative for each. Nothing about routing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it discloses what the call returns (verification state, the UIN, and which verification methods are available), which matters since there is no output schema.

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

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

Three sentences, each earning its place, with the core purpose front-loaded and the exclusions following. No filler or redundancy.

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

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

For a single-parameter, read-only lookup with no output schema, the description covers purpose, trigger conditions, routing to alternatives, and what data is returned. 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 single parameter (host_id) is fully documented with format guidance in the schema itself. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Get verification status and available verification methods for a host.' It further differentiates itself from the sibling tools add-host and start-verification, so an agent can distinguish it without opening a schema.

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

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

Gives explicit trigger context ('Use after add-host', 'Use when the user wants the current verification state, the UIN, or which methods are available') and explicit exclusions routing to alternatives ('Do not use it to start the check; call start-verification. Do not use it to add the site; call add-host'). When/when-not/alternatives are all present.

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