billing_history_create

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

Annotations already state readOnlyHint=false and destructiveHint=false, telling the agent this is a non-destructive mutation. The description adds nothing beyond that: no permission requirements, no uniqueness or duplicate-handling behavior for providerUuid+billedAt, and no disclosure of side effects such as provider balance recalculation.

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?

A single four-word sentence is certainly concise and front-loaded, but brevity here is under-specification rather than efficiency — there is no second sentence to carry any of the missing behavioral or parameter context.

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 mutation tool with no output schema, 33% schema coverage, and three required parameters, the description is too thin. An agent cannot determine required permissions, duplicate-handling rules, or what the created record's identifier looks like from this definition.

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 only 33% — billedAt is documented in the schema, but providerUuid and amount carry no description in either place. The description says nothing about these parameters, so it fails to compensate for the coverage gap in a tool where providerUuid (which provider the entry belongs to) and amount semantics matter.

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 verb 'create' plus resource 'billing history' makes the basic operation identifiable and distinguishable from siblings billing_history_list and billing_history_delete. However, 'infra billing history' is oddly phrased and the description never explains what a billing history record represents (a charge entry? a line item tied to a provider?), leaving the purpose only partially clear.

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?

No guidance on when to create a billing history entry versus alternatives, no prerequisites, and no mention of related siblings such as billing_provider_get or billing_node_create. The agent must infer all usage context from the name alone.

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