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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description adds real detail beyond them: temporary files are removed, and already finished files are not deleted, which is a meaningful scoping nuance an agent could not infer from annotations alone. The repeat-safety sentence largely restates idempotentHint.

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 action front-loaded and no wasted wording. Slightly compressed to the point that the destruction scope could be tied more explicitly to what the caller loses.

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

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

An output schema exists and annotations carry the safety profile, so the description only needs to convey the destructive scope, which it does. Only minor gaps remain, such as failure behavior for an already-completed job (implied by 'already finished files are not deleted').

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

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

Schema description coverage is 100% and both parameters already carry descriptions naming their source tools (metrika_export_report, metrika_status). The description adds no parameter-level information, 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 ('Cancels a Yandex Metrika export job') plus the secondary effect of removing temporary files, which distinguishes it from siblings like metrika_get_job and metrika_export_report. It does not explicitly name an alternative, but the job-cancel scope 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?

Implies usage context (cancelling an in-flight export) and notes 'Safe to repeat', but gives no explicit when-to-use/when-not guidance or pointer to sibling tools such as metrika_get_job for checking job state first. Adequate but with clear gaps.

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=false, so the safety profile is covered. The description adds genuinely new behavior: it performs no API call, and it warns that metric entries carry aggregation rules such as 'users must never be summed' — a real correctness constraint an agent would otherwise miss.

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

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

A single dense sentence, front-loaded with the verb and resource, with the kind enumeration and the critical aggregation caveat inline. No filler and nothing redundant with the schema.

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

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

An output schema exists, so the description need not describe return values, and both parameters are fully documented in the schema. For a two-parameter read-only catalog tool, nothing an agent needs in order to call it correctly is absent.

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

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

Schema coverage is 100%, so baseline would be 3, but the description goes beyond the bare enum by explaining what each kind contains (presets = ready-made reports; metrics = unit and aggregation rules; dimensions; periods). It does not describe the optional 'search' substring filter, though the schema documents it adequately.

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 ('Lists the Yandex Metrika report fields this server supports') and enumerates the exact four kinds. It is instantly distinguishable from the sibling report-execution tools (metrika_run_report, metrika_run_timeseries), which consume rather than list these fields.

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

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

Usage is clear by implication and reinforced by 'No API call', signalling this is a cheap discovery step to take before calling a report tool. What is missing is an explicit 'call this first if you do not know valid metric/dimension names' routing sentence against the siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive and open-world, so safety is covered. The description adds real behavior beyond them: identical-conditions requirement for comparability, null percent on a zero baseline, percentage points for rate metrics, quota consumption with cache fallback, and an explicit prompt-injection warning about labels being external data.

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 comparison semantics and no filler sentences; each clause carries content (default period, null-percent edge case, quota, injection safety). The semicolon-chained density makes it slightly harder to scan than a bulleted structure would be.

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 11-parameter nested tool with an output schema, the description covers comparison semantics, defaults, edge cases, quota behavior and safety, which is what an agent needs before calling. The only meaningful gap is explicit sibling differentiation against the report and timeseries tools.

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 bar is the baseline 3, and the description does add meaning: it explains that dimensions produce per-segment comparisons and restates the default period pair, which governs how the periods object should be left unset. It still does not explain the interaction between preset and goal_ids beyond what schema text says.

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

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

States a specific verb and resource: 'Compares Yandex Metrika traffic between two periods'. It also names the comparison outputs (baseline, current, absolute and percent change, percentage points) and contrasts the mode with per-segment comparison via optional dimensions, which separates it from metrika_run_report and metrika_run_timeseries.

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 clear operating guidance: same counter/metrics/filters/time zone for a valid comparison, default period pair, and an explicit caution not to loop calls because they spend API quota (with cache caveat). It does not explicitly say when to prefer this over metrika_run_report or metrika_run_timeseries, so the sibling routing is inferred rather than stated.

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 non-read-only, open-world, non-idempotent and non-destructive, and the description adds real behavior: the sign-in happens in the browser, the URL is one-time and local, and no token passes through chat. It does not warn that a second call without connection_id may create a duplicate connection, which is the natural risk given idempotentHint=false.

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

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

Three short sentences, front-loaded with the action and scope, then the return value, then the renewal and next-step instructions. No filler and nothing buried.

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

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

With an output schema present, return values need little explanation, yet the description still names login_url and its one-time nature, plus the follow-up tool. The remaining gap is the optional alias parameter's effect and the consequence of repeated invocation on a very small two-parameter 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 coverage is 100%, so both parameters are already documented, and the description's phrasing about connection_id closely mirrors the schema's own wording. The 'alias' parameter is not explained at all in the description, so it adds little meaning beyond structured data.

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 ('Signs in to Yandex Metrika in the browser') with the granted scope ('read-only access') and the return artifact ('one-time local login_url'). It is clearly distinguishable from siblings like metrika_status or metrika_disconnect, which are named as adjacent steps in the flow.

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 clear when-to-use context plus a renewal path ('Pass connection_id to renew an expired connection') and an explicit follow-up ('Afterwards call metrika_status'). It does not state a precondition such as checking metrika_status first, or what happens if a connection already exists, so it stops short of full 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, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the payload includes goals with IDs and a warning that goal names can repeat, which affects how downstream calls must be made. No return shape or failure modes are described, but the output schema covers returns.

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, and the purpose is front-loaded before the workflow hint and the ID caveat. Every sentence carries actionable 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 two-parameter read tool with full schema coverage, annotations, and an output schema, the description covers what an agent needs: what is returned conceptually, when to call it, and the goal-ID caution. Only the relationship to sibling tools like metrika_list_counters is left implicit.

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 counter_id and connection_id both documented and pointing at their source tools (metrika_list_counters, metrika_status). The description adds no parameter-level detail beyond implying a single counter is targeted, 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 ('Shows') and a precise resource scope: counter settings (time zone, status, access) plus its goals with IDs. This is clearly distinguishable from metrika_list_counters, though the description doesn't name that sibling explicitly.

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 a concrete usage trigger: 'Call before goal reports.' That tells an agent exactly where in a workflow this fits. It stops short of naming alternatives (e.g. metrika_list_counters for enumeration vs. this for detail), so it's clear context without explicit 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?

The annotations already flag destructive=true and idempotent=true, and the description goes well beyond that by specifying exactly what is destroyed — exports, token, cache — and what is not recoverable ('Data already shown in the chat cannot be recalled'). It also clarifies that Yandex-side access revocation is out of scope, which prevents a false expectation of full cleanup.

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, effects front-loaded, then the irreversibility caveat, then the out-of-scope note. Nothing is repeated from the title or annotations and every clause carries new 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 one-parameter tool with an output schema and rich annotations, the description covers all the decision-relevant facts: what is removed, what is irreversible, and what remains the user's responsibility. An agent can call this correctly and set expectations accurately from the description alone.

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 connection_id parameter is documented in the schema with an example and a pointer to metrika_status. The description adds no further meaning about the identifier, 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?

The description names a specific verb and resource ('Disconnects a Yandex Metrika connection on this computer') and enumerates the concrete effects (cancels exports, deletes token, clears cache). Paired with the sibling list, an agent can immediately distinguish it from metrika_connect and the read-only status/report tools.

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

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

It gives a clear context for use (tearing down a connection) and an explicit boundary condition: revoking app access inside Yandex is a separate user step, so the agent knows this tool does not accomplish that. It stops short of naming when not to use it versus alternatives such as metrika_cancel_job for individual job cleanup.

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

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

The description adds substantial behavior beyond the annotations: the export runs in the background, returns a job, requires idempotency_key, returns the same job for the same key, and can be resumed with only connection_id and resume_job_id. This is consistent with idempotentHint=true and readOnlyHint=false, and it discloses the polling and artifact-read workflow.

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 compact sentences, front-loaded with the core action and followed by the operational workflow. Every sentence carries useful information without 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 complex asynchronous export tool with an output schema, the description covers job creation, idempotency, resume behavior, polling, and artifact consumption. The remaining report-shaping details are documented in the comprehensive input schema.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds important conditional meaning: idempotency_key is required for a new export, and resuming requires only connection_id and resume_job_id. It does not explain every report option, but those are already covered by 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 states a specific verb and resource: it exports all rows of a Yandex Metrika report to a CSV or JSON file as a background job. The scope and async job return are clear, though it does not explicitly contrast this tool with sibling metrika_run_report.

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

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

It gives clear next-step guidance: poll metrika_get_job until completed, then read with metrika_read_artifact or give the user file_path. It also explains the resume path, but does not explicitly say when to choose this over metrika_run_report or metrika_run_timeseries.

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 that job errors and result files are surfaced, which is useful behavioral context, but says nothing about polling cadence, terminal states, or how failures are 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?

A single sentence, front-loaded with the verb and resource, with the returned fields listed in a compact clause. No filler, no repetition of the 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?

An output schema exists, so return values need not be spelled out, and the two required params are fully documented in the schema. What's missing is only workflow context — that this is the polling companion to metrika_export_report and what to do on failure.

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

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

Schema description coverage is 100% and both required parameters carry their own descriptions, including the ID pattern and where each value originates. The description adds no parameter-level meaning beyond that, 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 pairs a specific verb ("shows") with a specific resource (a Yandex Metrika export job) and enumerates what is returned: state, progress, errors, and result files. That makes it clearly distinct from job-creating or job-cancelling siblings, though it never names those siblings explicitly.

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

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

Usage is only implied: the description reads as a polling/inspection tool for a job created elsewhere, and the schema note ("Job ID from metrika_export_report") supplies the workflow link. Nothing states when to prefer this over metrika_cancel_job or metrika_read_artifact, and no conditions or exclusions are given.

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 by structured data. The description adds useful context about results being scoped to a connection and what fields come back, but omits pagination behavior despite a cursor parameter being present. Adds value, but not rich behavioral detail.

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

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

Two sentences with zero filler: the first defines the resource and its returned fields, the second states the follow-up action. The key hand-off instruction is placed at the end where it is easy to act on, and nothing is repeated.

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

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

An output schema exists, so return values need not be enumerated, yet the description still summarizes the important fields, and it explains the required connection_id via the schema. The only meaningful gap is that a paginated list tool does not mention cursor-based paging or result limits, which matters for an agent deciding whether one call suffices.

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 cursor, search and connection_id are already documented in the schema (including the pointer to metrika_status for the connection ID). The description adds no syntax, matching rules, or default behavior beyond the schema, so baseline 3 applies.

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

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

The description gives a specific verb and resource ("Lists Yandex Metrika counters") and disambiguates the term with a plain gloss ("tracked websites") plus the exact fields returned (ID, name, site, time zone, access level). It does not explain how this differs from sibling tools like metrika_status or metrika_describe_counter, so it stops short of full sibling differentiation.

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 clause "Pass the ID as counter_id to other tools" gives concrete workflow guidance: use this tool to discover counter IDs before calling report/describe tools. It stops short of explicit exclusions (e.g., when to prefer metrika_status for connection info), but the intended context 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real behavior the annotations don't: the 32 KiB ceiling and that chunks are cut on line boundaries, which matters for parsing. It stops short of explaining cursor exhaustion or whether an empty chunk signals end-of-file.

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 short sentences, zero filler. The chunking behavior leads and the input constraint follows immediately, so the most decision-relevant facts are 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?

An output schema exists, so return values and next_cursor needn't be re-explained, and the annotations carry the safety profile. What remains thin is the termination/pagination lifecycle across successive calls, which for a chunked reader is the one thing an agent most needs stated.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by clarifying the identifier semantics ('never a path or URL'), which prevents a plausible misuse the pattern/regex alone doesn't rule out. It adds nothing about cursor or max_bytes, but the schema documents those well.

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 ('Reads a finished Yandex Metrika export file') plus the chunking unit, and explicitly rules out the common wrong input ('never a path or URL'). That constraint alone separates it from siblings like metrika_get_job or metrika_export_report.

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

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

Usage is implied rather than stated: the chunk/cursor framing tells an agent this is a paginated read, and the schema notes artifact_id comes from metrika_get_job, but the description itself never says 'use after the job finishes' or names an alternative. An agent must infer the sequencing from structured fields.

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 read-only/idempotent/open-world, but the description adds quota consumption and cache behavior, the strict-accuracy refusal of sampled data, the default period in the counter time zone, and a prompt-injection warning about labels. These are real operational traits an agent cannot get from 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?

A single dense paragraph that front-loads purpose, then alternatives, then defaults and safety. Sentences are information-bearing, though the result-format and prompt-injection clauses could be trimmed or split for scanability.

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

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

With an output schema present and 13 fully described parameters, the description only needs to cover intent, routing and operational caveats. It does all three, including defaults, quota, cache and untrusted-label handling, so nothing an agent needs 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 defaults, enums and limits are already documented per parameter. The description restates the preset list and the period default and adds the 200-row cap, but contributes little meaning beyond the schema.

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

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

States a specific verb and resource ('runs a Yandex Metrika traffic or goal report for one period') and enumerates both modes (preset vs explicit metrics/dimensions), so the agent immediately knows what the call produces. It also names the sibling metrika_export_report, separating this tool from the bulk path.

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 routing rule: cap of 200 rows per call, and 'use metrika_export_report for everything' beyond that. It also warns against looping repeated calls. It does not distinguish itself from metrika_run_timeseries or metrika_compare_periods, which is the remaining gap.

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 still adds non-obvious behavior: exact calendar boundaries in the counter time zone, flags on buckets containing today or clipped by the period, top-N segment series when dimensions are supplied, and quota consumption despite the read-only nature.

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?

Five dense sentences, front-loaded with what the tool produces, then boundaries, then the quota warning. Every sentence carries information; the only cost is that the prompt-injection caveat sits mid-paragraph rather than at the end.

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 12-parameter, nested-schema tool with a full output schema, the description covers the remaining gaps: time-zone semantics, boundary clipping, cache/quota behavior and untrusted result labels. An agent can call this correctly without further context.

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 parameters are richly documented, so the baseline of 3 applies. The description adds the bucket/dimension interaction ('Optional dimensions return top-N segment series'), but it also states a default of 'last 28 complete days by day' while the period schema declares 'last_7_complete_days' — an inconsistency the agent must resolve from the schema.

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

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

The description opens with a specific verb and resource ('Shows Yandex Metrika metric dynamics') and immediately narrows scope to bucketed time series (day/week/month). That distinguishes it from a plain report tool, though it never names metrika_run_report or metrika_compare_periods as the contrasting siblings.

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

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

It gives a usable default ('last 28 complete days by day'), a rule for weekly series, and a caution against looping calls, which is real guidance. What is missing is explicit routing: nothing says when to pick this over metrika_run_report or metrika_compare_periods.

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 readOnly, idempotent, non-destructive and closed-world, so the description's real value-add is the auth disclosure — the tool functions before any Yandex sign-in, which annotations cannot express. Mentioning that it returns capabilities and a recommended next step also hints at the response shape without duplicating the 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?

Two tight clauses with the purpose front-loaded and the workflow instruction immediately after. The middle list of returned items is slightly run-on but each element carries information; no filler sentences.

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

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

An output schema exists, so return-value detail is not required, and the sole optional parameter is fully described in the schema. The description supplies the two things structured fields cannot — ordering and pre-auth availability — leaving little an agent needs that is missing for such a simple discovery 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 coverage is 100% and the single optional connection_id is fully documented there, so the baseline applies. The parenthetical "(connection_id values)" usefully signals that the tool emits the IDs the parameter consumes, but it adds no new syntax or filtering semantics beyond the schema.

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

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

States a specific verb and resource ("Shows Yandex Metrika connections") and enumerates what the response contains (state, export jobs, capabilities, next step). It is distinguishable from siblings like metrika_list_counters or metrika_get_job, though it does not explicitly name which sibling it replaces.

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?

"Call it first" gives an explicit ordering instruction that tells the agent where this fits in a workflow, and "works before any Yandex sign-in" clarifies the prerequisite state. It stops short of naming alternatives or stating when-not to use it, so no exclusion guidance is present.

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