get_node_usage

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

With readOnlyHint=true already covering safety, the description adds two pieces of genuinely new context: the underlying usage data is flushed roughly every 2 minutes (so results can be stale), and the "[READ] POST" marker resolves the apparent conflict between a POST route and a read-only operation. It does not describe the shape of the returned user objects, but the annotation-relative bar is met.

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 short sentences, front-loaded with the outcome before the freshness caveat, and the endpoint/method tag is compact. Slight redundancy between sentence one and sentence two (both restate the threshold condition), which keeps it from being fully waste-free.

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?

No output schema exists, so the description must carry return-value semantics; it names the returned entity and the applied filter but not the fields on each returned user (usage totals, uuid, etc.). Combined with no usage guidance among ~90 siblings, the definition is adequate but leaves real gaps.

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 100%, so start, end, body.nodesUuids and minTotalBytes are all already documented in the schema. The description only restates the minTotalBytes comparison semantics that the schema already states verbatim, adding no syntax, units or edge-case detail beyond it.

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 with scope: "Get users exceeding a traffic threshold on the given nodes for a period," which precisely identifies the entity returned (users) and the filter (threshold over nodes). It is clearer than the crowded sibling set of stats tools, but it never names which sibling (e.g. get_stats_node_users_usage, get_stats_nodes_usage) to prefer, so differentiation is left to inference.

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 explicit guidance on when to use this tool versus the many adjacent stats/usage siblings (get_stats_user_usage, get_stats_node_users_usage, get_internal_squad_usage). The only usage-adjacent detail is the data-freshness caveat, which is behavioral rather than a selection rule.

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