market_get_price_history

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavior beyond those annotations: the from/to filter is applied 'locally' and the result is a chronological series with change statistics. This clarifies output shape and filtering semantics without contradicting annotations.

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 entire description is one compact sentence that front-loads the core action and then adds the key qualifiers: optional filter behavior and returned outputs. Every clause earns its place; there is no redundant filler.

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?

The output schema covers return values, so the description need not restate them. Still, the description leaves a meaningful gap: 'uniqueId' is not semantically clarified, and the relationship between required latitude/longitude and the depot list is not explained. The schema partially fills this via depots' description, but the description alone would not let an agent confidently construct a correct call.

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 only 57%, so the description must compensate. It adds meaning for depots ('selected product depot IDs') and from/to (date format, local filtering), but 'uniqueId' remains undefined and ambiguous—the agent cannot tell from the description what entity it refers to. Latitude, longitude, and distance are already described in the schema, so those are adequately covered.

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 uses a specific verb and resource: 'Get market price series' for a unique ID and selected depot IDs. It also states the date filter and the returned outputs (chronological series, change statistics), which clearly distinguishes it from siblings like market_get_product or market_compare_product_offers.

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 description gives enough context to infer the intended use: retrieving historical price series with optional date filtering. However, it does not explicitly state when to prefer this over alternatives, nor does it mention exclusions or conditions such as when compare/offer tools should be used instead.

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