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

Annotations declare write/idempotent/non-destructive, and the description goes well beyond that: it discloses partial-merge semantics, that a fact with its own field is rejected as typed_field if sent via answers, that rejected and clarify lists are the correction surface, and that the rest of the write is saved either way. That last point in particular is non-obvious failure behavior an agent could not infer from the annotations.

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 content is dense but front-loaded: the merge rule and id/included semantics come first, then vehicle identification, answers routing, and optional fields. Each bullet carries distinct, actionable information, though the third and fourth bullets pack several rules into single long sentences and could be split for scanability.

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?

With no output schema, the description correctly carries the return-value burden, explaining that status, suggested, rejected, and clarify come back and how to act on each. For a 5-parameter, deeply nested mutation tool, nothing an agent needs in order to call it correctly or interpret the response is missing.

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 80%, so the schema already carries most field documentation, and the baseline would be 3. The description still adds real semantic value the schema does not: id-vs-no-id meaning (update vs add), included toggling quote membership, the precedence of VIN/plate over year/make/model, and the routing rule between typed fields and answers.

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 opening sentence states a specific verb and resource — saving customer-supplied application facts — and immediately describes the merge semantics that define the tool. Read against siblings like jerry_get_status and jerry_start_shopping, it is unmistakably the write path into an existing application, with no overlap or ambiguity.

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?

Guidance is conditional and explicit throughout: send only new or changed facts, supply year/make/model only when there is no VIN or plate, send coverage and history.currentMonthlyPremiumCents only when the customer raises them, and send that id with included:true once a suggested item is confirmed. It states when-not cases, not just when, which is exactly what an agent needs to avoid bad writes.

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