run_tracking

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

With no annotations, the description carries full behavioral disclosure. It reveals side effects: spending Search API calls and writing a history measurement. It also provides the important no-op guarantee: the run stops before the first request and spends nothing when limits would be exceeded, and it discloses the blocked-response behavior.

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

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

Three sentences with no filler, front-loaded with purpose, then cost, then guardrails. Every sentence adds decision-relevant 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?

Covers purpose, cost, failure modes, and the unblocking parameter despite having no output schema. The main omissions are success-return behavior and the meaning of region, but the description is nearly sufficient for a first correct invocation.

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

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

Schema description coverage is 80%, so the schema already documents most parameters. The description adds a use-case link for now (how it lifts the restriction in blocked runs), but it does not materially extend domain/queries/competitors semantics. Region remains undescribed in both schema and 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?

States a clear action: capture current positions for tracked queries and persist a measurement to history ("Снять текущие позиции по отслеживаемым запросам и записать замер в историю"). This distinguishes it from sibling tools like track_query or get_positions by emphasizing tracked-query scope plus the history write, and it also flags Search API cost.

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?

Explains when running makes sense and the constraints: a run consumes Search API quota, and aborts before any request if it would exceed YASEO_TRACKING_MAX_CALLS or violate YASEO_TRACKING_MIN_INTERVAL_DAYS. It also tells the agent how to respond to blocks via the now parameter. It does not explicitly name sibling tools as alternatives, so no exclusions are given.

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