internal_squad_stats_get_internal_squad_user_usage

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

With no annotations, the description carries the full burden, and it does disclose genuinely useful traits: zero-filled days across the range and an ingestion lag of roughly 2 minutes before data is flushed. It does not state permissions/auth requirements, response shape, or the semantics of the minTotalBytes threshold it references.

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 purpose is front-loaded and the HTTP route line is acceptable, but the trailing 'Tags: ...' line and the Russian pagination sentence ('Пагинация через query-параметры: start') are boilerplate with no bearing on this tool, since the only query params are start/end. Wasteful tail dilutes an otherwise compact description.

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 4-required-parameter read tool with no annotations and no output schema, the description covers the return concept (daily usage, zero-filled) and freshness lag, which is helpful. It still leaves the response structure, the meaning of userId, and the nonexistent minTotalBytes filter unresolved.

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 75%, but userId is a bare number with no description and the description never explains it. Worse, the description advertises a minTotalBytes filter that does not exist among the four declared parameters (additionalProperties is false), so it actively misleads about the callable surface.

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 ('Get a single user daily traffic usage on the internal squad nodes for a period') and names the HTTP route, so the core operation is unambiguous. However, the very next sentence shifts to 'Returns users whose total usage ... is >= minTotalBytes', which describes a plural, threshold-filtered list rather than a single-user lookup, muddying what the tool actually returns.

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?

No guidance on when to prefer this over the near-identical siblings internal_squad_stats_get_internal_squad_usage, internal_squad_get_internal_squad_usage, or bandwidth_stats_nodes_get_stats_node_users_usage. The agent is left to infer the distinction from names alone.

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