query_monetization

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), so credit goes to what the description adds: 'Local only; never saves prices or changes catalog state', 'No automatic retries or pagination', and the caveat that 'Missing response data is not absence'. Those are genuine operational traits not derivable from the hints. It does not mention authorization scope or rate limits, so it falls short of a 5.

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?

Front-loaded with the operation and its scope, then safety, caveats, routing, and return shape in short declarative sentences. No filler, but it is a dense sentence chain covering six distinct topics with no formatting separation, which costs a bit of scannability.

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 generic three-parameter POST wrapper, the description supplies everything an agent needs: scope, safety, no-retry/no-pagination caveats, method-discovery prerequisite, sibling routing for GETs and writes. An output schema exists, so it need not explain return values, and its one-line return summary is sufficient.

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 100% and all three parameters are documented there, including the method-ID discovery flow and the 'put request JSON in body, not parameters' rule. The description only alludes to method discovery via describe_api_method and adds no naming, format, or pagination-token detail beyond the schema. Baseline 3 is correct when the schema carries the burden.

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?

States a specific verb and resource ('Run one scoped read-only commerce POST') and narrows the scope to two concrete operations: regional price conversion and offer batch reads. It also names the sibling it is not ('ordinary catalog GETs use read_publisher'), so an agent can distinguish it without opening any schema.

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?

Explicit positive routing ('Use for price estimates or offer batch reads requiring POST'), explicit negative routing ('ordinary catalog GETs use read_publisher'), and an explicit alternative for the write path ('Use prepare_monetization_write to propose saved catalog changes'). It also directs the agent to describe_api_method as a prerequisite step.

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