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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the crucial meaning behind that: 'Replaces the earlier offer,' so the agent knows existing data is overwritten rather than merged. It also clarifies the one-time capture intent ('asked ONCE') and dollar units, though it says nothing about validation failures or what the call returns.

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 purpose and the leading 'asked ONCE' constraint are front-loaded, and the illustrative dialogue shows how the offer gets used. The example quote is somewhat long, but it is doing explanatory work rather than padding.

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 five-parameter save tool with no output schema, the description covers what is saved, when to ask, the overwrite semantics, and units. The main remaining gap is the absence of any statement about the response or what happens on repeated calls, which matters for a destructive-and-idempotent tool.

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 every parameter is already documented in the schema. The description only reiterates units ('Prices in dollars') and the 'in their words' framing for services, which adds marginal meaning beyond the existing field descriptions.

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 definition states a concrete verb and resource ('Save what the agency sells and its usual prices') and explains the artifact's role as the default offer for agreements and outreach. It is clear what is being stored, though it never explicitly distinguishes itself from the sibling agreement_template_save, which an agent could easily confuse with it.

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?

It gives a concrete trigger: 'Ask it the first time the agency wants an agreement or starts prospecting and no offer is saved,' and points to agreement_template_get as the way to check whether an offer exists. That is a real when-to-use condition, though it stops short of stating when not to use it (e.g., re-saving vs. viewing).

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