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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuine behavioral caveat — that demand is not inferred from usage activity — plus packaging rules about where fields go. It does not describe what the calculation returns or how the two modes differ in behavior, so it adds moderate value only.

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 core capability is front-loaded, which is good, but the remaining sentences are a choppy list of packaging rules, and 'Follow its required fields and exact choices' is filler that restates the schema's job. Several sentences could be merged or dropped without losing information.

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?

This is a complex tool with two mutually exclusive input shapes, up to 120 periods, nested geography objects, and an output schema. The description never explains which fields belong to which mode or what the two modes produce, so an agent cannot construct a valid call from the description alone. The output schema offsets the need to describe return values, but the input-side gap remains large.

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 0%, so the description must carry the burden. It does explain the wrapper structure ('Put tool fields inside inputs'), that modelVersion is conditional, and that a REST-only field must not be passed — useful given the nested oneOf schema. But it says nothing about the mode enum, metric choices, period structure, or the geography block, leaving most parameter meaning to the schema's patterns and enums.

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 names two capabilities — measuring change across matched observations and evaluating constant-gain threshold scenarios — which maps to the two oneOf branches in the schema. However, the phrasing is abstract ('Measure changes across matched observations') and never states the resource in plain terms, so an agent must open the schema to learn what is actually computed. No sibling is named or distinguished.

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?

There is no when-to-use guidance and no alternative tool is named. The closest thing is a negative caveat ('No region or industry demand is inferred from usage activity'), which clarifies semantics but does not tell the agent when to pick this tool over buscalc_fluxneed or buscalc_foreneed.

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