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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured fields. The description adds one piece of genuinely new context — results are restricted to data visible to the linked Market Brew account. It says nothing about pagination, history depth, or ordering, so it clears the lowered bar but only barely.

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?

Two short sentences with the trigger front-loaded and zero padding, which is structurally sound. However, the first sentence carries no information beyond the tool name, so it does not earn its place, and the total length is under-specified for a two-parameter tool with a nested object.

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?

There is no output schema, so the description should help the agent anticipate the return shape, but it only says the data is account-scoped. Combined with an undocumented required 'id', an unenumerated nested query object, and heavy sibling ambiguity, the definition leaves an agent under-equipped to call this tool 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 description coverage is 50%: the nested 'query' object is documented with its filter keys, but the required 'id' parameter has no description in either the schema or the description text. The description never explains that 'id' identifies the usage report whose history is being fetched, so it does not compensate for the coverage gap.

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 is essentially a restatement of the tool name: "Use this when the user asks to get usage report history." It does not state what a usage report history actually contains or how it differs from close siblings such as get_usage_report, get_usage_metric_history, get_usage_metrics, and list_usage_reports. The only substantive content is the account-visibility clause, which is scope rather than 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?

The "use this when..." phrasing is circular — it triggers on the phrase "usage report history" rather than on a recognizable user intent or data condition. No exclusions or alternatives are named, even though the sibling list contains at least four other usage-related tools an agent must choose between. Effectively no routing guidance.

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