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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the mutation and repeatability profile is largely covered. The description does add real context beyond that: every call creates another version rather than replacing one, and published terms are inert until agencies accept. It stops short of noting authorization failure modes or what happens when effectiveFrom is in the past.

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?

Three short sentences, front-loaded with the action and scope, then the audience restriction, then the versioning/acceptance caveat. Every sentence carries distinct information and nothing is repeated from the schema beyond the parenthetical field list.

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 six-parameter, fully-required mutation tool with an output schema, the description covers the essentials: authorization scope, targeted-vs-global behavior, versioning semantics, and downstream acceptance. Only edge behavior (invalid effectiveFrom, re-publishing identical terms) is unaddressed, which is a minor gap given annotations and the output schema.

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%, so all six parameters are already documented, which sets the baseline at 3. The description does add one genuine semantic beyond the schema: partnerId null means publish to all agencies, which the schema itself does not say. The remaining parameter meanings (discount, grace days, dates) merely restate the schema.

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 ('Publishes a new set of wholesale commercial terms'), enumerates the substance of those terms, and defines the scope switch (one agency vs. all agencies when partnerId is null). The closing note that agencies must still accept it separates publishing from the accept_terms sibling without needing to inspect either 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 a clear audience gate ('Platform commercial operators only') and explains the two usage modes via partnerId null vs. set. What it lacks is any explicit exclusions or a named alternative for the accept/approve path, so the agent is left to infer that acceptance is a separate tool call.

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