Jerry.ai

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description still earns credit by explicitly reinforcing that nothing is verified or changed and by naming the exact data surfaced, which goes beyond the annotation set. It omits auth/permission prerequisites, but for a zero-parameter read this is a minor gap.

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?

Two short sentences, front-loaded with the positive scope and closed with the negative scope. Every clause carries information and there is no filler or restatement of the title.

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?

An output schema exists, so return-value documentation is not the description's burden, and the annotations carry the safety and idempotency profile. What remains — what is read and what is deliberately not done — is fully stated, making the definition complete for this simple, parameterless read 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?

The tool takes no parameters, so there is nothing for the description to disambiguate. Per the baseline for zero-parameter tools, a 4 is appropriate; the description correctly avoids inventing arguments and instead spends its words on scope.

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 opens with a specific verb+resource ("Read the name, email and phone on the customer's Jerry account") and enumerates the exact fields returned, including phone verification status. The resource "account" is distinct from the sibling tools that deal with quotes, status, and applications, so an agent can route correctly without opening a 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?

"It doesn't verify an email or change any insurance information" gives a clear negative-scope signal that steers the agent away from mutation flows. However, it never names an alternative tool (e.g. jerry_update_application) or states the condition under which this read tool should be preferred, so it stops short of full when/when-not/alternatives guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: sort order and currency units, the 'prices are estimates until priceStatus is final' caveat, and the handling of declined quotes (excluded but counted in declinedCount). It omits any pagination or result-size behavior, so not a 5.

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?

Front-loads the core action and ordering before the optional bundleIds behavior and the caveats. Dense but each sentence carries distinct information; the final 'It doesn't request quotes' is terse but earns its place as an exclusion.

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?

No output schema exists, so the description must convey the return shape, and it does: sorted quote list, per-policy coverageSummary, bundle coverages/discounts/payment plans, and declinedCount. Pricing finality is also covered; only pagination/response envelope details are absent.

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 both intentId and bundleIds are already documented in the schema, including the 4-bundle cap and the extra data returned. The description adds only the comparison rationale ('for example to compare them'), which is marginal over the schema, so the baseline 3 applies.

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 ('List every quote for a shopping intent') plus scope and ordering ('cheapest first by monthly price (in USD cents)'). It also explicitly distinguishes itself from the sibling jerry_request_quotes with 'It doesn't request quotes.'

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?

Explains the conditional use of bundleIds ('Pass up to 4 bundleIds ... for example to compare them') and gives the negative exclusion that it does not fetch new quotes, implicitly routing to jerry_request_quotes. It never names that sibling or states the exact when-to-use condition, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'It doesn't change anything' largely restates structured data. The description does add useful behavioral context about what surfaces in the response (suggested items not yet on the application, a confirmation when a request is ready), but discloses nothing about permissions, freshness, or error cases.

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?

One tightly packed sentence that front-loads the core action and the read-only guarantee at the end. It is long and comma-heavy, but every clause maps to a distinct part of the return payload, so little is wasted.

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 carries the burden of explaining return values and does so by enumerating the five payload areas plus the conditional confirmation. Combined with annotations covering safety and a two-optional-parameter schema, an agent has everything needed to call and interpret it.

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 both 'full' (include every typed fact, masked) and 'intentId' (omit for most recent open intent) are already fully documented in the schema. The description's mention of the 'most recent open intent' fallback adds no meaning beyond that. Baseline 3 applies.

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 concrete verb and resource ('Read where the customer's insurance shopping stands') and then enumerates the exact payload domains returned (stage, current goal needs, application summary, suggestions, confirmation). That enumeration makes it unmistakably different from siblings like jerry_get_quotes or jerry_get_account without needing to name them.

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?

Usage is only implied through workflow language ('what the current goal still needs', 'when a request is ready, the confirmation to show'), which hints this is the status/pre-flight read. There is no explicit when-to-use statement and no named alternative or exclusion versus jerry_get_account or jerry_get_quotes.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent action. The description adds behavior beyond that: the tool only actually requests something when 'requested' comes back true, and the second call must echo the customer's exact reply. It does not mention auth needs or side effects of the request itself, so a 4 rather than 5.

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 tight sentences, purpose front-loaded, then the two-step protocol in execution order. Every sentence carries required information; only a small amount of density in the middle sentence keeps it from being a model of brevity.

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 two-step, no-output-schema tool with a nested confirmation object, the description covers the full interaction: selection call, returned status/confirmation, customer approval, and the gated 'requested' condition. It is essentially complete, with only minor gaps around what a successful request actually produces.

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 baseline is 3, and the description genuinely adds call-sequence semantics not in the schema: bundleId alone selects the quote on the first call, while token plus customerReply are only used on the confirmation call. That mapping of parameters to call stages is meaningful added value.

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: 'Get the final price of the quote the customer chose.' It is clear this operates on the chosen quote and is quote-related like its siblings, though it does not explicitly contrast itself against jerry_get_quotes or jerry_get_status, so the differentiation is inferable rather than stated.

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 very explicit call sequencing: first with bundleId only, then again with the confirmation token and the customer's exact reply after the customer agrees. This is strong when-to-use guidance for the two-step flow, but it never names an alternative tool or a when-not-to-use condition, so it stops short of a 5.

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

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

With annotations covering safety (readOnly=false, openWorld=true, non-destructive), the description goes further and discloses the two-phase confirmation contract plus response field semantics that exist nowhere in the schema: the 'requested' boolean gates the whole action, 'reason' explains refusals, and 'status' is the resulting intent. It also documents the stale_confirmation failure mode and the recovery path, which is exactly the kind of behavioral context that helps an agent act correctly.

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 description is front-loaded with the action and then the protocol, with no filler sentences. However, one clause ('Nothing is requested unless requested comes back true; reason says why not, and status is the intent after the call') is densely packed and relies on response-field names the agent has no schema for, which slightly muddies readability.

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 required-parameter write tool with a nested confirmation object and no output schema, the description adequately covers the confirmation workflow, the success gate, and one error path. It is thin on the origin of intentId, on retry/idempotency expectations, and on whether other error codes exist, which keeps it from being fully self-sufficient.

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 67% and already documents token, customerReply, and idempotencyKey, so the baseline is 3. The description's 'pass its token and their exact reply' largely repeats the schema wording for those nested fields and adds nothing about intentId (the required upstream id) or the idempotencyKey, so it does not compensate for the uncovered parameter.

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 first sentence, "Request quotes," simply restates the name and title and never says what a quote is or how this differs from siblings like jerry_get_quotes or jerry_request_final_price. The remainder of the text describes the confirmation protocol rather than the tool's purpose, so an agent still cannot tell from the description alone which quote tool to pick.

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 prerequisite sequence: the request needs the confirmation produced by the status tool, you must show its summary, obtain the customer's explicit yes, then supply the token and reply. It also gives conditional guidance for the stale_confirmation case (show the new confirmation and ask again), though it never explicitly names jerry_get_status or states when to prefer this over other quote tools.

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

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

Annotations already cover idempotency and non-destructiveness, but the description adds real behavior: an existing intent for the same products is resumed rather than duplicated, and the response carries 'the status, with rejected and clarify'. It does not discuss auth needs or side effects on the customer's saved application beyond resumption.

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?

Front-loaded with purpose and resume behavior, then parameter guidance and return value. Dense and mostly waste-free, though the final sentence about sources/permission is slightly convoluted and could be tightened.

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 complex nested-object tool with no output schema, the description covers entry point, resume semantics, the split of facts between application and the update tool, and the shape of the return (status/rejected/clarify). Only deeper edge behavior (auth, limits) is absent, which is acceptable here.

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 cross-parameter semantics the schema does not: application should carry only main fields (rest goes to updateShoppingIntentApplication), and sources/permission work together ('permission holds the customer's reply allowing it').

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 ('Start shopping for the insurance products the customer asked for') and the resume-if-open behavior. This is enough to distinguish it from jerry_request_quotes and jerry_get_quotes, though it never names a sibling explicitly.

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 clear context: start the intent here, pass known facts in application, and route any remaining fact to jerry_update_application 'right after'. It names an alternative for the overflow case. No explicit when-not condition (e.g. versus request_quotes timing), which keeps it from a 5.

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

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.

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

Goes well beyond the read-only/idempotent annotations: it explains the timeout result shape, the stop reasons (manual takeover, delayed), the nextStep field on status, and that a delayed price can be re-waited on. These are exactly the behaviors an agent needs to write a correct poll loop.

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?

Front-loads the core behavior (wait, return when ready or at timeout) and then layers the edge cases. Dense but each clause carries distinct information; only the final sentence about delayed prices is mildly redundant with the earlier 'delayed' mention.

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 compensates by describing what comes back (quote list, status, nextStep) and the terminal/non-terminal conditions. An agent has everything needed to implement a correct wait-and-retry loop.

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 baseline is 3, but the description adds meaning to timeoutSeconds by stating what happens when it elapses ('returns with the status so far') and implies the retry cadence. It does not elaborate on intentId beyond what the schema already says.

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 (wait) and precise resources (quotes, final price) and frames itself as the polling companion to jerry_request_quotes / jerry_request_final_price. An agent can distinguish it from jerry_get_quotes or jerry_get_status without opening any 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 clear when-to-use context: call after requesting quotes/final price, call again while still running, and keep waiting when the status is delayed. It does not explicitly name the immediate-return siblings (jerry_get_quotes, jerry_get_status) as the alternative for a non-blocking check, so routing is inferred rather than stated.

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