gflow_usage_stats

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

With no annotations supplied, the description carries the full burden, and it discloses a genuinely surprising side effect: any gflow call may trigger a weekly background upload of usage totals, gated on the machine having shown the usage notice and visible in the telemetry block's upload state. What it omits is whether the tool itself is strictly read-only and whether the summary is limited by telemetry retention.

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 first sentence front-loads purpose and scope, the second specifies exactly what data comes back, and the third covers the side effect. Tight overall; the 'Like every gflow tool call' framing is boilerplate but earns its place by generalizing a non-obvious behavior.

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 spell out return shape, and it still sketches the two counts. For a one-parameter, low-complexity read tool this is nearly complete; only the interaction between telemetry being disabled and what the summary then contains is left unaddressed.

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 0% for the single 'weeks' parameter, so the description must compensate, and 'over the last N weeks' does establish that it is a lookback window ending now. It adds no bounds, accepted range, or behavior for extreme values, so it only partially fills the gap left by the bare 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 names a specific verb and resource (summarize local gflow-cli usage statistics), bounds the scope (last N weeks), and enumerates the two data sources it aggregates (command invocation counts from local telemetry, generation counts from the local catalog). No sibling tool overlaps this resource, so it is trivially distinguishable.

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 tool's purpose suggests calling it to inspect local activity, and the 'when enabled' clause signals telemetry must be on. There is no explicit when-to-use/when-not guidance, no comparison against alternatives such as gflow_get_credits or gflow_auth_status, which an agent might otherwise confuse this with.

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