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

Adds significant behavioral details beyond annotations: the return value format, the required verification step, and specific error codes (409 for already added, 403 for limit exceeded). Annotations already indicate a write operation and non-idempotency, but the description enriches this with concrete side effects and error scenarios.

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 composed sentences cover the action, return value, next steps, and errors without redundancy. The structure is front-loaded and 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 one-parameter tool with no output schema, the description is complete: it states the purpose, return shape, required follow-up, and error conditions. Nothing critical is missing.

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

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

The input schema fully documents host_url with type, format, and an example, giving 100% coverage. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the action: 'Добавляет сайт в список пользователя' (adds a site to the user's list), with a specific verb and resource. It distinguishes itself from sibling tools like list_sites and get_site_summary by focusing on the add operation.

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 clear context: this tool adds a site, and the description mentions the required follow-up verification via get_verification_status → start_verification. However, it does not explicitly contrast with alternatives or state when not to use it, so it stops short of a 5.

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

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

Description adds significant behavioral details beyond annotations: returns 201 with sitemap_id, raises 409 SITEMAP_ALREADY_ADDED for duplicates, and requires confirmed site rights. This enriches the readOnly/idempotent hints and provides concrete error semantics.

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, front-loaded with the core action, then return format, error condition, and prerequisite. No filler or redundancy; 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 simple 2-parameter mutation tool, the description covers the main operational aspects: action, response, error, and permission requirement. However, it lacks an explicit note on when to use it vs. list_sitemaps or how host_id is used, though the schema fills that gap. Overall, sufficiently complete for invocation.

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

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

Input schema has 100% coverage with descriptions for both parameters. The tool description itself does not add parameter-specific details, so the baseline of 3 applies because the schema already fully documents url and host_id semantics.

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

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

The description clearly states the action ('Добавляет sitemap-файл вручную') and the resource (sitemap file). It distinguishes itself from siblings like list_sitemaps (which lists) and add_site (which adds a site), even referencing the Webmaster interface section as an analogy.

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

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

The description implies usage context (manual addition, requires confirmed rights) but does not explicitly state when to use this tool versus alternatives. No reference to sibling tools like list_sitemaps or automatic sitemap detection is given, so guidance is only implied.

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

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

The description adds valuable behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). It explicitly states that the tool 'does not send anything to the network' and 'does not show the token itself', which is crucial for an auth-related tool. It also explains what it does show, giving full transparency about its effects.

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

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

The description is compact and front-loaded: it states the primary purpose first, adds key specifics (what it shows, what it doesn't show), and ends with a clear usage trigger. Every sentence adds value, no redundancy. Excellent structure for a zero-parameter diagnostic 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?

Given the tool's simplicity (no parameters, no output schema), the description fully covers what the user would learn from calling it: connection status, token source, expiry, file location, and safety caveats. There is no ambiguity about what the tool returns or its side effects. Complete for its intended diagnostic purpose.

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

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

With zero parameters, the baseline is 4. The description doesn't need to explain parameters, and it doesn't attempt to. It focuses on what the tool reports, which is appropriate. No parameter-related guidance needed.

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

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

The description clearly states the action: 'shows whether Yandex Webmaster is connected' and specifies the exact details it covers (token presence, source, expiry, file location). It distinguishes itself from sibling tools (start_login, finish_login, logout) by focusing on status rather than auth actions, and the specific details make it unambiguous.

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

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

The description explicitly says to call this when Webmaster tools report that the connection is not configured ('Вызовите это, если инструменты Вебмастера отвечают, что подключение не настроено'). This provides clear usage context, though it doesn't explicitly mention alternative tools or when not to use it. That's sufficient for a diagnostic tool.

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

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

The description discloses side effects (saving a file with 0600 permissions) and code validity (single-use, 10 minutes), adding context beyond annotations. However, it contradicts the idempotentHint: true annotation because a single-use code makes repeated calls with the same argument non-idempotent, conflicting with the annotation's implication of safe repetition.

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

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

The description is three concise sentences, front-loaded with the step context ('Второй шаг подключения'), and contains no redundancy. Every sentence adds value, covering purpose, side effects, and failure handling.

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

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

Given the simple tool with one parameter and no output schema, the description covers the essential flow, side effects (file save and verification), and failure handling. It could more explicitly mention the return value or how success/failure is signaled, but overall it provides sufficient context for correct usage.

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

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

The schema already describes the code parameter, but the description adds critical meaning: it must come from start_login, is one-time, and expires in 10 minutes. This extra context guides the agent on valid input beyond the schema's basic description.

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

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

The description explicitly states the tool's function: it exchanges a confirmation code from start_login for an access token, saves it with 0600 permissions, and verifies it with a live request. This clearly distinguishes it from sibling tools like start_login (first step) and logout (opposite).

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

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

It provides explicit usage context: it is the second step after start_login, and if the code is not accepted, it instructs to call start_login again for a fresh code. It also notes that after success, other tools work immediately without restart, giving clear when-to-use guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds practical behavioral details: the count field may arrive as a string despite being int64, the structure of the links array, and the permission prerequisite. These are meaningful nuances not captured by annotations.

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

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

The description is extremely concise—two sentences encapsulate purpose, return structure, pagination, and permissions. It is front-loaded with the primary purpose and every sentence provides new, valuable 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 read-only, idempotent tool with no output schema, the description fully compensates by detailing the return structure (count and links with fields), pagination behavior, and permissions. No critical information is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter guidance beyond reiterating offset/limit pagination, which is already evident from the schema. It does not introduce any new parameter semantics.

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

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

The description clearly states the tool 'returns examples of external links to the site' — a specific verb (returns) on a well-defined resource (external links) with scope (to the site). It distinguishes from all sibling tools by naming the exact resource, and the title reinforces this.

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

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

The description provides clear usage context: it mentions pagination via offset/limit and the requirement of confirmed rights to the site. While it doesn't explicitly compare with alternatives or say when not to use, this is sufficient for a tool with no direct sibling overlap.

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 known. The description adds valuable behavioral detail: it explains the response structure (indicators with arrays of {date, value} by status key), the meaning of OTHER, and the requirement for confirmed rights. No contradiction with annotations.

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

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

Every sentence in this description earns its place: output structure, status key semantics, default behavior, and permissions. It is front-loaded with the main verb and object, and the length is proportionate to the tool's complexity. 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?

There is no output schema, so the description fully compensates by detailing the return object shape (indicators with arrays of {date, value} per HTTP status category). Combined with the default period and authorization requirement, the description is complete enough for an agent to invoke the tool correctly without additional documentation.

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 descriptions cover all three parameters (100% coverage), so the baseline is 3. The description adds extra meaning by noting the default current-day period and that date_from/date_to define the custom period, which is not in the schema. It does not repeat parameter formats, but it enriches the temporal semantics.

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

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

The description opens with a specific verb and object ('Возвращает историю обхода сайта роботом') and immediately clarifies the resource (crawl history by HTTP status codes). It distinguishes itself from sibling history tools like get_search_queries_history by focusing on HTTP status code aggregates, making the purpose unmistakable.

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

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

The description provides clear usage context: it states the default time range (current day), how to set a custom period via date_from/date_to, and the prerequisite of confirmed site rights. It does not explicitly compare to alternative tools or state when not to use it, but the context is sufficient for most agents.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses important behavioral details: requires confirmed permissions ('Требует подтверждённых прав'), specific error 404 HOST_NOT_INDEXED, top size cap (3000) and pagination limits. These are not visible in structured data and add significant 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 dense sentences, each covering meaningful info: return format, limits/pagination, defaults, and error/auth. No filler or redundancy; front-loaded with the main purpose.

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

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

For a tool with 8 parameters and no output schema, the description covers the response structure, pagination, default period, required permissions, and a specific error. This is highly complete, especially since the schema already documents all parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying pagination semantics ('листайте offset/limit') and explaining the 3000-query top cap, which helps understand the offset/limit parameters. This goes slightly beyond what the schema provides.

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

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

The description clearly states it returns the top search queries for a site over a period, with a specific verb ('Возвращает') and resource ('ТОП поисковых запросов сайта'). It also details the response structure (queries array with indicators), which fully clarifies the tool's function.

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

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

The description gives context on default period and pagination ('По умолчанию период — последняя неделя', 'выдача — до 500 за раз'), but does not explicitly mention when to use this tool instead of alternatives like get_search_queries_history. Implied usage is clear, but no exclusions or alternative references are provided.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds the response format (indicators object with date/value arrays), default period (last week), and permission requirement, providing useful behavioral context beyond annotations without contradiction.

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

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

The description is compact and front-loaded: the first sentence states the purpose and output shape, the second gives a use case, and the third covers defaults and prerequisites. Every sentence earns its place with no 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 compensates by explaining the response structure, default period, and required permissions. It does not explicitly specify default behavior for query_indicators when omitted, but overall it gives an agent sufficient context to invoke the tool correctly.

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

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

Schema description coverage is 100%, with each parameter already well documented (e.g., date_from, query_indicators enums, device_type_indicator). The description repeats the default period but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns the history of aggregate indicators for ALL site search queries, with a specific structure (indicators object with key-value arrays). This distinguishes it from siblings like get_popular_queries (which returns individual queries) and get_indexing_history (indexing, not queries).

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

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

The description provides a clear use case: 'Подходит для динамики видимости сайта' (suitable for site visibility dynamics) and states a prerequisite (verified site rights). It does not explicitly name alternative tools or exclusions, but the context is enough for an agent to select it for date-based aggregate trends.

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 read-only, non-destructive, and idempotent behavior. The description adds the response structure and the permission requirement, going beyond the annotations without contradicting them.

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

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

The description is two sentences long, front-loaded with the primary action and return type. Every sentence adds value: the first explains the output structure, the second clarifies the current-state semantics and permission requirement.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It documents the return format, the meaning of 'right now', and the necessary permission, which covers all needed context without excess.

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%, as the only parameter host_id is fully explained in the schema including how to obtain it from list_sites. The tool description itself doesn't add any parameter-specific semantics, so the baseline of 3 applies.

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

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

The description opens with the verb 'Возвращает' (returns) and clearly specifies the resource: site diagnostics. It details the problems object structure with severity and state, making it distinct from sibling tools like get_site_summary or list_sites.

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

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

The description provides concrete usage context: it shows what Webmaster considers a problem at the current moment. It mentions the prerequisite of verified rights, but doesn't explicitly name alternatives or when-not-to-use conditions.

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

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

Annotations already declare the tool read-only and idempotent. The description adds the important behavioral constraint that confirmed site rights are required, and it clarifies the structure of the response (including problem categories). This adds value beyond the annotations without contradiction.

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

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

The description is two sentences: the first lists the return fields concisely, the second states the permission requirement. It is front-loaded with the primary action and contains no superfluous content.

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

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

Although there is no output schema, the description fully enumerates the returned fields and their meanings, including site_problems categories. The permission prerequisite is noted, making the tool's usage context complete for the agent.

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

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

The input schema fully covers the single optional parameter host_id with description and default behavior. The tool description adds no additional parameter semantics beyond reiterating the requirement for rights, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool 'returns site summary statistics' and enumerates specific output fields (sqi, searchable_pages_count, site_problems). This specific verb+resource combination distinguishes it from sibling tools like get_site_diagnostics.

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

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

The description implies usage for retrieving site summaries but does not explicitly state when to choose it over alternatives such as get_site_diagnostics. It does mention a prerequisite (confirmed rights), providing some contextual guidance, but lacks exclusions or alternative tool references.

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, openWorld, and non-destructive. The description adds valuable behavioral context: the returned ID belongs to the OAuth token owner and the server automatically injects it into other calls, explaining the tool's practical role. No contradictions with annotations.

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

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

The description is two sentences long and front-loaded with the core function. It then explains the auto-substitution behavior and specific use cases without any redundant or ambiguous content.

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

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

For a zero-parameter diagnostic tool, the description is complete: it provides the return format, explains the OAuth token ownership, clarifies when to use it, and mentions related raw_request paths. No important context is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters; it sufficiently explains the return value and purpose, which is all that is needed for a parameterless tool.

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

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

The description clearly states the tool returns the user_id (owner of the OAuth token) with an example response format. It distinguishes this tool from siblings by explicitly noting that the server auto-substitutes user_id, so this tool is usually unnecessary for normal operations.

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

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

The description provides explicit when-to-use guidance: for diagnostics (e.g., setting YANDEX_USER_ID) or raw_request paths. It also states when not to use it, because the server automatically injects user_id into other calls, making this a rarely needed diagnostic tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond the annotations by clarifying what data is returned (state options, timing, failure info) and how verification_uin fits into the process. No contradictions.

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

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

The description is a single dense sentence that lists all relevant return fields. It is comprehensive but slightly long; however, every element adds value and the main purpose is front-loaded. Could be improved with bullet points, but it's appropriately concise for the information conveyed.

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

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

Given the simple tool (1 optional parameter) and no output schema, the description adequately covers the return values and state semantics. It also ties to the broader verification workflow (UIN placement before start_verification). The only minor gap is lack of explicit note about error responses beyond fail_info, but that is covered by the listed fields.

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% for the only parameter (host_id has a description explaining its format and the environment variable fallback). The tool description does not add anything about parameters, but it doesn't need to because the schema is already informative. Baseline of 3 applies.

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

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

The description clearly states the tool returns the site rights verification status, listing exact fields (verification_state with enum values, verification_type, verification_uin, etc.). This specific resource (verification status) is distinct from sibling tools like get_site_summary or get_user_id. The reference to start_verification also links it to the verification workflow.

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

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

The description implies when to use this tool: to check verification status and to obtain the UIN code to place on the site before running start_verification. It provides clear contextual guidance without explicit exclusions or alternatives, but the workflow hint (placing UIN before start_verification) is useful.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful context: the data originates from a user-configured list and confirmed rights are required. No contradiction with annotations.

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

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

The description is concise yet information-dense, front-loading the purpose and efficiently describing the return structure and prerequisites with no filler words.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the return format, configuration source, and permission requirements. The agent has enough to decide when and how to invoke it.

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

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

Schema description coverage is 100%; the single optional host_id parameter is fully described in the schema, so the description need not add parameter details. A baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns tracked important pages ('Возвращает отслеживаемые важные страницы сайта'), specifying the resource and action. It is distinct from sibling list tools like list_sites and list_sitemaps, and the detailed return structure removes any ambiguity.

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

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

The description implies usage when you need the user-configured important pages and mentions a prerequisite (confirmed site rights), but it does not explicitly compare with alternatives or provide when-not-to-use guidance. The context that the list is configured in the Webmaster interface is helpful though implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond annotations: it describes the return format, cursor pagination, tree traversal, and the requirement for confirmed site rights, which enriches the agent's understanding.

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

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

The description is two sentences, front-loaded with the main purpose, then efficient details on pagination and permissions. Every sentence contributes meaning, with no redundancy or filler.

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

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

Despite having no output schema, the description fully covers the return structure and key behaviors (pagination, tree traversal, permission requirement). For a read-only list operation with optional params, this is highly complete and leaves few ambiguities.

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% for all four parameters, so the baseline is 3. The description adds value by explaining how 'from' is used for cursor pagination and how 'parent_id' traverses the index tree, going slightly beyond the schema's field-level descriptions.

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

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

The description clearly states it returns the site's sitemap files known to the robot, with a specific verb and resource. It provides the exact structure of the returned array and implicitly distinguishes itself from sibling tools like add_sitemap and list_sites.

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

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

The description gives clear context for when to use this tool—when you need to list a site's sitemaps—and explains how to paginate and traverse index sitemap trees. It does not explicitly name alternatives, but the context is sufficient and no exclusions are needed.

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

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

Annotations already declare read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds beyond this by detailing the return structure (array of hosts, including host_id format, verified, main_mirror) and the significance of host_id, which is valuable 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?

The description is only two sentences, front-loaded with the core purpose, and includes all necessary details (return fields and usage guidance) without any redundancy. It is a model of concise, well-structured documentation.

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 zero-parameter list endpoint with no output schema, the description is quite complete: it mentions the response format (array of hosts), lists all key fields, and gives a concrete example of host_id. It doesn't discuss pagination or empty-list behavior, but that's a minor gap given the tool's simplicity.

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

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

The tool has 0 parameters and an empty schema, so the baseline for parameter semantics is 4. The description doesn't need to explain parameters; it focuses on output, which is appropriate.

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

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

The description clearly states the verb ('returns a list of user's sites') and scope, and distinguishes it from sibling tools by positioning it as the starting point for Webmaster API work ('with this tool you should start any work'). It also enumerates key fields, so purpose is unambiguous.

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

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

The description explicitly says to start any Webmaster work with this tool and that the returned host_id is needed by all other tools, providing a clear when-to-use cue. However, it doesn't mention when not to use or name alternatives (e.g., if you already have host_id), so it falls short of a 5.

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

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

The description adds meaningful behavioral detail beyond the destructiveHint=true annotation: it specifies the disk token deletion, explicitly says the env token is preserved, and notes that Yandex-side access remains active until revoked. No contradiction with annotations.

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

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

Three short sentences deliver complete information without redundancy: what is deleted, what is not deleted, and the external side effect. The most important action 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 no-parameter logout tool with destructive annotations, the description fully covers the action, boundary conditions, and external persistence. No output schema is needed for this operation.

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

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

The tool has zero parameters and schema coverage is 100%, so the description is not required to explain parameter meaning. It correctly focuses on behavior rather than inputs.

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

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

The description opens with a specific verb and resource: 'Удаляет сохранённый токен Вебмастера с диска' (deletes the saved Webmaster token from disk). This clearly distinguishes logout from sibling auth tools like auth_status, start_login, and finish_login.

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-not guidance: the YANDEX_OAUTH_TOKEN environment variable is not touched and requires manual removal. It also directs users to Yandex ID to revoke the still-active access, providing an alternative for full logout.

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 warn about destructive operations and non-read-only behavior. The description adds valuable specifics: DELETE is irreversible, body is only for POST, and {user-id} is auto-substituted. It does not cover response format or error handling, but for a raw API proxy this is acceptable.

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

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

The description is four sentences, starting with the core purpose, then path construction, then body/DELETE warnings. Every sentence adds value; the first sentence is dense but informative. No fluff.

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

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

For an open-ended raw request tool with 3 parameters and no output schema, the description covers path syntax, query parameters, body constraints, and destructive behavior. Minor gap: it only explicitly mentions {user-id} substitution, leaving other placeholders like {host-id} implicit. Otherwise it is adequate.

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

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

Schema description coverage is 100%, so the schema already explains path, body, and method. The description adds a query-parameter-in-path tip and an example, but most parameter semantics repeat what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Прямой вызов любого пути Yandex Webmaster API v4' (Direct call to any Yandex Webmaster API v4 path) and specifies it is for endpoints without a dedicated tool, listing concrete examples like sitemap info, recrawl quota, and site deletion. This distinguishes it from sibling tools that handle specific endpoints.

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 'для эндпоинтов без отдельного инструмента' (for endpoints without a separate tool), setting a clear use condition. It also provides guidance on path formatting, placeholder substitution, query parameters, body usage, and DELETE behavior, giving the agent sufficient context to decide when to use this raw fallback instead of a domain-specific sibling.

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

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

The description discloses key behavioral details beyond annotations: it returns a 202 status with task_id and quota_remainder, explains the daily quota, and lists specific error codes (400, 409, 429). This adds significant context about rate limits and duplicate handling, which annotations only hint at.

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

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

The description is a single paragraph of 4 sentences, front-loaded with the main action. It is informative without being verbose, though it could be slightly more structured (e.g., bullet points for errors).

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

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

The description is comprehensive for a tool with no output schema: it explains the return object, status code, quota behavior, and all possible errors. It also references the host_id parameter from the schema, making the tool easy to use correctly.

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

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

The input schema already provides full coverage of the two parameters (url and host_id) with descriptions. The tool description adds minor context (e.g., URL must belong to the site via the 400 error), but does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's function: it sends a site page to the queue for recrawl by the robot. It uses a specific verb and resource, distinguishing it from sibling tools like list_sites or add_sitemap.

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

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

The description implies when to use the tool (when a page needs recrawling) but provides no explicit comparison to alternatives or when-not-to-use guidance. The mention of quota and error conditions gives context, but no direct usage exclusions.

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

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

Beyond the read-only/idempotent annotations, the description discloses that no config edit or restart is needed, the returned code expires in 10 minutes, and the code can only be exchanged by this server. This adds meaningful security and lifecycle 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?

Each sentence earns its place: primary purpose, return value, user interaction steps, next-step handoff, and security/expiry details. It is front-loaded and compact for the amount of operational guidance it provides.

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

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

Given the absence of parameters and output schema, the description covers the essential behavior: what is returned, what the user must do, what to pass to finish_login, and the code's validity/security. No critical gap remains for an agent selecting or invoking the tool.

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

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

The tool has zero parameters, so the schema covers everything and the description does not need to document parameter meaning. It still clarifies that no configuration or restart is required, which is the relevant semantic for a no-argument 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?

Description opens with the explicit role ('Первый шаг подключения') and states the concrete return value: a link to the Yandex OAuth page. It clearly separates this tool from finish_login by naming it as the first step.

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 specifies the exact workflow: show the full link, ask the user to authenticate, confirm access, and send back the code. It explicitly directs the resulting code into finish_login, naming the sibling alternative and giving clear when-to-use context.

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

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

Beyond the annotations (non-read-only, open-world, non-idempotent), the description discloses the expected verification state (usually IN_PROGRESS) and the specific 409 conflict error. It also explains external prerequisites (TXT record, file, meta tag), adding useful behavioral context without contradicting the annotations.

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

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

The description is three sentences, each carrying essential information: action, prerequisites, response, and error. It is well-structured and front-loaded with the core purpose, with 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 tool with no output schema, the description explains the response by referencing get_verification_status, which is an acceptable shorthand given the sibling context. It also covers the likely error case. However, it does not fully enumerate possible verification_state values, leaving minor ambiguity if the referenced tool is not understood.

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

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

Schema coverage is 100%, but the description enriches the enum values with specific instructions for each verification_type (DNS, HTML file, meta tag). It also clarifies the optional host_id and its fallback to an environment variable, adding meaning beyond the raw schema.

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

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

The description clearly states the tool 'запускает проверку прав на сайт' (launches site verification) using a selected method, which is a specific verb-plus-resource action. It distinguishes itself from get_verification_status by focusing on starting the verification rather than querying status.

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

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

The description provides clear prerequisite guidance (place UIN code before calling) and references the sibling get_verification_status for the UIN and response format. While it does not explicitly state when not to use the tool or name alternative actions, the context is sufficient to infer that this tool is for initiating verification.

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