hive_measure_keyword_metrics

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

Annotations only declare non-read-only/non-idempotent hints; the description carries the real burden. It discloses quota accounting (one daily Hive measurement unit, and which request type spends it), partial-failure semantics ('a failed source leaves the other valid metric in the answer'), async behavior (wait 0–20s, HTTP 202 means still running), the opt-in hive:measure scope and its two approval paths, and an iOS-only platform constraint.

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 core action and its trigger are front-loaded, and the dense sentences about quota, dedup, and failure isolation each carry non-obvious information. It is information-rich but slightly loaded for a single paragraph; nothing is 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?

For an async, quota-consuming task tool with no output schema, the description covers triggering, cost, deduplication, async polling contract, partial failure, auth scope, and platform limits. An agent has everything needed to call it and interpret the outcome without opening other 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 baseline is 3, but the description adds meaning beyond the schema: it explains what wait actually does (keeps the call open until the result is stored) and what a 202 outcome implies, plus that the two metrics are independently resolved. It still doesn't characterize term normalization or country fallback beyond 'defaults to us'.

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 precise verb+resource+scope: 'Start a measurement of one keyword's popularity and/or difficulty in one storefront.' It names the exact conditions that make this the right tool and explicitly distinguishes itself from the sibling hive_keyword_metrics, which only reads the stored value.

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 states when to use it ('when the stored value is missing or stale'), when no new work is consumed ('a fresh value or verified absence', 'a request that joins a job already running uses no daily measurement unit'), and routes the agent elsewhere for reading results ('read it later with hive_keyword_metrics'). Alternatives and conditions are explicit, not inferred.

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