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

Annotations already establish readOnly/non-destructive/openWorld=false, and the description adds meaningful context: calls are grouped by the verified human behind each agent, storage is shared Space cost, user pages do not change Space totals, purchased debits exclude internal-agent transfers, and only the authenticated owner's finances are returned. Some sentences ("Tracking limits are explicit") are cryptic, but the added behavioral disclosure is real.

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?

Purpose is front-loaded and there is little outright filler, but it is one dense paragraph packing four distinct modes, and clauses like "Tracking limits are explicit and user pages do not change Space totals" are terse to the point of opacity.

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 10-parameter tool with an output schema and safe-read annotations, the description covers the relevant modes, the parameter dependency constraint, and access rules, which is enough to call it correctly. Only breakdown enum semantics and before_period format remain unexplained.

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?

With schema description coverage at 0%, the description carries the burden and mostly succeeds: it explains history_limit/before_period, spaces_limit/spaces_cursor, users_limit/users_cursor, and the space_id/breakdown/rows_* dependency. The gaps are the meaning of the breakdown enum values (function/caller/user) and the accepted format for before_period.

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?

"Read your weekly included coverage, purchased Credits and category totals" gives a specific verb plus resource and names the sibling boundary (account_get_wallet is person-only). The purpose is clear but slightly muddied by folding in Space listing and per-space breakdown modes that read like separate operations.

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?

Explicitly ties parameter groups to modes (history via history_limit/before_period, Space listing via spaces_limit/spaces_cursor, per-space inspection via space_id) and states "breakdown, rows_limit and rows_cursor require an owned space_id" plus the linked-agent vs person access rule. It stops short of naming which sibling to pick for usage-adjacent needs, but the access/alternative guidance is concrete.

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