catalog_create_metering_policy_assignment

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

Annotations already declare a non-readonly, non-idempotent write, so the description is not the sole source of the safety profile. It does add real behavioral context the annotations lack: that a body with entityType=ALL deletes older assignments for the given pricingCardId, and that fields are validated against business rules. However, it never explains those business rules or the response, and the 'deletes older assignments' side effect sits uneasily with destructiveHint=false without being acknowledged.

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 first sentence duplicates the tool title, the second restates the same create action at greater length, and the endpoint path is tacked on at the end. 'Validate its field according to business rules' is vague filler that consumes space without telling the agent anything actionable.

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 one-parameter, fully documented create endpoint with no output schema, the description covers the write action and the key replace-on-ALL side effect. It still leaves open what is returned and how the tool relates to the metering-policy naming, which matters for an agent deciding between the several assignment-related siblings.

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 semantics the schema lacks: the body must carry ALL fields, and entityType=ALL specifically means prior assignments for that pricingCardId are removed. The enum's own schema description ('Pricing card assigned entity type') does not convey that replace behavior, so this is genuine added meaning.

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 does state a create action on a concrete resource (pricing card assignment) and even names the endpoint, so the operation is identifiable. But the tool is named catalog_create_metering_policy_assignment while the text talks only about 'pricing card assignments', leaving the metering-policy relationship unexplained, and it never distinguishes itself from siblings such as catalog_create_metering_assignment_strategy or catalog_patch_metering_policy_assignment.

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 statement of when to use this versus the existing create/patch/delete assignment siblings, nor of prerequisites or permissions. The only guidance-like content is a behavioral rule about entityType=ALL replacing older assignments, which is a side effect rather than usage guidance.

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