amazon-orders-mcp

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

Annotations already cover safety (readOnlyHint=true) and network reach (openWorldHint=true). The description adds genuine behavioral detail beyond them: the fan-out scope of sites checked when `site` is omitted, and the side-effect-free extra output of which site is the default.

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 sentences, both load-bearing: the first defines the check and its fallback scope, the second adds the default-site reporting. Nothing is padded and the primary action is front-loaded.

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 a single optional parameter, full schema coverage, annotations, and an output schema, the description covers everything an agent needs to invoke it correctly. The only unstated piece is what the tool does when a session is invalid, which the output schema can reasonably carry.

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 description largely restates the schema's own wording for `site` (including the fallback-to-default-semantics). It adds no new syntax or format detail beyond the schema's `amazon.de` example, 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: check with Amazon whether the user's saved sessions are still valid, and additionally report the default site. That is clearly distinct from the mutation sibling sign_in, but the description never names or contrasts an alternative tool, so it stops short of the top band.

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 explains the branching behavior well (check `site` if given, otherwise the default site plus every site with a saved session), which is effectively guidance on how to call it. But there is no explicit when-to-use/when-not-to-use framing, nor any pointer to sign_in for the case where no session exists.

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 and the description does not contradict it. The description adds that the return is the set of changeable settings plus their current values, but says nothing about auth requirements, session state, or whether values are defaults vs. user-modified. Adequate but not rich.

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 purpose, and the second sentence points to authoritative documentation for per-setting semantics. Nothing is redundant or padded.

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 need not be explained, and the annotations cover the safety profile; the description also supplies the purpose and an authoritative reference for individual settings. The remaining gap is that it does not mention any session/auth prerequisite, which is mildly relevant given the `sign_in` and `check_session` siblings.

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 zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is 4. No parameter information is missing.

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 ('Get the settings... and their values') and explicitly distinguishes this tool from its write counterpart by naming `update_config`. An agent can immediately tell this is the read half of a config read/write pair without inspecting 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?

Usage is implied rather than stated: naming `update_config` signals this is the read counterpart, so an agent can infer it should call this to inspect config before mutating. However, there is no explicit when-to-use guidance, no prerequisites (e.g., needing to sign in first, given the `sign_in`/`check_session` siblings), and no stated exclusions.

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 as a read-only, open-world operation, so the safety profile is covered. The description adds meaningful behavioral context: the tool is deprecated and its data is equivalent to `household_members` on `get_orders`.

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, front-loaded with the most important fact (“Deprecated”), followed immediately by the correct replacement. There is 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?

For a deprecated tool, the definition gives the agent everything needed to avoid it and use `get_orders` instead. Annotations cover safety, the schema covers the lone parameter, and an output schema exists, so no additional return-value explanation is required.

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 single `site` parameter has 100% schema description coverage, so the schema already explains its meaning and default. The description adds no parameter-level detail, which is acceptable given the high schema coverage.

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 identifies this tool as deprecated and names the replacement, which implies it retrieves the same family/household members as `get_orders.household_members`. It does not explicitly state a verb and resource such as “lists family members,” but the replacement mapping makes the intended behavior clear enough to distinguish it from siblings.

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 explicitly says the tool is deprecated and directs the agent to `get_orders`, satisfying the when-not-to-use and alternative-tool guidance. No further usage inference is required.

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 the safety profile is covered. The description adds useful pagination behavior (batches plus a cursor for the next batch), but says nothing about auth expectations, rate limits, or what happens when no gift cards exist.

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 sentence that front-loads the primary resource (balance) and then the secondary payload (activity batch + cursor). No filler, no 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 values need no explanation, and the pagination model is captured. What remains missing is any note about prerequisites such as an authenticated session or how site defaults are resolved, though the schema's site parameter covers that partially.

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 fully documented in the schema itself. The description restates the days-window and cursor-batch concepts without adding syntax, ranges, or edge-case guidance beyond what the schema already gives.

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 plus the two things returned: the gift card balance and a batch of activity, with cursor-based batching. That is clearly distinguishable from siblings like get_transactions or get_orders, though the description never names those alternatives 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 only implied – the reader must infer this is the tool for gift card balance/history rather than get_transactions. There is no explicit when-to-use, when-not-to-use, or named alternative, even though nearby siblings cover overlapping financial data.

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 description's added value is the variable-result behavior: the HTML summary is always present, PDFs are optional and seller/site dependent. That is genuinely useful expectation-setting. It does not cover empty results, invalid order IDs, or any auth requirement, so it stops short of full 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?

A single front-loaded sentence that names the resource first and then enumerates the returned document types. Every clause earns its place; nothing is padded.

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 values need not be explained, yet the description still frames their variability well. The only gap is behavior on failure or empty-invoice cases, which an agent would have to discover at call time.

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%, and the site parameter already explains the default-site behavior and the check_session reference. The description only restates that an Order ID is required, adding no format or usage nuance beyond the schema, 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 invoice documents') scoped to an Amazon Order ID, and enumerates the artifacts returned: Printable Order Summary HTML plus seller-issued invoice and credit-note PDFs. This clearly separates it from order-detail siblings like get_order or get_orders 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 implied by the resource itself (ask for invoices of an order), and 'mostly on EU sites' implicitly warns that PDFs may not exist on all marketplaces. But there is no explicit when-to-use vs get_order, no statement that the order must already exist, and no note about needing a session (that hint lives only in the site parameter's schema text).

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 that it returns 'full details,' which signals completeness of the result, but it does not describe error behavior or any additional operational constraints.

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 with no wasted words. It is appropriately sized for a simple lookup tool and gets directly to the point.

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 explained, and the input schema fully documents the parameters. The description is complete enough for a simple read-by-ID tool, though it could mention how it relates to sibling list/search 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 description coverage is 100%, so the schema already documents both order_id and site clearly, including the default-site behavior. The description only restates the order ID parameter and adds no further semantic detail, so the baseline score 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 states a specific verb and resource: retrieving full details for a given Amazon Order ID. It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools such as get_orders or search_orders.

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 required order ID, suggesting the tool is for looking up a single known order. However, there is no explicit guidance on when to use this instead of get_orders, search_orders, or get_tracking.

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=true and openWorldHint=true already declaring the safety profile, the description still adds real context: results come in batches, a cursor drives the next batch, and household members whose orders the account can view are included. It stops short of noting that the batch may exceed `limit` due to whole-page fetching or that `full_details` triggers extra requests, both of which remain schema-only.

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; the return-shape clause is packed but each part (history, household members, cursor) carries information. Slightly dense/run-on for a one-liner but efficient.

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 explaining return values is unnecessary; the description covers purpose and pagination adequately for a 9-param, all-optional tool. The remaining gap is routing guidance among the many sibling retrieval tools, which is the one thing an agent still has to infer.

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% with rich per-parameter documentation, so the baseline is 3. The description only gestures at the time-period and cursor semantics; precedence rules, filter values, and `family_member_id` behavior are all left to the schema, which is acceptable but adds nothing.

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 a batch of Amazon Order history) plus the returned payload shape (household members, cursor). This distinguishes it implicitly from the singular `get_order` and from `search_orders`, but it never names those siblings to make the split explicit.

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: fetching history for a time period with cursor-based paging and optional household scope. There is no statement of when to prefer this over `search_orders` or `get_order`, and no prerequisites (e.g. requiring a session) are given.

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 agent knows this is a safe, network-dependent read. The description adds that results cover 'every charge' in the history, but says nothing about pagination, ordering, or volume, so it adds only modest context beyond 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?

A single, front-loaded sentence with zero filler. The scope qualifier is stated immediately.

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 covering safety, a fully documented single parameter, and an output schema handling return values, the description covers what remains. A brief note on multi-site behavior would make it airtight, but nothing essential for correct invocation 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 description coverage is 100% and the single 'site' parameter is fully documented, including its default behavior referencing check_session. The description contributes nothing about the parameter, so baseline 3 is 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 ('Get') and a specific resource ('every charge in the Prime membership payment history'), which clearly separates it from siblings like get_gift_card_activity or get_order_history. It doesn't explicitly name the nearest alternatives (e.g. get_transactions), so it stops short of full sibling differentiation.

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 scope ('Prime membership payment history') implicitly tells an agent when this tool applies rather than a general transaction listing. However, there is no explicit when-to-use guidance and no mention of alternatives such as get_transactions for non-Prime payments.

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 agent knows this is a safe external read. The description adds that data comes from scraping the package tracking page, which is mild context, but it doesn't mention failure modes (e.g., what happens when tracking is unavailable) or return shape. With annotations carrying the safety profile, a 3 fits.

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 efficient sentence with the resource and source front-loaded. Every clause earns its place; nothing is wasted or buried.

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, annotations cover the safety and open-world profile, and parameters are fully documented in the schema. The description supplies the core purpose and source, so it is complete enough for correct invocation, with only minor room for failure-mode detail.

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 schema already explains site, order_id, and shipment_id, including the note that Amazon hides tracking links on older orders. The description adds no syntax or format detail beyond the schema, 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?

States a specific verb ('Get') and resource ('carrier and tracking number of a Shipment'), and even names the source ('package tracking page'). It is clearly distinguishable from list-type siblings like get_order_history or get_order, though it doesn't explicitly name an alternative.

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 description (retrieve tracking info for a shipment), but there is no explicit when-to-use, when-not-to-use, or named alternative among the siblings. An agent must infer that this is the tool for tracking details rather than order details.

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 usefully adds that results come in batches with a cursor for the next batch, which is real behavioral context beyond the annotations' scope. It stops short of describing ordering, freshness, or failure 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 sentence that front-loads the verb and resource and then enumerates the modes plus pagination. Dense but every clause carries information; slightly run-on but not wasteful.

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, and all five parameters are fully described in the schema. The description covers the modal selection and pagination, leaving only tool-routing against siblings unaddressed.

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% and every parameter is documented in detail there, including the cursor carry-over and the limit page-rounding semantics. The description only restates the three modes, so the baseline 3 applies with no meaningful added semantics.

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 a batch of Amazon Transaction history') plus the three access modes: day window, single order, cursor batch. It does not name any sibling tool, so an agent cannot distinguish it from get_order_history or get_order without reading further, which keeps it at 4 rather than 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 implies the three usage modes (days, order_id, cursor) but never states when to prefer this tool over get_order_history or get_order, nor any prerequisites beyond what the schema states. Usage is implied by the parameter modes rather than explained.

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. The description adds useful context by stating that it searches every year of order history and returns each matching Item with its Order number and date.

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 clearly conveys scope, search inputs, and result content without unnecessary wording.

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 full schema coverage, an output schema, and annotations covering safety and openness, the description provides enough context to call the tool correctly. It could be stronger only by explicitly situating this tool relative to its siblings.

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 parameters are already well documented. The description reinforces the query semantics but adds little beyond what the schema already provides 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?

The description gives a specific verb and resource: search Order history for Orders by product title, Order number, address, or recipient. It clearly states the search scope and result shape, though it does not explicitly distinguish itself from sibling tools like get_orders or get_order.

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 implies usage by explaining what can be searched and comparing the behavior to the search box on Your Orders. However, it gives no explicit guidance on when to use this tool versus get_orders, get_order, or other siblings.

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?

Beyond the annotations it discloses the key traits: it launches a browser window on the user's own machine, credentials never pass through the agent, the call blocks until the user finishes with a 120-second limit, and how the no-browser case behaves. That is exactly the context an agent needs for an interactive, open-world operation.

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 trigger condition comes first, followed by the mechanism, timing constraint, and error fallback, in four tight sentences with no repetition or 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?

Output schema covers return values, so the description needn't explain them; what remains (interactivity, timeout, browser selection flow, consent trigger) is fully covered. Nothing an agent needs to invoke this correctly 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 100%, so the baseline is 3. The description adds real workflow meaning for `browser` (only use it after the no-browser error, and the choice is persisted so the user is asked once), but says nothing extra about `site` beyond what the schema already documents.

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 is clearly distinguishable from siblings like check_session, which reads state rather than initiating an interactive login. An agent can identify the 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 triggers ('when they ask you to or after a tool says they aren't signed in') and a concrete fallback flow if the no-browser error occurs: ask the user, then re-call with `browser`. Both when-to-use and what-to-do-next are spelled out.

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 non-read-only, idempotent, non-destructive, closed-world, so the bar is lower; the description nonetheless adds real behavioral context the annotations cannot carry — preference changes persist, tuning changes die at server restart unless `save` is true, `warn_on_missing_required_field` degrades errors into partial data, and a `domain` change may force re-authentication verified via check_session. It stops just short of describing the response payload, which is covered by the output 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?

Front-loaded with the core action and dense with actionable detail, but it sprawls into a long run of clauses and offloads key enumeration to an external link rather than staying self-contained. Every sentence is largely load-bearing, so the penalty is mild.

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 3-parameter mutation tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what may be changed autonomously, persistence semantics, the restart caveat, the partial-data side effect, and the required follow-up check after a domain change.

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, and the description earns an increment by explaining what specific key values mean (`domain` as the default site consumed by tools lacking `site`, `browser` as sign-in target) and by elaborating the `save` trade-off beyond the schema's one-liner. It does not enumerate the full key set, deferring to an external documentation URL instead.

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?

Starts with a specific verb+resource ('Change a setting') and immediately disambiguates the two classes of setting it mutates: user preferences (domain, browser) versus tuning knobs (request_timeout, thread_pool_size). It also ties itself to the sibling get_config by saying the key comes from there, so an agent can distinguish read-config from write-config without inspecting schemas.

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 rules for both modes: preferences 'only when the user asks', tuning settings autonomously 'when calls keep failing' with concrete trigger examples (timeouts, throttling). It also supplies an alternative path ('to read another site once, pass it as `site` instead') and guidance on when to offer `save`.

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