commerce_market_observation_query

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the side-effect profile is covered. The description adds some context by stating that execution routes through a domain-agent dispatcher under JWT, tenant, and company scope, which helps the agent understand authorization context, but it does not disclose any further behavioral details beyond the 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 description is short and well organized with a clear Args section, but the opening sentence largely repeats the tool name and the routing sentence is more technical context than functional explanation. It is not bloated, yet some of its brevity comes at the cost of substance.

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?

Given the existence of an output schema, return values do not need explanation, and the two parameters are minimally described. However, for a tool with a destructive annotation and a name suggesting a query, the description does not explain the action's actual behavior, expected inputs, or why an agent would choose it over the many adjacent commerce tools, leaving significant ambiguity.

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?

The input schema provides no descriptions (0% coverage), so the description's parameter lines add meaningful value: 'message' is a free-text objective and 'inputs' is an optional JSON string of structured inputs. However, the explanations are terse and do not clarify what kinds of objectives or structured inputs are expected for this specific commerce action.

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 says 'Run the commerce domain agent action `market_observation_query`', which essentially restates the tool name without explaining what the action actually does or what a market observation query is. It identifies a domain and a routing mechanism, but not the concrete purpose or effect of the tool.

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 is given about when to use this tool instead of the many related commerce tools such as commerce_market_observation_ingest, commerce_trend_synthesis, or commerce_chat. The description only mentions the routing path and offers no selection criteria, exclusions, or alternative recommendations.

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