amazon-orders-mcp

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

Annotations already flag readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful context beyond that: it contacts Amazon remotely and by default fans out across every site with a saved session rather than just one, which is non-obvious scoping behavior.

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 compact sentences, front-loaded with the primary action, with the default-scope rule immediately following. No filler, though the trailing 'Also says which site is the default' is a slightly tacked-on secondary behavior.

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 values need no explanation, there is only one optional parameter, and annotations cover safety and openness. The description supplies the remaining scope semantics, leaving nothing an agent needs 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 100% and the single optional `site` parameter is fully documented in the schema, including its default fallback. The description's clause about the default site and all saved-session sites largely restates the schema description, adding no new syntax or format detail.

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: checking whether saved Amazon sessions still work, plus a secondary effect of reporting the default site. It is clearly distinguishable from data-fetching siblings like get_orders, though it never names `sign_in` as the contrasting tool.

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?

The default behavior (check default site plus every site with a saved session) is spelled out, which implies the use case of verifying session validity. However, there is no explicit guidance on when to use this versus `sign_in`, or what it means when a session is reported as broken.

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=true and openWorldHint=true, so the safety profile is covered. The description adds a useful framing — the returned keys are exactly the mutable settings — but defers the actual meaning of each setting to an external readthedocs URL that an agent cannot reliably resolve at call time.

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 operation and its scope. The second sentence outsources essential semantics to a URL rather than stating them, which is efficient but only partially earns its place.

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 an output schema present, return-shape explanation is unnecessary, and annotations carry the read-only/open-world profile. The only meaningful gap is that the per-setting semantics an agent would need to interpret the values live behind an external link rather than in the description.

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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The description correctly implies no arguments are needed and that the payload is self-describing key/value settings.

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 (get) and resource (settings/config) and explicitly scopes the result to the subset mutable via `update_config`, which cleanly distinguishes it from the sibling with the matching write operation. An agent can tell from the description alone what it will receive and how it relates to the write counterpart.

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?

The pairing with `update_config` gives clear read-before-write context, and the zero-parameter, side-effect-free nature means there are few alternative tools an agent could confuse this with. It lacks explicit when-not-to-use guidance, but for a config getter there is little meaningful competing surface to exclude.

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=true and openWorldHint=true, so safety is covered. The description adds the genuinely useful behavioral fact that the tool is deprecated, but it does not say whether calls still succeed, when removal happens, or what happens if an agent uses it anyway. It also adds nothing about the per-site read behavior beyond the schema.

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 sentence, deprecation notice front-loaded, and the actionable replacement immediately follows. Nothing extraneous.

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 deprecated read-only tool with a single documented parameter and an output schema, the description supplies everything an agent needs to make the routing decision. The only missing piece is whether the tool still functions at all, which would matter if an agent is forced to fall back to 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 coverage is 100% and the single `site` parameter is fully documented in the schema, including the default-site fallback. The description adds no parameter guidance, so the baseline of 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?

The description names the resource indirectly through the replacement's field ('household_members lists the same members'), making clear this tool returns family/household members, and it explicitly distinguishes itself from the sibling get_orders. It never states the verb directly ('lists family members'), so the purpose is inferred rather than declared.

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 an explicit do-not-use instruction plus the exact alternative (`get_orders`) and the specific field that covers the same need (`household_members`). An agent has no ambiguity about which tool to call.

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?

readOnlyHint=true and openWorldHint=true already declare the safety profile, and the description usefully discloses the batching/cursor continuation model. It says nothing about auth/session requirements (check_session is a sibling) or rate limits, so added value is moderate.

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 front-loaded sentence that names the primary output first, then the activity batch and cursor. No filler, though the trailing cursor clause reads slightly like schema restatement.

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 shape needn't be described, and all four parameters are fully documented in the schema. The description covers purpose and pagination adequately; only session/site-selection context is left implicit.

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 days, site, limit and cursor are all documented in the schema, including the interaction where 'days' is ignored when 'cursor' is given. The description merely restates the days/cursor relationship, 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 ('Get the Amazon Gift Card balance') plus the secondary payload (activity batch) and cursor mechanic. The resource is clearly distinct from siblings like get_transactions and get_prime_payments, though no sibling is named 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?

Usage is implied by the resource ('balance and activity for a given number of days'), but there is no explicit when-to-use, when-not, or routing to alternatives such as get_transactions for payment-level history.

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 readOnlyHint and openWorldHint already declared, the description adds real context beyond annotations: the Printable Order Summary is HTML and available on every site, while invoice and credit note PDFs are seller-issued and mostly only on EU sites. That availability variance is valuable and not in structured fields; only auth/permission details are absent.

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?

A single front-loaded sentence with the resource and scope stated first, followed by the document types. The nested parentheticals are a bit dense but every clause carries information about what is returned.

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 structure needn't be explained, and annotations cover the safety profile. The description adequately conveys purpose and output variety; only explicit sibling routing guidance is missing, which is a minor gap for a simple two-parameter 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?

Schema coverage is 100% and both parameters (order_id, site) are documented there, so the schema does the heavy lifting. The description reinforces that documents are tied to a single Order ID and mentions site coverage, but adds no format or defaulting detail beyond 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 ('Get the invoice documents of a given Amazon Order ID') and enumerates exactly what is returned (Printable Order Summary HTML plus seller-issued invoice and credit note PDFs). This clearly separates it from siblings like get_order or get_transactions 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?

The purpose implies when to use it, but there is no explicit routing guidance versus get_order, get_transactions, or search_orders, and no stated prerequisites (e.g., that a session must exist). Usage is inferable rather than directed.

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=true and openWorldHint=true, so the safety profile is covered. The description adds only that the result is 'full details' (a complete record), and says nothing about failure modes for an unknown Order ID or the site-resolution behavior.

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?

A single front-loaded sentence with no filler. It is efficient, though its brevity leaves room for a short clause on scope or alternatives.

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 values need not be described, and annotations cover the read-only nature. However, for a cross-site tool whose site parameter defaults to a session-derived value, the description omits any note about site scoping or session prerequisites.

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%, and the schema itself explains both order_id and the site default that falls back to the user's default site via check_session. The description adds no meaning beyond that, so the baseline of 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 ('Get the full details for a given Amazon Order ID'), which distinguishes it from list-oriented siblings like get_orders and search_orders by implying a single-record lookup. It never names those siblings explicitly, so the differentiation relies on inference.

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 guidance on when to prefer this over get_orders, search_orders, or get_transactions, nor any mention of preconditions such as needing a valid session. The only usage signal is implicit in the required order_id.

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 and openWorldHint, so safety is covered. The description adds the batch/cursor pagination model and the household-visibility default, but these largely restate schema-level behavior rather than disclosing new operational traits such as rate limits or page size.

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?

A single front-loaded sentence that wastes no words and leads with the core action and resource. Its only minor weakness is cramming three related facts (time period, household members, cursor) into one dense clause.

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 an output schema present and annotations covering the read-only profile, the description gives enough for an agent to call the tool correctly, including the pagination model. The remaining gap is routing guidance against sibling order tools, which is minor given the schema richness.

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 nine parameters are documented in the schema itself. The description adds no syntax, format, or precedence detail (e.g., time_filter over year) beyond what the schema already provides, 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 ('Get'), resource ('Amazon Order history'), and scope ('a batch ... for a given time period') plus the cursor-based pagination and household visibility. It is clearly distinguishable from the singular get_order and from a search tool, but it never names a sibling to route against.

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?

No explicit when-to-use or when-not guidance and no mention of alternatives like search_orders or get_order. The batching/pagination framing implies list-style usage, but the agent is left to infer when this tool is preferred.

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=true and openWorldHint=true, so the safety profile is covered. The phrase "every charge" implies an exhaustive, unpaginated read, which is modest added context, but nothing is said about auth requirements, history depth/limits, or cross-site behavior.

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?

A single front-loaded sentence with zero filler. It is efficient, though its terseness leaves little structure to guide the agent.

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 and the only parameter is fully described, so most of the burden is carried by structured fields. Still, for a payment-history read tool the description doesn't clarify history scope, site behavior, or how it differs from the generic transaction tools.

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% and the single `site` parameter is fully documented in the schema, including its default and a pointer to check_session. The description adds nothing about the parameter, so 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?

The description names a specific verb ("Get") and a specific resource ("charge[s] in the Prime membership payment history"), which is narrow enough to separate it from generic siblings like get_transactions or get_orders. It does not, however, explicitly name a sibling or state the boundary between this and the general transaction tools.

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 when-to-use / when-not-to-use guidance and no mention of the alternative tools (e.g. get_transactions) that also return payment data. The use case must be inferred entirely from the resource name.

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=true and openWorldHint=true, so the safety and world-access profile is covered. The description adds that the values are scraped from the tracking page, which hints at external-dependency behavior, but says nothing about what happens when no tracking link exists — a known limitation the schema hints at but the description omits.

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?

A single tight sentence with the resource and the source of the data front-loaded. No padding or redundancy.

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 values needn't be spelled out, and annotations cover safety. What's missing is any mention of the failure/edge case (no tracking link on older orders), though the schema does surface it per-parameter, so the omission is minor.

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%, including the site default behavior and the note that older orders stop showing the tracking link. The description adds no parameter-level meaning beyond what the schema already provides, 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: retrieve carrier and tracking number for a Shipment. It also identifies the source of the data (the package tracking page), which helps an agent understand what it actually returns. It doesn't explicitly contrast with siblings like get_order, but the 'shipment tracking' scope is distinctive enough to route correctly.

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?

The phrase 'from its package tracking page' implies the tool applies when a shipment has a tracking link, but there is no explicit when-to-use vs when-to-use-something-else guidance and no named alternatives among the siblings. Usage is inferable but not directed.

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=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context about batching and cursor pagination. It does not discuss authentication or rate limits, but with annotations present this is a solid additional disclosure.

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 a single front-loaded sentence that covers the main resource, scopes, and pagination behavior with no wasted text.

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?

Given the 100% schema coverage, output schema, and annotations, the description is complete enough for correct invocation. Minor details such as site defaulting and limit page behavior are left to the schema, but the core usage modes are covered.

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 five parameters are already fully documented in the schema. The description reinforces the days/order/cursor modes but adds no format or edge-case meaning beyond what the schema provides, making the baseline 3 appropriate.

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 states a specific verb and resource: getting a batch of Amazon Transaction history. It also clarifies the two scopes, a number of days or a single order, plus cursor-based pagination. It does not explicitly differentiate itself from siblings like get_orders or search_orders, so it falls short of a 5.

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?

The description gives clear usage context: fetch by days or by a single order, and use the cursor to get the next batch. It does not state when to prefer this tool over sibling order tools, but the transaction-specific scope is reasonably clear from the description.

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 and openWorldHint, so safety is covered. The description usefully adds that the search spans all years and returns item-level results with their parent Order's number and date, but says nothing about pagination (cursor/limit behavior beyond the schema), per-site scoping, or result ordering.

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 dense sentence with no filler, front-loaded on the search scope before the returned unit. It is long but every clause carries information about matching fields or output shape.

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 an output schema, full parameter descriptions, and read-only/open-world annotations, the description only needs to establish purpose and scope, which it does (all-years, item-level results). Minor gaps around pagination and default-site behavior are already handled by the 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 the baseline is 3. The description does add a little conceptual meaning for `query` (the same matching the site's own search box performs across title, order number, and recipient/address), but repeats what the schema already documents for site, limit, and cursor.

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?

Names a specific verb (search) and resource (Order history) plus the fields matched (product title, order number, address, recipient) and the returned unit (each Item with its Order number and date). It is clearly distinguishable from get_order/get_orders in substance, but it never names those siblings, so the differentiation is inferred 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?

The 'as the search box on Your Orders does' analogy implies the case where the user has a keyword rather than an order ID, and 'every year' implies it is not date-scoped. But there is no explicit when-to-use / when-not statement and no pointer to get_orders or get_order for listing or fetching a known order.

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 annotations: it discloses that a real browser window opens on the user's machine, that credentials are entered on Amazon's own page and never seen by the tool, and that the call blocks waiting on the user with a 120-second budget. It does not say what happens on timeout/success/failure (does it return a session, throw, leave state changed), which is the one behavioral 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?

Four short sentences, front-loaded with the action and trigger, then the mechanism, then the timeout, then the error path — in the order an agent needs them. No restated title, no filler.

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 annotations declaring the mutating/open-world profile, an output schema covering return values, and full parameter documentation in the schema, the description supplies exactly the missing pieces: trigger condition, blocking/timeout behavior, credential privacy, and the retry-with-browser 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 the baseline is 3; the description earns above that by giving the `browser` parameter a conditional usage rule (only on the 'no browser' error, value is the user's choice, persisted so the user is asked once) that is not derivable from the schema text alone. `site` is only implicitly referenced via the general sign-in flow, so it stops short of a 5.

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 ('Sign the user in to Amazon') and immediately distinguishes itself from the session-checking siblings by naming the trigger 'after a tool says they aren't signed in'. An agent can identify this as the authentication action without opening the 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 explicit when-to-use conditions (user asks, or a prior tool reports no session) and an explicit when-to-use-again path: if the tool reports no browser, ask the user which to use and re-call with `browser`. The fallback is spelled out, not left to inference.

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 cover the safety profile, and the description adds substantial beyond it: persistence semantics (preference saved, tuning lasts until restart unless `save`), the side effect that `warn_on_missing_required_field` returns partial data, and the required follow-up `check_session` after changing `domain`.

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?

Dense but well-structured and front-loaded: the change-preference vs self-tune rule comes first, persistence and follow-up last. It is long, but nearly every sentence carries actionable constraint; minor trimming of the doc link sentence is possible.

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?

Given an output schema exists and annotations carry the safety profile, the description covers the remaining gaps: when to invoke, persistence, self-tune conditions, and post-change verification. An agent can act correctly without opening anything else.

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 real meaning beyond the schema: `domain` is the default site read when `site` is absent, and the `save` default differs between preference and tuning changes. This genuinely enriches parameter interpretation.

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 (change) and resource (setting/preference), and distinguishes itself from get_config by naming `key` as coming from that tool. The agent can tell this is the write counterpart to reading config.

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?

Explicitly separates when the agent may change prefs on its own (only when user asks) from when it may self-tune (calls keep failing), and routes to an alternative (pass `site` instead of switching `domain`). No inference needed.

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