yandex_metrica_create_logs_request

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

Annotations declare it is a non-read-only, non-idempotent, open-world call, but the description adds the genuinely useful behavioral traits: the operation is asynchronous, must be polled via get_logs_request until status is 'processed', and date2 cannot be today. It does not discuss lifecycle cleanup/cancellation (cancel/clean siblings exist), so it falls just short of a 5.

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

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

Five sentences, each carrying distinct information with the purpose front-loaded. It is dense but every sentence (scope, preconditions, exclusions, polling, field prefixes) earns its place, though the length edges toward a wall of text.

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 correctly compensates by describing the async lifecycle and the polling step needed to obtain results. Combined with full parameter coverage, an agent has everything needed to invoke and follow through on the call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds field-naming syntax not present in the schema: fields must use the ym:s: prefix for visits and ym:pv: for hits. This ties the fields parameter to the source choice, which is meaningful beyond the 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 (create) and resource (asynchronous Yandex Metrica Logs API export of raw visits or hits), plus scope (one counter and date range). It explicitly distinguishes itself from yandex_metrica_get_report (aggregated totals), so the agent can route without opening the schema.

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

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

Gives explicit when-to-use ('when the user wants row-level data' after evaluate_logs_request confirms feasibility), explicit when-not-to-use ('not to test feasibility', 'not for aggregated totals; call get_report'), and a named follow-up (poll get_logs_request). The alternative and its selection condition are both stated.

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