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

Annotations already cover readOnly/idempotent/non-destructive, so the description's real contribution is the auth requirement ('Requires recordings:read scope') and the permission-scoped visibility of the count. Both are operationally useful and not derivable from annotations or schema. Return shape (bare integer vs envelope) is left unstated.

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, purpose first, usage second, prerequisite last. No filler and nothing repeated from the title or 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?

A simple zero-required-parameter read tool with full schema coverage and no output schema; the description says what is returned (a total) and what scope governs it. Slightly short on whether the count respects the workspace/account selection, but nothing blocking an agent from calling it correctly.

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% with rich per-parameter text for account and workspace, so the baseline is 3. The description adds nothing about how workspace scoping affects the returned total, which is the one genuinely non-obvious semantic here.

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?

Specific verb+resource ('Return the total number of calls') with an explicit scope qualifier ('visible to the actor user'), which implicitly separates it from hub_list_calls and hub_count_search_calls. It never names those siblings outright, so the differentiation is inferred rather than stated.

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?

'Use to plan pagination' gives a concrete when-to-use condition, which is the main reason an agent would reach for a count endpoint. It stops short of explicit exclusions (e.g. 'do not use to count filtered results — use hub_count_search_calls') or prerequisite ordering.

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