catalog_create_policy

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral detail — fields are validated against business rules, implying possible validation failures — but says nothing about what those rules are, what an error looks like, or whether creation requires a specific org context.

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 text is short but the first line ('Create a new pricing card') is immediately restated in the second line, wasting the most prominent position. The raw POST path is useful context, but the opening could have been used to disambiguate pricing cards from policies.

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 mutation tool with a deeply nested body schema (metering items, tag-based items, charge models) and no output schema. The description never explains the payload shape, the response, or which nested item collections are mutually exclusive, so an agent has to reverse-engineer intent entirely from the schema — and several nested item properties are empty objects with no typing.

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?

There is a single 'body' parameter with 100% schema description coverage and an inline description ('The pricing card to be created'), so the schema does the heavy lifting. The description adds no field-level guidance for the complex nested payload (fixedPrice, chargeModel, the various metering item arrays), which remains the hardest part of invoking this tool correctly.

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 verb is clear ('Create') and the description names the resource as a 'pricing card', but the tool itself is named catalog_create_policy, so an agent must reconcile two different resource nouns (policy vs. pricing card). The POST path confirms it targets /pricing-cards, but this naming mismatch makes it harder to distinguish from sibling tools like catalog_create_metering_policy_assignment and policy_create_policy.

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 guidance on when to use this versus sibling creation tools (catalog_post, catalog_create_or_update, catalog_create_metering_policy_assignment), nor any prerequisites such as required org scope or permissions. The only selection hint is the implicit 'new' in 'Create a new pricing card', which the agent must infer.

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