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

Goes well beyond the annotations: discloses the required OAuth scope, that approvals are signed and valid ten minutes, what gets refused (unowned or unavailable custom listings, mixed input modes, holds/sale prices/seller bounds), and clarifies that readOnlyHint is compatible with write scope because preparation only issues approvals. It also cautions that cached catalog asks are not live sold comps. Deduction only because several behavioral statements are restated twice (consent, read-only nature) rather than adding new information the second time.

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?

Purpose and confirmation requirement are front-loaded, and return/refusal/auth details follow in a logical order. However, there is redundant phrasing — 'Requires OAuth store:prices:write consent' followed by 'Write consent is required because...' says the same thing twice, and the read-only caveat repeats the annotation's claim rather than extending it.

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 multi-mode, five-parameter tool with no output schema, the description covers the return payload (old/proposed prices, market guidance with timestamp and usability, cached lowest ask, skipped reasons, signed approvals), the failure conditions, and the auth prerequisite. An agent has everything needed to select it and prepare 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 100%, so the baseline is 3, but the description adds genuine meaning: the mutual exclusivity of updates vs. strategy input (the oneOf is easy to miss), that an omitted strategy falls back to the store setting, and that strategy becomes store-wide strategy for confirmed automation. It does not explain cursor pagination, which the schema already covers.

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 ('Prepare exact one-time card price changes') plus the confirmation gate, and immediately bounds scope by excluding recurring pricing, inventory quantities, and publication. That lets an agent separate it from supercatch_prepare_price_changes and supercatch_execute_price_changes without reading 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?

Gives an explicit trigger ('use when the user wants an in-chat price update'), two mutually exclusive input modes with 'never combine them', a default rule for omitted strategy, and named exclusions for adjacent workflows. The only soft spot is that the follow-up apply tool isn't named, but 'ask for confirmation before applying' plus the pre-apply preparation framing covers the routing decision.

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