List Billable Usage Logs

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

With readOnlyHint=true already set, the description still adds substantial behavioral context: pagination behavior, the nature of each entry (token-consumption event), and the exact fields included. It goes beyond annotations by describing response structure and metadata, giving agents full transparency on what to expect.

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 description is a single dense paragraph but every sentence contributes value: usage triggers, what is returned, filtering options, and response fields. It is longer than minimal but appropriately so for a complex list tool; no filler or repetition.

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?

With no output schema, the description fully explains what the caller will receive, including pagination metadata and per-item fields. It also clarifies that it's organization-wide, filters by type/search/date, and returns token-consumption events—complete coverage for a 6-parameter read-only list tool.

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 detailed per-parameter descriptions. The tool description reinforces how filters map to user needs (e.g., filtering by type, search, and date range) and adds meaningful context about pagination defaults and page size caps, complementing rather than repeating the schema.

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 opens with explicit user intents ('who consumed tokens, how their quota was spent, or wants an audit') and names the exact resource ('billable feature usage logs'). It clearly distinguishes from sibling tools like list_niches or get_quota by focusing on token-consumption events.

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?

Provides strong when-to-use guidance ('Use this when...') and lists supported filters. It does not explicitly mention when not to use it or name alternatives, but the context makes it clear this is for audit/quota questions, distinguishing it from read-only tools like get_quota.

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