bandwidth_stats_users_get_stats_nodes_usage

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

With no annotations, the description carries the full behavioral burden, and it delivers little. The GET route implies a read operation, and the trailing note hints at pagination, but there is no disclosure of auth requirements, rate limits, whether the range is inclusive, or what happens for out-of-range dates. Worse, the pagination note is attached to 'start', which the schema defines as a required start date, so the behavioral hint is likely wrong.

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 text is short but poorly front-loaded for an agent: it leads with a raw HTTP route, then a purpose line, then a tag list, then a Russian pagination fragment. The tag line and the pagination fragment do not earn their place and the fragment is confusing rather than informative.

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-parameter tool with no annotations and no output schema, the description is not complete enough. It never explains the topNodesLimit parameter, never clarifies the range semantics, and its one parameter reference is misleading. The only compensating detail is the route, which at least confirms this is a per-user read endpoint.

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 75% (end, start, userId documented; topNodesLimit has no description). The description only mentions 'start', and does so in a misleading way, framing it as a pagination query parameter when it is actually a required date bound. It adds no correct meaning beyond the schema and omits the undocumented topNodesLimit entirely.

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 line 'Get User Usage by Range' gives a specific verb+resource, and the route '/api/bandwidth-stats/users/{userId}' confirms the scope is per-user bandwidth usage over a date range. However, the tool name mentions 'stats_nodes_usage' while the description says user usage, creating ambiguity, and nothing distinguishes it from siblings like bandwidth_stats_nodes_get_stats_node_users_usage or internal_squad_stats_get_internal_squad_user_usage. The 'Tags: Bandwidth Stats Controller' line is noise that does not clarify purpose.

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?

There is no statement of when to use this tool versus the many similarly-named bandwidth-stats siblings. The only usage-flavored sentence is the Russian note about pagination via query parameters, which does not tell the agent when this tool is the right choice. The agent must infer selection purely from the route and name.

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