Pirate Ship by Cotlet

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

Annotations already declare destructive, open-world, non-idempotent, and non-read-only behavior. The description adds important context beyond them: the operation costs real money and waits for owner approval.

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 tightly packed clauses with the core action and financial consequence front-loaded. There is no wasted language.

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?

The description covers financial cost and approval delay, which are essential for a destructive purchase tool, and annotations supply safety cues. However, with no output schema, it does not explain what the agent receives after approval or what happens while waiting.

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 batch_id, rate_ids, ship_date, label_type, and max_total_usd are already documented. The description only reinforces batch and rate selection, adding little 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: buying labels for a draft batch at chosen rates. An agent can distinguish this from creation tools such as create_batch and pricing tools such as get_rates.

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?

Makes clear this applies to a draft batch and selected rates, with schema fields pointing to create_shipment/create_batch and get_batch as sources. It gives clear context but does not explicitly state when not to use it or name alternatives in 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?

The annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds meaningful behavior beyond annotations by noting that cancellation is limited to pickups that can still be cancelled and that it 'Waits for the owner's approval.'

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 action and resource. Every clause adds relevant information about eligibility or approval.

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 low-complexity single-parameter tool with rich annotations and no output schema, the description covers purpose, eligibility, and approval behavior. It could go further by explaining what happens if the pickup is no longer cancellable or if approval is denied.

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 parameter is already documented as 'id from list_pickups.' The description adds no further parameter semantics, so the baseline score of 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 gives a specific verb and resource ('Cancels a scheduled USPS or UPS pickup') plus an eligibility condition, so the tool's purpose is clear. It does not explicitly distinguish itself from sibling tools such as schedule_pickup or list_pickups, which keeps it below 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?

Use is implied: cancel a scheduled pickup that can still be cancelled. The approval requirement is useful workflow context, but the description does not explicitly say when not to use the tool or point to list_pickups for finding the pickup_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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered elsewhere. The description adds genuinely new behavioral context: the operation is limited to draft batches and it returns the batch's recomputed rates. It still omits what happens to previously quoted rates or whether failures roll back the move.

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 with the core action and outcome front-loaded; no filler or redundant 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?

For a two-parameter destructive mutation with no output schema, the definition covers enough to attempt the call but leaves gaps: how to obtain a draft batch, where the allowed ship_dates come from, and what an error or rejected transition looks like are all unstated.

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 only 50%: ship_date is documented in the schema (must be one of the rate's ship_dates, YYYY-MM-DD) but batch_id has no description anywhere, and the description does not explain it or how to discover a batch's valid ship dates. With a coverage gap this size, the description needed to compensate and does not.

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 ('Moves a draft batch to another ship date') plus the side effect (recomputed rates), so an agent can tell it apart from rename_batch, create_batch, or get_rates. It does not explicitly name an alternative, but the 'draft batch' scoping 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 'draft batch' implies a precondition (only draft batches qualify), which is useful implied usage guidance. However, there is no explicit when-to-use vs when-not statement, no mention of what to do for a non-draft batch, and no pointer to siblings for obtaining a batch or rates.

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 the safety profile (readOnly, non-destructive), and the description adds real context beyond them: it is free, it requires the user's Cotlet API key or sign-in, and it enumerates the status fields returned. Auth and cost disclosure are exactly the kind of extra behavioral facts that earn credit here; transport/pagination is the only 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?

The return content is front-loaded in the first sentence, with cost and auth as short trailing clauses. It is dense but not padded; every clause (statuses, cost, auth) conveys distinct information.

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 read-only tool with annotations and no output schema, the description adequately describes what comes back (per-app access and browser-account state plus the required user step and console link) and states auth needs. The missing piece is any pointer to the related request/browser tools, but nothing essential to calling it correctly is 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?

With 100% schema description coverage and a single optional 'app' filter, the schema carries parameter meaning. The description never references the filter, so it adds nothing over the structured field; 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 clearly states the resource (the apps in the user's workspace) and what is reported per app: access status, Cloud Browser account state, and next step. It does not name or distinguish itself from the closest sibling, cotlet_request_apps, so an agent must infer which one to call when it wants to request access.

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?

'Free. Needs the user's Cotlet API key or sign-in.' gives a prerequisite but not a when-to-use rule. There is no explicit routing to cotlet_request_apps (for requesting an app) or to the cotlet_browser_* tools (for acting once an app is connected), so usage is only implied.

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 destructiveHint=false, so the safety profile is covered. The description still adds non-obvious context beyond them: that the call costs nothing ('Free') and that authentication is required, which are genuine behavioral facts an agent needs.

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 short sentences with the main purpose front-loaded and no padding. The 'Free.' fragment is terse but conveys a meaningful fact efficiently.

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 zero-parameter, read-only lookup with no output schema, the description covers what it returns, what it costs, and what auth it needs. Only minor gaps remain (e.g., currency/format of the balance), which is acceptable at this complexity.

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 the baseline is 4; there is nothing for the description to clarify and it does not attempt to misdescribe inputs.

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 the specific resource returned: the user's current credit balance. The verb ('get'/'retrieve') is implied rather than stated, and it doesn't differentiate from cotlet_whoami or other cotlet_* account tools by name, but the resource is unambiguous.

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?

'Free' signals there is no cost/credit consumption to calling it, and the auth prerequisite ('needs the user's Cotlet API key or sign-in') tells the agent what is required before calling. There is no explicit when-to-use vs. alternative guidance, leaving usage implied.

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 destructive/openWorld/non-idempotent annotations, it discloses that the tool acts as the user on the site, that certain action classes (payment, account/sign-in) are blocked, what is returned after the click, and the billing model with a 3-minute idle expiry. These are exactly the operational constraints an agent cannot infer from structured fields.

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 sentences, all load-bearing: action, side-effect return, refusal policy, and cost/lifetime. The final sentence packs two distinct facts (credit cost and 3-minute idle expiry) into one long clause, which slightly hurts 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 covers the return value (URL and title), the side-effect profile, refusal conditions, and the session/cost lifecycle. An agent has everything needed to decide and invoke correctly.

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 parameter is fully documented in the schema (100% coverage), and the description's 'by its number in the page's element list' merely restates the schema text. No extra guidance on how to obtain valid element numbers, 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?

States a specific verb (clicks) and resource (a link, button or other element of the current page in the user's browser) plus the addressing mechanism (its number in the element list) and the return (URL and title). This clearly separates it from siblings like cotlet_browser_press, cotlet_browser_type, cotlet_browser_select and cotlet_browser_navigate 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?

Gives explicit exclusion rules: pay/buy buttons and buttons on account or sign-in pages are refused, which tells the agent when this call will fail. It also frames the cost/session lifecycle (credits per started minute, session ends 3 minutes after the last call), but it never explicitly routes the agent among alternatives such as press vs select vs type for a given widget.

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?

Adds substantial detail beyond annotations: cookies are retained, the browser sleeps, billing stops, and the tool returns session minutes and credits. This is consistent with destructiveHint=false because no cookies or session history are described as destroyed.

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 states the action, side effects, and return value without filler. Every clause contributes useful invocation context.

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 zero-parameter close tool with no output schema, the description is largely complete: it explains side effects and return values and aligns with the annotations. The only gap is the undefined `app` reference, which slightly undermines clarity.

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 schema has zero parameters and full coverage, which normally supports a baseline of 4. However, the description references `app` even though no such parameter exists in the input schema, creating a small ambiguity about how app scope is selected.

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: ending the browser session on Cotlet, with app-specific scope noted. This distinguishes it from siblings like cotlet_browser_open, cotlet_browser_connect, and cotlet_browser_sessions without needing their 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?

The description implies when to use it by explaining that the per-minute charge stops, but it does not explicitly contrast this with cotlet_browser_sessions or explain when not to close a session. Usage is inferable rather than stated.

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 past the annotations: it discloses that only one tab exists, that new tabs are refused, that the user watches live, that credits accrue per started minute of an open connection, and that a Cotlet API key or sign-in is required. These are exactly the operational facts an agent needs before opening a metered, user-visible session, and nothing contradicts the declared hints.

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 tight sentences, front-loaded with the action and return value, then constraints, then cost and auth. Minor awkwardness in "It works in one open tab, the app's:" but no sentence 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?

Covers return value, auth, cost, and tab restrictions, which is strong for a tool with no output schema. The gap is the missing link between "one app" and the zero-parameter schema: an agent is never told how the target app is chosen, nor that cotlet_browser_close should be called to stop the metered session.

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 the 4 baseline applies. The description adds the useful note that the browser is tied to "one app" and signed in as the user, which is context the empty schema cannot convey, though it never explains how that app is determined.

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?

A specific verb and resource ("Wakes the user's Cloud Browser") plus a concrete return value (cdp_url) makes the operation unambiguous. It distinguishes itself from interaction siblings like cotlet_browser_click/navigate by saying it hands over a CDP WebSocket, but it never names the closest alternative (cotlet_browser_open) so the boundary 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?

"Gives a CDP client full control" implies the use case (you need raw CDP rather than the click/type/navigate helpers), and the auth/cost constraints hint at prerequisites. However, there is no explicit when-to-use versus cotlet_browser_open or cotlet_browser_sessions, and no when-not-to-use guidance despite a crowded browser sibling family.

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 the read-only, non-destructive, open-world profile, so the description is not obligated to repeat that. What it adds is genuinely useful and non-obvious: billing behavior (every started minute costs credits) and session lifetime (ends on close or 3 minutes after the last call), which no annotation conveys.

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 short sentences, each carrying distinct information: what it does, the app-browser scoping rule, and the cost/session-lifetime caveat. No filler and the core 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?

There is no output schema, and the description compensates by stating it returns the resulting URL and title. Session termination and credit cost are covered. Only failure behavior (invalid URL, non-public address, cross-app access) and the distinction from cotlet_browser_open are left unstated.

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?

With a single parameter at 100% schema description coverage, the schema already fully documents the url format and its app-browser meaning. The description restates the http/https constraint but adds no format, validation, or edge-case 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?

The description gives a concrete verb and resource ("Opens a public http or https address in the user's browser on Cotlet") and notes the return value (final URL and title). It clarifies the app-scoped variant ("An app's browser opens only that app's pages"), though it never distinguishes itself from the closely named sibling cotlet_browser_open, leaving some 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?

It implies usage by constraining the address to public http/https and explaining the app-browser scope, but never states when to pick this over cotlet_browser_open, cotlet_browser_connect, or cotlet_browser_sessions. The agent must infer the routing from name similarity alone.

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?

The annotations only declare read-only, open-world, non-idempotent and non-destructive. Beyond them, the description discloses that the user watches every step live, that every started minute costs credits, and that the session ends on close or three minutes after the last call. That billing and expiry model is exactly the context an agent needs before invoking the tool.

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 dense sentences with no filler, and the core identification of what is being opened comes first. The lifecycle/cost details are clustered at the end, which reads a bit run-on but is still well-ordered.

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?

There is no output schema, so the description appropriately states that the page URL and title are returned, and it covers cost and session expiry. The remaining gaps are the error behavior and routing to related session 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%, so the single url parameter is fully documented in the schema, and the baseline is 3. The description does explain the two browsing contexts (the user's signed-in browser versus an app's browser), but it refers to an `app` parameter that does not exist in the schema, which can confuse an agent about what it can pass.

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 and resource: it wakes the user's own hosted Chrome on Cotlet and opens a URL. That is clear and concrete. However, it never contrasts itself with siblings like cotlet_browser_connect or cotlet_browser_navigate, which an agent must distinguish when starting a browsing session.

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 agent can infer that this is the entry point for starting a browsing session, and the closing sentence hints at session lifecycle. But there is no explicit 'use this when' versus connect/navigate, nor any guidance on whether to open the browser before calling click/type/read.

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 (destructive, openWorld, non-idempotent) by disclosing a safety guardrail (Enter refused on account pages), the return payload (URL and title after the press), and the billing/session model (every started minute costs credits, session ends on close or 3 minutes after the last call). Those are exactly the non-obvious traits an agent needs before deciding to act.

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 front-loaded sentences: action and scope first, key semantics second, then constraints and side effects. No filler, and the credit/session warning is placed after the operational content where it belongs.

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 one enum-constrained parameter and no output schema, the description still names the return value, the refusal case, and the session lifetime. Nothing material 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 coverage is 100% with a fully enumerated key list, so the baseline is 3; the description adds real meaning by mapping keys to intents (Tab to next field, Enter to send, arrows for suggestion lists), which the bare enum does not convey.

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 ('Presses one key on the current page in the user's browser on Cotlet') and scopes it to the focused element. The concrete key examples (Tab, Enter, Escape, arrows) separate it cleanly from cotlet_browser_type and cotlet_browser_select without needing their 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 concrete when-to-use guidance per key ('Tab to the next field, Enter to send, Escape to close a dialog or pop-up') plus an explicit refusal rule ('Enter on account pages is refused'). It never explicitly says when to prefer cotlet_browser_type or cotlet_browser_select instead, so it stops short of full alternative routing.

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?

Adds significant behavioral context beyond annotations: limits (20,000 chars), exclusions (field values, cookies, storage), scroll-relative start on long pages, and cost model (credits per started minute, session ends after 3 minutes idle or on close). No contradiction with readOnly/idempotent hints.

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 sentences, front-loaded with what the tool returns, then limits, scroll behavior, and cost. Every sentence earns its place and no waste.

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, but the description fully explains return values (text, numbered list) and key operational details (size limits, exclusions, cost, session lifetime). Complete for a 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?

Zero parameters, so baseline is 4. The description need not explain parameter semantics; it correctly focuses on return behavior and constraints 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?

States a specific verb ('Returns') and resource ('current page of the user's browser on Cotlet'), and enumerates what is returned (readable text, numbered list of links/buttons/fields). This clearly distinguishes it from sibling browser tools like screenshot or click.

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?

Implies usage (read the page's text and interactive elements), but provides no explicit when-to-use guidance or alternatives among the many browser tools (e.g., screenshot, navigate). An agent must infer the appropriate context.

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 (all of which it is consistent with), the description discloses two things an agent could not otherwise know: cost ('Every started minute of the session costs credits') and session lifecycle ('ends when closed or 3 minutes after the last call in that browser'). For a metered, session-bound tool this is exactly the right kind of added context.

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 dense sentences; the core output is front-loaded before the cost/lifecycle caveats. The colon-introduced list ('boards, canvases and layouts') is slightly awkward but each clause carries real information rather than restating 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?

With no output schema and no parameters, the burden falls on the description, and it covers output form, cost, and timeout. It does not state prerequisites (an active browser session) or what happens when no browser is connected, which is the main remaining gap for a session-scoped 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?

There are zero parameters, so no parameter semantics are required — the baseline for a parameterless tool applies. The description correctly adds nothing spurious about inputs.

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 and resource ('Returns a JPEG image of the visible part of the current page') and even flags the return payload as URL + title. The clause 'boards, canvases and layouts that the page text does not show' indirectly distinguishes it from cotlet_browser_read, but it never names that sibling, 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 phrase 'that the page text does not show' gives a usable heuristic for choosing screenshots over the text-reading sibling. What is missing is an explicit instruction such as 'use cotlet_browser_read for text' or a note that a browser session must already be connected via cotlet_browser_open/connect.

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 past the annotations by disclosing the cost model ('every started minute of the session costs credits'), the session lifecycle ('ends when closed or 3 minutes after the last call'), the implicit lazy-load side effect, and the exact return payload (URL, title, at_top, at_bottom). These are operational facts an agent cannot get from readOnly/idempotent hints alone.

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 but front-loaded paragraph: mode enumeration first, then side effect/return, then billing. Every sentence carries information, though the billing clause is appended to a long sentence and could have been separated 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?

No output schema exists, and the description compensates by naming the returned fields and their meaning (at_top, at_bottom). Combined with the three-mode explanation and session-cost warning, an agent has everything needed to call this correctly on the first attempt.

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 cross-parameter meaning the schema does not, namely that `screens` describes distance for the down/up modes while `element` selects the scroll-until-visible mode. It restates the 0.8 default and the direction set, which is mildly redundant with 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?

Starts with a specific verb+resource ('Scrolls the current page in the user's browser') and enumerates the three distinct modes of operation (by screens, to top/bottom, until element). An agent can distinguish it from siblings like cotlet_browser_read or cotlet_browser_navigate 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 phrase 'Content that loads on scroll appears, and the next read lists it' effectively tells the agent when to use this tool (to reach lazy-loaded content, then call cotlet_browser_read). It does not explicitly name a when-not condition or state that element-based scrolling supersedes the screens/direction parameters, so the routing is clear but not exhaustive.

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 only flag the operation as destructive, non-idempotent, and open-world; the description goes well beyond that by disclosing the return payload (URL and title after selection), the refusal of card fields and account pages, and the credit/session economics including the 3-minute inactivity timeout. That is exactly the kind of context an agent needs before spending money and mutating page state.

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 core action is front-loaded in the first clause and each following sentence carries distinct information (return values, refusals, billing). It is dense rather than wasteful, though the session-cost sentence is boilerplate that inflates the definition relative to the two-parameter operation.

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 mutation tool with no output schema, the description covers what is returned, what is blocked, and the session lifecycle cost, which is nearly everything an agent needs. The one remaining gap is what happens on an unsuccessful match (error vs. silent no-op), which matters given destructiveHint=true.

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?

With 100% schema coverage, the schema already documents both parameters, so the baseline is 3. The description does add a little meaning by clarifying that 'option' can be matched by the label as the list renders it or by its value, but it says nothing about partial matching, case sensitivity, or failure behavior for an unmatched label.

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 ('Chooses an option') and resource ('drop-down list on the current page') and scopes it to Cotlet's browser session, which cleanly separates it from navigation or screenshot siblings. It does not explicitly name the neighboring tools (click/type/read) that an agent might confuse with selection, so it stops just short of full 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?

'On the current page' establishes the precondition that a page must already be loaded, and 'Card fields and account pages are refused' gives an explicit when-not boundary. It stops short of a 5 because it never names the alternative action (e.g., use click or type when the element is not a select).

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?

The description adds meaningful behavior beyond the annotations: it discloses the authentication requirement, that costs and minutes are reported, that only still-valid cdp_url links are returned, and that closing revokes unused links. This is consistent with destructiveHint=true and readOnlyHint=false.

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 compact and front-loads the main behavior, with the close behavior following immediately. The phrase 'of one app or of all' is unnecessary and confusing given the one-parameter schema, but overall there is little waste.

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 low-complexity tool with rich annotations and no output schema, the description covers the main return data and authentication. The unresolved 'one app or all' scope is a real gap because the schema cannot express app selection, leaving the agent unsure how to interpret that claim.

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 close parameter is already documented. The description adds that close=true ends connections and takes back unused links, but it also mentions 'of one app or of all' even though the schema exposes no app-targeting parameter, which creates ambiguity rather than clarity.

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 clearly identifies the resource as Cloud Browser sessions and explains that it exposes cost, minutes, and valid cdp_url links, with an optional close behavior. It does not explicitly distinguish itself from sibling tools such as cotlet_browser_close or cotlet_browser_connect, and the opening verb 'Open' is slightly ambiguous.

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 useful condition for the close parameter ('With close: true') and states the authentication prerequisite. However, it does not explain when to use this tool versus cotlet_browser_close or other browser siblings, and the 'of one app or of all' scope is not actionable through the schema.

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 the return value (URL and title after typing), a security refusal policy for sensitive fields and sign-in pages, a credit cost per started minute, and session lifetime ('ends when closed or 3 minutes after the last call'). The mutation/destructive framing is consistent with destructiveHint=true and openWorldHint=true.

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 action and addressing scheme, then layers behaviour, refusals and cost in three tight clauses. The billing sentence is slightly off-topic for a typing tool but is genuinely useful context, so only a minor deduction.

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 destructive, open-world browser mutation with no output schema, the description covers the action, how elements are addressed, the return value, safety refusals, and session/cost lifecycle — everything an agent needs to call it without surprises.

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 three parameters are already documented, and the description largely restates them (`submit` presses Enter, element numbering from the page's element list). Baseline 3 is appropriate; it adds no constraints or gotchas 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 ('types text into a field of the current page') plus the addressing scheme ('by the field's number in the page's element list'), which cleanly separates it from siblings like cotlet_browser_press, cotlet_browser_select and cotlet_browser_click.

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 via the `submit` note ('presses Enter after typing, e.g. to search') and an explicit when-not: password, card, one-time code fields and sign-in pages are refused and left to the user. It does not name the sibling to use instead for keystrokes like Tab/Escape, so it stops just short of 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 flag destructive, open-world, non-idempotent behavior, and the description adds real value on top: accepted file source shapes, the 10-file / 20 MB limits, the returned URL and title, and the per-minute credit cost with the 3-minute idle timeout. It does not say what happens on partial failure or whether existing field content is replaced, which keeps it short of 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?

Two dense sentences, purpose and input shape front-loaded, with cost/session policy last. Every clause carries information, though the credit-and-timeout clause sits somewhat awkwardly in a tool-purpose description.

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 states the return value (URL and title), and it covers input forms and limits. The main gap is the missing reference to how a browser session must already exist and how this differs from cotlet_upload_file.

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 restates the url/file_id alternatives and the element-number meaning that the schema already documents, adding limits (10 files, 20 MB) but no genuinely new semantics such as how the element list is obtained or what happens if element is not a file input.

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 ('puts files into a file field of the current page in the user's browser'), plus the targeting mechanism (element number). It distinguishes itself from generic upload behavior by naming the browser/session context, but it never contrasts itself with the sibling cotlet_upload_file, which an agent could easily confuse it with.

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 browser-session framing and the note that the session ends on close or 3 minutes after the last call imply when this tool fits, but there is no explicit 'use this instead of cotlet_upload_file when...' guidance, and no prerequisites (e.g. needing an open browser session from cotlet_browser_open/connect) are stated.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes the status vocabulary and the polling context, but says nothing about behavior for an unknown or expired call_id, retention window, or whether repeated polling is rate-limited.

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 resource and key, with the status set inlined rather than padded into separate sentences. The trailing 'answered with status pending or running' is slightly awkward phrasing but earns its place as scoping information.

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 one-parameter read tool with no output schema, the description supplies the crucial return-value information (the full status enum) that the structured fields omit. Only minor gaps remain, such as what accompanies the status in the response.

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?

There is a single required parameter with 100% schema description coverage, so the schema already carries the semantics. The description's 'by its call_id' merely restates the schema and adds no format or sourcing detail (e.g. where the call_id came from).

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 resource (an earlier Cotlet call) and a specific retrieval (its status, keyed by call_id), and enumerates every terminal and intermediate state so the agent knows exactly what it will get back. No sibling tool overlaps this resource, so the lack of an explicit 'not for X' does not create 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?

The closing clause scopes it to calls whose prior response was pending or running, which effectively tells the agent this is a polling tool rather than a general history lookup. It stops short of naming an alternative or saying what to do once a terminal status is reached.

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-readonly, non-destructive, non-idempotent write, so the description only needs to add context. It does: it states where the report goes, that error text and call_id are attached when available, that secrets are never included, and that an API key or sign-in is required. It does not mention what happens on duplicate submissions, consistent with idempotentHint=false but not explained.

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 dense sentences, front-loaded with the action and its goal, then the trigger scenarios, then the content and auth constraints. No filler and nothing repeated from the title or annotations.

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 mutation tool with no output schema, the description covers purpose, triggers, attached payload, secret handling and authentication, which is enough to call it correctly. It omits what the caller receives back or whether filing duplicates creates separate reports, a minor gap for a write 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%, so enum values for `kind` and field meanings for `tool`, `app` and `call_id` are already documented in the schema. The description adds only marginal meaning, clarifying that call_id and error text are picked up automatically when present, which is the baseline expectation given full schema documentation.

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 and resource ('Sends a report straight to the Cotlet team') and enumerates the concrete situations it covers: failed or wrong-data tools, blockers, missing tools/fields/apps. It stops short of explicitly distinguishing itself from the sibling cotlet_request_apps, which plausibly overlaps with the 'app the task needed and Cotlet lacks' case.

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?

Clear contextual triggers are given ('failed or returned wrong data', 'an error you could not get past', 'needed and Cotlet lacks'), which is enough for an agent to decide when to file a report. It offers no explicit exclusion or pointer to cotlet_request_apps / cotlet_get_call, so edge-case routing is 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?

Adds substantial behavior beyond the annotations: a live app is granted immediately, other requests go to the Cotlet team with a 72-hour response window, the operation is free, and authentication via Cotlet API key or sign-in is required. The mutation-like but non-destructive nature is consistent with 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?

Three tight sentences with the core action front-loaded, followed by outcome behavior, slug source, cost, and authentication. No wasted words.

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 simple one-parameter request tool with no output schema, the description provides everything needed to call it correctly: what it does, how outcomes differ, where to get valid slugs, and what credentials are 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?

Schema coverage is 100%, so the schema already documents the apps parameter and slug examples. The description adds useful context by pointing to https://cotlet.dev/api/v1/apps as the canonical slug list, though it does not mention the maxItems limit.

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: request access to apps for the user's workspace. It distinguishes this from informational siblings like cotlet_apps and cotlet_balance by describing an action that submits an access request and explains the two possible outcomes.

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 clearly frames the tool as the programmatic equivalent of 'Request access' in the console, which implies when to use it. It does not explicitly say to use cotlet_apps first to discover slugs, so a small inference remains.

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?

The description adds substantial behavioral detail beyond the annotations: it returns a one-time upload_url and file_id, requires an HTTP PUT to upload_url, enforces a 25 MB limit, states the URL works only once, and notes the Cotlet API key/sign-in requirement. These details are consistent with the non-read-only, non-destructive annotation profile and materially help the agent understand the workflow.

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 most important fact—what is returned and how it is used—is front-loaded in the first sentence. The remaining sentences cover upload method, size limit, one-time behavior, and auth without wasted words.

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?

There is no output schema, and the description fully explains the return values, the upload workflow, the file size constraint, one-time URL behavior, and authentication needs. An agent has enough information to invoke and chain this tool correctly.

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%, with both name and content_type documented with examples in the schema itself. The description does not add parameter-specific syntax or constraints beyond that, so the baseline score of 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 and resource: it returns a one-time upload_url and file_id for a local file. It also clarifies the intended use cases (an image for a post, an attachment), but it does not explicitly distinguish this helper from sibling tools such as cotlet_browser_upload.

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: call this to obtain upload_url and file_id, PUT the file to upload_url, then pass file_id to any argument that accepts a file. It does not name when-not-to-use cases or alternative tools, so it falls short of the top score.

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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds genuine value beyond them: it declares the call is credit-free ('Free') and that authentication via the user's Cotlet API key or sign-in is required, which matters for failure handling. It does not say what shape/format the response takes, but the field list largely compensates.

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: the first front-loads the substantive return contents, the second carries the cost and auth facts. No filler, no restatement of the title, and every clause 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?

There is no output schema, so the description must carry the return contract — and it does, enumerating each field the agent will receive. Combined with the required-auth note, an agent has enough to call it correctly. Only minor gaps remain, such as how failures look when the key is missing or what access-status values are possible.

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 and the baseline of 4 applies. Nothing in the text conflicts with the empty 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?

The description names a concrete resource — the Cotlet account identity for this connection — and enumerates exactly what comes back (email, workspace, access status, API key/OAuth client scope, callable apps, credit balance). That is far more specific than the bare 'who am I' title. It stops short of explicitly distinguishing itself from siblings like cotlet_balance and cotlet_apps, which overlap on the balance and app-list portions of the response.

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 context is implied rather than stated: an agent can infer this is the pre-flight identity/permission check, and 'Needs the user's Cotlet API key or sign-in' plus 'Free' tells it the prerequisites and that no credits are consumed. However there is no explicit 'call this before cotlet_apps or cotlet_balance to verify access' routing, and no stated conditions under which this tool should be skipped.

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 destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful context by calling the result an 'unpaid draft' — i.e., nothing is charged and further action is required — but it says nothing about limits, whether the draft persists, or what happens on failure.

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?

It is short, but shortness here comes from under-specification rather than economy — it reads as a fragment ('Unpaid draft batch for many packages with the rates of each rate group') with no subject or clear predicate, and the key follow-up action is buried after a semicolon.

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 an 11-parameter, non-idempotent, destructive creation tool with no output schema and low schema coverage, the description leaves most of the calling contract unaddressed: the nested shipments array (1–500 items), override semantics, and defaulting behavior (ship_from_id, package_preset_id) are all 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 description coverage is only 36% across 11 parameters, so the description needs to compensate and does not. Its only parameter-adjacent phrase, 'rates of each rate group', is ambiguous and does not map onto any field; per-shipment overrides, package_preset_id precedence, and packaging options go unexplained.

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 the resource and state precisely — an unpaid draft batch covering many packages — and the trailing 'buy it with buy_label' implicitly separates this from create_batch_from_orders and create_shipment. The telegraphic phrasing ('many packages', 'rates of each rate group') is slightly opaque, and no sibling is named outright, 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?

'buy it with buy_label' gives the follow-on step, which is real workflow guidance. But there is no statement of when to prefer this over create_batch_from_orders (orders vs. arbitrary shipments) or create_shipment (single), and no prerequisites such as account/balance requirements are mentioned.

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 destructiveHint=true, openWorldHint=true and non-idempotent, so the safety profile is carried for the description. The line 'nothing is bought' usefully clarifies no money moves despite the destructive hint, but it doesn't say what happens to the source orders or how partial failures are handled — the key risk for a destructive, non-idempotent tool.

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 compact sentence with the core action front-loaded and the 'nothing is bought' qualifier placed where it lands hardest. Zero wasted words.

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 five parameters, no output schema and a destructive annotation, the description should say what the agent gets back and what happens to the consumed orders. It covers the action and the no-purchase guarantee but leaves the outcome and side effects to inference.

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 all five parameters including the companion-tool pointers (list_import_orders, list_saved_packages) are already documented. The description only echoes the 'one saved package' constraint and adds no format or edge-case 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: turns orders into a batch of shipments. It also pins down the 'one saved package' scope, which implicitly separates it from create_batch, though it never names that 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?

'nothing is bought' is a useful exclusion that steers agents away from buy_label territory, and the package/order framing implies the pre-label workflow. But it never names alternatives (create_batch, create_shipment) or states prerequisites like having synced orders first.

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=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is carried structurally. The description adds useful context about what the template is for, but says nothing about side effects an agent would care about — e.g., whether setting default=true displaces an existing default template, or whether the sender email must be pre-verified.

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 verb and resource come first and the use-case qualifier follows. Efficient, though it could have spent the same length on a more decision-relevant fact.

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?

A seven-parameter creation tool with no output schema, given only one sentence. It does not say what comes back (e.g., a template ID), whether the new template becomes active for new labels, or any constraints beyond what the schema enforces — significant gaps for a mutation with destructiveHint=true.

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 71%: html placeholders, name, default, bcc_email, and sender_email are all documented in the schema, and the description adds nothing further. Two required parameters (subject, sender_name) are undocumented but self-evident by name, so the schema still carries most of the semantic load — a baseline 3.

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?

"Adds a tracking email template" gives a specific verb plus resource, and the trailing clause explains what the resource is used for (recipient tracking-link emails). This distinguishes it implicitly from update_email_template, delete_email_template, and list_email_templates, though none are named.

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 use this versus update_email_template, nor on prerequisites such as needing tracking email settings configured or a verified sender. The only context is the purpose clause, leaving the agent to infer whether it should create a new template or modify an existing one.

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 that this is a non-read-only, non-idempotent, destructive, open-world operation. The description adds only the generic purpose and does not mention duplicate-title behavior, side effects, permissions, or what "destructive" means for a saved package.

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 concise, though its brevity contributes to gaps handled in other dimensions.

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 13-parameter mutation tool with low schema description coverage and no output schema, the description is too thin. It does not provide enough parameter or behavioral context for an agent to invoke it confidently.

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 low (38%), so the description needs to compensate. It only broadly groups parameters into "type, size, weight, extra services" and does not explain required fields like title and packaging, the default/irregular flags, or most optional services.

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 ("Saves a package") and enumerates the main dimensions it captures, so the basic purpose is clear. It does not explicitly distinguish itself from siblings such as update_saved_package or list_saved_packages, leaving some 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?

It only implies that the tool is for saving reusable package settings ("for reuse on labels"). It gives no guidance on when to use this versus update_saved_package, list_saved_packages, or creating a shipment directly.

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 destructiveHint=true, non-idempotent, openWorld, so the description's only added context is that the result is a PDF link. It never explains what the 'destructive' aspect means here — e.g., whether generating a SCAN form finalizes or consumes a batch/ship date, or whether it can be regenerated. For a destructive, non-idempotent tool that is the single most important thing an agent needs.

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 compact sentence with the resource and output front-loaded and no filler. It is arguably slightly under-specified rather than too long, which is a completeness issue rather than a conciseness one.

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?

All parameters are optional and fully documented in the schema, and the description covers the return type (PDF link), so nothing critical is missing. However, for a destructive, non-idempotent generation tool with no output schema, the description should say what generating a form does to the underlying batch/labels and whether it is repeatable.

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 three parameters including the precedence rule (batch_id ignores ship_date) are already documented. The description restates the ship_date scoping but adds no format, default, or interaction detail beyond the schema, 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?

Identifies a specific, recognizable resource (USPS End of Day SCAN Form) and states the output form (a PDF link), which lets an agent tell it apart from the read-only sibling list_scan_forms. The generative verb is only implied by the title rather than stated in the description itself, so it is clear but not perfect.

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 explicit when-to-use statement, no prerequisites, and no mention of the obvious alternative list_scan_forms. The only guidance is embedded in the schema ('only the labels of this batch', 'default: today'), which the description does not reinforce or contextualize.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risk profile is covered. The description adds the US-only constraint and the optional return-address behavior, but says nothing about whether the new address becomes the default or what happens on duplicate titles.

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 no filler; the core action and the optional variant are 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?

For a non-idempotent mutation with nested address objects and no output schema, the description should clarify return behavior (ID? created object?) and address validation rules. The safety profile is covered by annotations, so this is adequate but not complete.

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 the schema already documents the return_address default ('Default: the origin') as well as most field descriptions. The description's mention of an optional separate return address mirrors what the schema states, adding marginal new meaning.

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 ('Adds a US Ship From Address') with a scope qualifier (US) and the return-address option. It's clearly distinct from list/update/delete siblings by name, though the description never names them 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?

No guidance on when to use this versus update_ship_from_address, list_ship_from_addresses, or set_default_ship_from_address, and no prerequisites (e.g., whether an address must be validated first) are given. The agent must infer usage from the name alone.

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, destructive, open-world, and non-idempotent behavior. The description adds useful lifecycle context beyond that: the label is unpaid, includes every rate, and must be purchased via buy_label. It does not explain destructive or idempotency details, but with annotations covering the safety profile this is a meaningful addition.

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?

It is one compact sentence, front-loaded with the key state (unpaid draft) and the next action, with no filler. The telegraphic fragment style is slightly less polished than a full sentence, but every word 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?

For a 13-parameter creation tool with a nested required recipient object and no output schema, the description is far too thin. It omits the required address structure, package dimensions and weight, packaging, signature, insurance, and address_correction behavior.

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 only 38% across 13 parameters, including a nested recipient object, dimensions, packaging, signature, insurance, and address_correction. The description mentions none of these parameter semantics, so it does not compensate for the low 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 phrase 'Unpaid draft label for one package with every rate' identifies the resource and scope: a draft label for a single package including all rates. Naming buy_label distinguishes this from the purchase step, though the creation verb is implicit 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?

It explicitly routes the purchase step to buy_label, giving a clear create-draft-then-buy workflow. It does not state exclusions, such as when to use get_rates instead, or other prerequisites, so it falls 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 destructiveHint=true, openWorldHint=true and non-idempotent, so the safety profile is covered. The description adds real behavioral value beyond that: only unpaid drafts are deletable, and the operation waits for owner approval, meaning the call may not complete synchronously.

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, zero filler, with the destructive eligibility constraint front-loaded ahead of the approval caveat.

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 one-parameter destructive tool with full annotation coverage, the description supplies the two things annotations can't: eligibility scope and the approval wait. Remaining gaps (what happens to shipments within a deleted batch, error behavior) are 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 coverage is 0% and the single required parameter batch_id is undocumented in both schema and description. Its purpose is largely self-evident from the name, but the description's mention of 'or single shipment' creates ambiguity about whether batch_id can also reference a shipment, which is not resolved anywhere.

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 (Deletes) and resource (unpaid draft batch or single shipment), which lets an agent distinguish it from refund_batch and cancel_pickup by eligibility. It stops short of naming a sibling alternative for deleting paid/processed batches.

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 eligibility constraint ('unpaid draft') implies when the tool applies, and 'waits for the owner's approval' hints at an asynchronous flow. It never states what to use instead when the batch is not an unpaid draft, leaving the agent to infer the refund_batch path.

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 destructiveHint=true and idempotentHint=false, so the safety profile is carried by structured data. The description adds nothing beyond that: no statement that deletion is permanent, no indication of what happens to templates currently referenced by active tracking settings, and no error/permission 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?

One short, front-loaded sentence with no filler, but it is terse to the point of under-specification rather than genuinely 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?

For a destructive, non-idempotent mutation with no output schema, the description says nothing about consequences, irreversibility, or failure modes. An agent knows what the tool touches but not what it risks.

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 parameter is documented in-schema with a useful provenance note ('id from list_email_templates'). The description contributes no additional parameter meaning, 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 ('Removes') and resource ('tracking email template'), which cleanly separates it from create_email_template, update_email_template, and list_email_templates. It does not explicitly name those siblings, but the verb alone makes the distinction unambiguous.

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 guidance on when to delete a template versus when to update it, and no mention of alternatives. The only hint at preconditions lives in the schema ('id from list_email_templates'), not 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful consequence — that existing labels made with the package survive — but says nothing about irreversibility, permissions, or what happens to shipments referencing the package.

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 with no filler, and the primary action is front-loaded ahead of the side-effect caveat. It could name the alternative or prerequisite in the same space, but nothing 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?

For a one-parameter delete with full schema coverage, no output schema, and annotations covering the destructive/non-idempotent profile, this is nearly complete. The only real omission is confirmation or irreversibility guidance.

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 parameter package_id is already documented as 'id from list_saved_packages.' The description adds no further meaning beyond 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 (removes) and resource (Saved Package), which is unambiguous and distinct from siblings like create_saved_package, update_saved_package, and list_saved_packages. It does not explicitly name those siblings, but the verb makes the distinction obvious.

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?

Deletion intent is implied by 'Removes', but there is no explicit when-to-use framing, no mention of when to use update_saved_package instead, and no prerequisites such as confirming the package is unused. Usage is inferable rather than stated.

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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds two non-obvious traits the annotations cannot convey: the default-address guard and that deletion is gated on owner approval, meaning the call does not complete synchronously.

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 short sentences, front-loaded with the action, followed by the blocking constraint and the approval behavior. No filler and nothing an agent must scroll past to find the critical restriction.

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 one-param destructive tool with no output schema, the key facts are present: what it removes, what it refuses to remove, and that it awaits approval. Minor gaps remain around whether the call returns a pending status or completes later, and what happens to shipments already referencing the address.

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?

Only one parameter and schema coverage is 100%, with the schema itself explaining that address_id comes from list_ship_from_addresses. The description adds nothing beyond that, but the baseline for a fully-documented single param is 3.

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 (Removes) and resource (saved Ship From Address), which cleanly separates it from the other delete_* siblings by resource type. It does not explicitly name an alternative, but the resource specificity makes the purpose unmistakable.

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 one concrete exclusion (the default address cannot be removed), which is genuinely useful pre-call guidance. However, it never points to the relevant alternatives such as set_default_ship_from_address or update_ship_from_address, so an agent blocked by the default-address rule is left to infer the next step.

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 write, destructive, non-idempotent, and open-world behavior. The description adds genuinely non-obvious context beyond that: the dispute is scoped to one label and enters a pending state awaiting the owner's approval. It stops short of explaining consequences of approval or how to track the pending dispute.

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 with no filler. The action and its approval-wait behavior are both front-loaded and easy to scan.

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-parameter mutation with full schema coverage and rich annotations, the description covers the core action and the approval flow. It leaves gaps around what happens after approval, whether the dispute can be withdrawn, and how the pending status is surfaced, which matters for an open-world write 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 the schema descriptions already explain that shipment_id comes from list_carrier_adjustments and that reason is written as if to Pirate Ship support. The description adds only "with your reason," so the schema is doing the heavy lifting and 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 ("Disputes") and resource ("carrier adjustments of one label"), making the action unambiguous. It does not explicitly name the sibling list_carrier_adjustments as the source or contrast the two, so it falls 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?

Usage is implied: dispute an adjustment with a reason, and expect an owner approval step. There is no explicit guidance on when to dispute versus ignore or refund, no prerequisites beyond the schema's reference to list_carrier_adjustments, and no mention of what to do if a dispute is rejected.

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 the safety profile is fully covered by structured fields. The description adds nothing behavioral beyond that — no mention of link expiry, file format options (PDF/ZPL), max batch size, or whether an empty result is possible.

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 no padding, and the two selection modes are stated up front. It is slightly under-specified rather than bloated, but nothing in it 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?

For a two-parameter tool with no output schema, the description should at minimum resolve the batch_id/shipment_ids exclusivity and sketch what the returned link looks like. Neither is provided, and there is no mention of format or validity window, so an agent could easily call it with no arguments at all.

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 50%: batch_id is documented in the schema, and the description's 'of chosen shipments' implicitly explains shipment_ids. However, with zero required parameters and two mutually substitutable inputs, the description never states that one of the two must be supplied or whether both may be combined — the single most important semantic for this tool.

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 (printable labels) and the output (a download link), and scopes it to a batch or chosen shipments, which is enough to know what the call yields. It is written as a noun phrase rather than a verb+resource and makes no attempt to distinguish itself from nearby tools like get_label_settings or list_return_labels.

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 statement of when to use this tool versus its many siblings, no prerequisite (e.g., labels must already be purchased/generated), and no guidance on when to pick the batch path versus the shipments path. The agent must infer all of this from the one-line 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes one genuinely useful behavioral fact beyond that: the output is CSV. It says nothing about how the CSV is delivered (inline payload vs. download URL), whether large exports are asynchronous or truncated, or any range limits on the date filters.

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?

It is a single short sentence with no waste, but it is a sentence fragment and not front-loaded with an action verb. Brevity here reflects under-specification rather than efficiency.

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 five parameters, no output schema, and a read-only annotation set, the description should at minimum explain how the CSV comes back and how date filtering scope works. Stating only the output format leaves the agent without the return mechanism it needs given the absence of an output 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?

The description merely re-lists the enum values of the required 'report' parameter, adding no meaning beyond the schema. The 'sort' parameter has no description in either place, and the relationship between from_date and to_date (and how timezones interact with 'search') is left entirely to the schema's 60% 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 sentence names the resource (CSV of one of five report types) but is a noun phrase with no verb, so the export/download action is only inferable from the tool name. It also fails to distinguish this from the five closely-related list_* siblings (list_transactions, list_refunds, list_receipts, list_return_labels, list_carrier_adjustments) and export_shipments, which is the most important differentiation an agent needs here.

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 statement of when to choose export_report over the sibling list_* tools or export_shipments, and no mention of prerequisites or limits. The agent must infer the CSV-vs-paginated-list distinction entirely on its own.

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 closed-world, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot: the output is a CSV with every column delivered as a download link. It says nothing, however, about whether filters narrow the export, link expiry, or large-export handling.

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, and the output format plus delivery mechanism come first. It is efficient, though the extreme terseness leaves no room for the usage or filter caveats an 8-parameter tool warrants.

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?

It correctly answers the return-value question (download link) in the absence of an output schema, which is the biggest gap it could have left. But for a tool with 8 optional filters it never states whether those filters scope the export or are ignored, leaving a real ambiguity for an agent building the call.

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 88%, so the schema already documents sort, batch, search, status, carrier, dates and tracking_status. The description adds no parameter meaning beyond that; the phrase 'every column' only implicitly signals that there is no column-selection 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 description names the resource (shipments report) and the output form (CSV, every column, download link), which is specific enough to distinguish it from list_shipments or get_shipment. It never explicitly contrasts itself with the sibling export_report, so sibling differentiation is implied by the resource name 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?

There is no when-to-use guidance at all: nothing says to pick this over export_report or list_shipments, and nothing explains whether the 8 filter parameters are honored in the export. The agent must infer usage purely from the tool 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the payload includes pending refunds and pending returns in addition to the balance, which is genuine behavioral value, but says nothing about return format, currency, or freshness.

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?

It is a single short sentence with no padding, which is good, but the fragment structure ('...from the Reports page') is ambiguous and buries the actual action. Briefness here stems partly from under-specification rather than efficiency.

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 and no parameters, the description is the only place an agent can learn what a call returns, yet it lists data fields without explaining their shape, units, or relationship. For a zero-argument read tool the burden is small, but distinguishing it from sibling financial/report tools is left undone.

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. Baseline 4 applies; the schema is trivially complete.

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 data returned (account balance plus pending refunds and returns), which hints at a retrieval tool, but it never states a verb and reads as a fragment rather than a capability statement. It differentiates the resource from siblings like get_rates or list_transactions only implicitly by naming the fields.

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 call this versus list_transactions, list_refunds, or cotlet_balance, all of which appear to touch related financial data. The phrase 'from the Reports page' gestures at origin but does not tell an agent when the tool is the right choice.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's value-add is telling the agent that the response spans shipments, tracking, buyable rates and refundable amounts, which is useful since no output schema exists, but it does not say anything about the draft-vs-bought distinction as a behavioral state (e.g., rates only present for drafts).

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 compact clause with no waste, and the resource identity is front-loaded. The noun-phrase phrasing is slightly telegraphic and would read better as a verb phrase, but 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?

For a one-parameter read-only getter with full annotation coverage and full schema coverage, the description supplies the key missing piece: what the returned batch payload contains. It is nearly complete, falling short only on how draft and bought batches differ in that payload.

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?

Only one parameter exists and schema description coverage is 100% with an explicit provenance note ('From create_shipment or list_batches'). The description adds nothing about the batch_id format or prefix, 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?

The description characterizes the resource (a draft or bought batch) and enumerates its contents, which implies a retrieval tool, but it never states the verb 'get' or 'retrieve' and never contrasts itself with the sibling list_batches. An agent can infer the purpose but must read the name to confirm it is a single-resource fetch rather than another listing.

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 guidance, no prerequisites, and no named alternative. The parameter schema notes batch_id comes from create_shipment or list_batches, but that is schema text, not description text, so the description itself offers no routing help.

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 a closed-world scope, so the safety profile is covered without description help. What the description does contribute is a hint at the content of the returned settings (label size, packing list, logo, QR codes, address correction, export format), which is genuinely useful since no output schema exists, but it says nothing about whether the values are account defaults, whether they are editable via update_label_settings, or what shape they take.

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?

Twelve words, no filler, no repetition. It is efficient, though the fragmentary form means it is not front-loaded with a purpose statement the way a strong definition would be.

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 zero-parameter, read-only, closed-world getter whose safety profile is fully covered by annotations, the definition is minimally viable. However, with no output schema, the description should clarify that these fields are the returned settings values and note their relationship to update_label_settings; as written, an agent could misread the list as inputs.

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 and the baseline of 4 applies. The field list it does provide is not a parameter list and should not be read as one.

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 is a bare noun-phrase list ('Label size and file format, packing list, logo, QR codes, address correction, export format') with no verb, so it never explicitly states that it retrieves settings. It does add specificity beyond the name by naming which settings categories are covered, which is enough to distinguish it from siblings like update_label_settings, but the action itself must be inferred.

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 indication of when to call this tool, no prerequisites, and no mention of the obvious counterpart update_label_settings or of get_tracking_email_settings as a related settings reader. The agent must infer usage purely from the tool name and sibling list.

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/non-destructive, so the safety bar is low, but the description adds real value the annotations don't: USPS pickups are free, so cost only varies for UPS, and nothing is committed. It omits that UPS quotes depend on date/ready_time/close_time/overweight scheduling windows, which are behavioral constraints not spelled out at the top level.

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, twenty words, zero waste. The cost question comes first and the non-binding constraint is front-loaded in the same breath, which is exactly the order an agent needs.

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 10-parameter quote tool with no output schema, the description conveys the essential shape: it returns a price, USPS is free, nothing is committed. It leaves unstated that package_count and total_weight_oz are what actually drive the UPS price and that several parameters are UPS-only, but the schema covers most of that.

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 60% and the description adds no parameter-level meaning beyond implying that carrier choice drives whether the quote is zero. The carrier/date/close_time/ready_time/overweight descriptions live in the schema, not the prose, so the description neither compensates for the uncovered location, package_count, and total_weight_oz params nor restates what is already there.

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 resource (USPS/UPS pickup) and a specific question answered (what it would cost), and immediately distinguishes itself from a booking tool with 'Nothing is booked.' An agent can tell this apart from schedule_pickup without opening either 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?

'Nothing is booked' makes the non-committal, pre-purchase role of this tool explicit, which is the key routing decision versus schedule_pickup. It stops short of naming that sibling or stating the expected sequence (quote, then schedule), so the guidance is clear but not fully explicit.

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 the operation read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context—carrier coverage and cheapest-first ordering—but does not discuss rate validity, account requirements, or origin assumptions.

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 written sentence with no filler, front-loading the carrier scope and output ordering.

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 rate-quoting tool with no output schema, the description gives only a minimal output summary (services, price, cheapest first). It omits whether returned rates include IDs needed by buy_label, currency, or delivery estimates, and says nothing about the missing origin/origin-default context.

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 only 50%, and the description adds no parameter meaning at all. Required fields like to_zip and weight_oz are documented in the schema, but dimensions and packaging have no descriptions anywhere, and the description does not compensate.

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 clearly states the resource (USPS and UPS services with prices) and the scope (one package), which distinguishes it from quote and label-purchase siblings. It does not explicitly name alternatives, keeping it below 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?

Usage is implied—an agent can infer this is for comparing shipping rates before buying a label—but there is no explicit when-to-use versus siblings like get_pickup_quote or buy_label. No exclusions or prerequisites are stated.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description needn't restate them. It does contribute one thing annotations can't: the shape of the result (billing address and the labels paid for), which matters because there is no output schema—though it says nothing about formatting, not-found behavior, 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?

It is a single tight sentence with no waste, but it is a verbless fragment, so the reader gets resource semantics before ever learning what the tool does. Conciseness is fine; front-loading the action would be better.

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 one-parameter read with no output schema, the description partially covers the gap by describing returned content (billing address, paid labels). It still omits the action verb and any link to list_receipts, leaving the agent to reconstruct the lookup pattern from structured fields.

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 receipt_id carries a pattern plus a pointer to list_receipts, so the schema does the work. The description contributes no additional meaning about the parameter, which is the correct baseline 3 when the schema is self-sufficient.

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 is a noun phrase that defines the resource (a payment to Pirate Ship plus its billing address and paid labels) but never states the retrieval verb, so an agent must infer it from the tool name. It adds useful semantic content beyond the title, but it does not differentiate from the sibling list_receipts, which the schema—not the description—points to.

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 call this versus list_receipts or list_transactions, and no prerequisites or exclusions are stated. The only routing hint ('receipt_id from list_receipts') lives in the schema, not 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, openWorldHint=false, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the returned data categories (tracking, service, cost, recipient, carrier adjustments), which is useful context but not deep behavioral detail.

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 extremely concise with no wasted words and front-loads the resource scope. It is arguably under-specified for the tool's usage context, but conciseness itself is strong.

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 simple read-only tool with full schema coverage and rich annotations, the description provides enough to identify it. However, with no output schema, it should do more to explain the return shape or how the optional batch_id affects retrieval.

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 parameters are already documented in the input schema. The description adds no parameter-level syntax or constraints, which is acceptable given full 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 names the resource as a single shipment and lists included data, so the purpose is inferable. However, it is a sentence fragment without an explicit verb and does not clearly distinguish this from siblings like list_shipments or get_batch beyond the word 'One'.

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 use this tool versus list_shipments, get_batch, or other retrieval siblings. The agent must infer that this is for fetching a known shipment_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 this as read-only, idempotent, non-destructive, and closed-world, so the safety profile is clear. The description adds useful context about the metric categories included and the date-range scope, but it does not describe return shape, aggregation level, or behavior when dates are omitted beyond what the schema states.

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?

It is a single front-loaded sentence with no filler. Every listed metric contributes to understanding what the tool returns.

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 read-only stats tool with two optional date parameters and no output schema, the description covers what data categories are included. However, it does not explain the return structure or aggregation granularity, which would be helpful since no output schema exists.

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 both date parameters are fully documented with defaults. The description confirms the date-range scope but adds no syntax or formatting 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?

The description names the resource and the key metrics returned: labels, spend, savings, tracking, and destination data over a date range. This is clear enough to distinguish it from action tools like buy_label or refund_label, though it does not explicitly name sibling report/export 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?

It gives no guidance on when to use this tool versus alternatives such as export_report, list_shipments, or list_transactions. No exclusions or prerequisites are stated.

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, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing what the settings contain (default on/off, timing after purchase, template), which annotations don't provide, but it remains terse with no note on scope or return shape.

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 economical clause that front-loads the key content with zero filler. It is a sentence fragment lacking a leading verb, but that costs little.

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 parameters and no output schema, the description carries the burden of explaining what comes back, and it does so by naming the three setting facets. Complete enough for a simple zero-arg getter, though it could state the account-level scope.

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 there are no parameter semantics to document. Baseline 4 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?

Description enumerates the specific settings returned (default enablement, delay after purchase, template), so the agent knows exactly what this getter retrieves. It's clear but phrased as a fragment without an explicit verb, and doesn't explicitly contrast with update_tracking_email_settings, relying on the obvious get/update naming.

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 name and read-only nature—view current settings, likely before calling update_tracking_email_settings—but the description never states when to use this versus alternatives or any prerequisites. Adequate inference 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 destructiveHint=true, idempotentHint=false and openWorldHint=true; the description usefully narrows what 'destructive' means here (hiding, not shipping, not deleting). However it never says whether the hide is reversible (unignore_orders exists but is unmentioned) or whether the store connection still sees these 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 front-loaded sentence with no filler; the key scope constraint ('Import list', 'without shipping') comes first. Its brevity is efficient, though the saved space is not spent on reversibility or sibling routing.

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 one-parameter mutation with rich annotations this is close to adequate, but two things an agent needs are absent: that the action can be undone via unignore_orders, and whether hidden orders disappear from the store or only from the import queue. No output schema exists to fill the gap.

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 order_ids is already documented as 'Order ids from list_import_orders' with array bounds. The description adds nothing about the parameter, so the baseline 3 for schema-covered params 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 ('hides') and resource ('store orders') plus the scope ('from the Import list') and a negative condition ('without shipping them'), which separates it from create_shipment/buy_label. It never names the sibling unignore_orders that reverses it, so differentiation is good but not complete.

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?

'from the Import list' implies the workflow comes after list_import_orders, and 'without shipping them' hints at an alternative to buying labels. But there is no explicit when-to-use/when-not statement and no pointer to unignore_orders as the undo path, so the agent must infer.

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 closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: results are ordered newest-first and include both batches and single labels, with status and tracking counts — this is the only place return content is disclosed since there is no output schema. It stops short of stating page size or how many records come back.

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 compact sentence with the scope and ordering front-loaded and no filler. Slightly dense phrasing ('Latest batches and single labels') blurs whether single labels are a separate category or an included item type.

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 does the right thing by naming the returned fields (status, tracking counts). However, for a paginated listing tool it omits page size, total counts, or whether all statuses are returned, leaving the agent to discover result shape empirically.

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?

There is a single optional parameter and schema description coverage is 100% ('0 is the newest page'), so the schema fully documents it. The description's 'newest first' phrasing reinforces the ordering but adds no syntax or range detail beyond the schema; 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 (list) and resources (batches and single labels) plus ordering ('newest first') and what each entry carries (status, tracking counts). An agent can distinguish it from the singular get_batch, though the word 'Latest' leaves the exact listing scope slightly ambiguous.

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: it is obviously a listing/overview read, and sibling get_batch is the natural alternative for a single record, but the description never says when to prefer this versus get_batch or whether pagination should be looped. No explicit exclusions or prerequisites.

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 the safety profile is fully covered without description help. The description adds useful domain context (these are adjustments recorded after label usage, and records carry old vs actual package data), but says nothing about pagination, result volume, or the total/limit behavior of a list endpoint.

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 short sentence with no padding, and the core concept is front-loaded. It is a sentence fragment rather than a complete statement, which slightly weakens orientation but wastes no words.

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 8 optional parameters, no output schema, and a list endpoint's pagination semantics, this description is far too thin to stand alone. The trailing phrase 'with old and actual package' is ambiguous — likely describing returned fields — and does not tell the agent what a response contains or how to page through results.

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 description mentions no parameters whatsoever — not the carrier filter (USPS/UPS), status, date range, or search. With schema coverage at 63%, three parameters (sort, limit, offset) are undocumented in both schema and description, and the description does nothing to compensate for the gap.

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 sentence defines the domain entity well — post-label charges or credits from the carrier — but it is a noun phrase with no verb, so the action (list/retrieve) comes only from the tool name. It also never distinguishes this from the sibling dispute_adjustment, which operates on the same records, or from list_transactions/list_refunds which could also contain charges and credits.

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 guidance at all: no statement of when to call this versus dispute_adjustment, no prerequisite that a label must exist, no mention of the default sort/pagination behavior. The agent must infer usage purely from the 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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely useful fact beyond that: exactly one template is the default, which matters for follow-up actions. It omits ordering, count, and whether HTML bodies are truncated in the response.

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 terse clause with no filler and the most decision-relevant fact (default) placed last. It is efficient but so compressed it reads as a label rather than a directive, and lacks a leading verb to anchor it.

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 no-arg, read-only list tool with annotations covering safety, this is close to sufficient, but with no output schema the description is the only place the return shape could be described and it only gestures at it ('subject, sender, HTML body'). It also never says whether the list is filtered or complete.

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 there is nothing to disambiguate; baseline is 4 by rule. The field list (subject, sender, HTML body, default flag) does hint at the returned shape, though no output schema exists to confirm 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?

The name and title carry the verb (list) while the description is a noun fragment naming the resource and its fields: 'Tracking email templates: subject, sender, HTML body.' It does clarify these are the tracking-notification templates specifically, which is more than a tautology, but the description itself never states 'returns all templates' and does not differentiate from update_email_template/create_email_template beyond the implicit list semantics.

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 when-to-use guidance and no alternatives named, despite four closely related siblings (create_email_template, update_email_template, delete_email_template, get_tracking_email_settings). The agent must infer that this is the read entry point to discover template IDs before mutating them.

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 read-only, idempotent, non-destructive, closed-world semantics, so the safety profile is covered. The description adds the meaningful scope constraint ('unshipped'), but says nothing about ordering, default page size of 25, or that results cap at 100 — an agent could silently miss orders. No contradiction with openWorldHint=false, since 'connected store integrations' is a bounded set.

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 short sentence with no waste, but brevity here comes from under-specification rather than tight editing. It is front-loaded, though the payload is thin.

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 must convey what a returned order looks like, how results are ordered, and how pagination behaves — none of which appear. For a listing tool whose defaults silently truncate at 25 records, this leaves real gaps.

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 only 50%, and the description contributes nothing about any of the four parameters — not what 'search' matches, not what 'ignored' switches to, not pagination behavior. The 'Import grid' analogy adds no operational meaning beyond what the schema already says for search and ignored.

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 the resource ('unshipped orders from your connected store integrations') but is a bare noun phrase with no verb and leans on a UI reference ('as in the Import grid') that an agent cannot resolve. It does hint at scope (unshipped, i.e., not yet fulfilled) which separates it somewhat from list_shipments, but nothing explicitly marks the distinction.

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 statement of when to use this versus sync_store_orders, list_shipments, ignore_orders, or export_report, all of which sit in the same space. An agent must guess which retrieval path is appropriate.

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, idempotentHint=true and openWorldHint=false, so the safety and scope profile is fully covered. The description contributes only the content shape (types plus size/weight limits per carrier) and says nothing about whether the catalog is static, account-specific, or complete across carriers.

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 clause with no filler, and the examples (box, envelope, flat rate) are the most useful part of the sentence. It is a sentence fragment rather than a complete statement, which slightly weakens it.

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 parameters, no output schema, and annotations covering the safety profile, the remaining burden is describing the return content, which the description does (types per carrier, size and weight limits). An agent knows enough to call it, though it can't tell whether the result is carrier-complete or account-specific.

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; the baseline for a zero-parameter tool applies. The description usefully frames what the parameterless call returns (per-carrier package types with limits).

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 is a noun phrase naming the resource (packaging types, per carrier) and the attributes returned (size and weight limits), which is informative. However, it never states the verb of action and doesn't distinguish itself from adjacent tools like list_saved_packages or create_saved_package, which concern packaging in a different sense.

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?

Nothing in the description says when to call this versus list_saved_packages (user-configured packages) or get_rates (which likely requires a package type). Usage is only inferable from the resource name; no conditions or alternatives 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context (past as well as upcoming pickups, both carriers, confirmation numbers included) but says nothing about result volume, pagination, or time window for 'past'.

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 economical sentence with no filler, leading with the scope that distinguishes it. It is a noun phrase rather than a verb-led statement, which is a minor structural weakness but costs no clarity.

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 parameters and no output schema, the description usefully notes that confirmation numbers are returned. However, it leaves open how far back 'past' extends and whether results are bounded or ordered, which an agent cannot learn from any structured field 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter meaning is lost or contradicted.

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 (pickups), the scope (scheduled and past), the carriers (USPS and UPS), and even what comes back (confirmation numbers). It is clearly a listing operation distinct from sibling actions like schedule_pickup or cancel_pickup, though the verb itself is only implied by the name and title.

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 statement of when to call this versus alternatives such as get_pickup_quote or cancel_pickup, and no preconditions are mentioned. The agent must infer usage purely from the phrase 'scheduled and past', which is scope, not 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, so the safety profile is covered elsewhere. The description adds one genuinely new behavior: default ordering is newest first. It says nothing about pagination behavior (limit max 100, offset-based paging) or result size, which is relevant for a list tool.

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 clause plus a routing pointer, with the key scoping fact ('newest first') front-loaded. 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?

With no output schema and 7 parameters, the description should say at least what a receipt row contains or how paging behaves. As written, an agent knows what the tool lists and the default order but must open the schema for filtering and gets no hint about returned fields.

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 57%; search, status, and date params are documented in-schema, while sort/limit/offset are self-evident enums/defaults. The description adds only the 'newest first' default for sort, not enough to exceed the baseline for a partially documented 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+resource and disambiguates what a receipt is ('Payments made to Pirate Ship'), which an agent could not infer from the name alone. It also names the sibling get_receipt for single-record retrieval, separating the list and get cases.

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 clause 'get_receipt shows one' implicitly tells the agent to use this tool for lists and the sibling for a single record, which is useful directional guidance. However, there is no guidance on when to choose this over adjacent tools like list_transactions, list_refunds, or export_report, which also surface payment 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, idempotentHint, and non-destructive, so the safety profile is covered. The description's only addition is that results carry status and amount and default to newest-first — the latter is already declared as the schema default for `sort`. It says nothing about pagination behavior, result caps (limit max 100), or whether all refunds are returned regardless of status/date filters.

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 short sentence with no padding, but the brevity comes at the cost of clarity — the ambiguous "Label" opener front-loads the least informative word. It is efficiently sized but not well structured for an agent to act on.

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?

A 7-parameter, filterable list tool with no output schema and 57% schema coverage needs the description to explain filtering, paging, and result shape. The single sentence covers none of these, leaving an agent to guess how `status`, `search`, and the date range combine.

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 57%, with `sort`, `limit`, and `offset` undocumented in the schema. The description touches only sort order ("newest request first") and does not explain `search`, `status`, or the `from_date`/`to_date` inclusion semantics beyond what the schema already states. It fails to compensate for the coverage gap on the paging and sort parameters.

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?

"Label refunds with their status and amount" gestures at a listing of refunds with status/amount fields, and "newest request first" implies an ordering. But the verb "Label" is ambiguous (annotate? tag? display?) for a tool named list_refunds, so the reader must infer the actual action. The resource is identifiable, but the verb is not stated cleanly enough to distinguish it from refund_label, refund_batch, or list_transactions.

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 statement of when to use this versus alternatives. Siblings like refund_label, refund_batch, list_transactions, list_receipts, and list_carrier_adjustments are all plausible confusions, and none are addressed. The only usage hint is the default sort order, which is not 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only the domain hint that labels are pay-on-use and rows carry a 'used' indicator; it says nothing about pagination behavior, default ordering, or how filtered results are counted.

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?

It is a single short fragment with no waste, but it is under-specified rather than tight — one sentence carrying two facts and omitting everything an agent needs about filtering and paging.

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 7 optional parameters, no output schema, and no annotations beyond the read-only safety profile, the description should explain paging, sorting, and what the returned fields include (used/unused status). None of that is present, so an agent cannot call this confidently beyond the bare minimum.

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?

Seven parameters with only 57% schema description coverage: sort, limit, and offset have no descriptions at all, and the description supplies no semantics for any of them. It also gives no hint that status accepts the same string values shown in the report table, or how from_date/to_date interact with the timezone note.

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 is a noun phrase ('Pay-on-use return labels and whether a customer used them') rather than a verb+resource statement, so the listing action is only implied by the tool name. It does add domain meaning — these are pay-on-use labels and the result indicates customer usage — but it never distinguishes this from siblings like list_refunds, list_shipments, or list_receipts.

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 guidance, no exclusions, and no mention of alternatives such as list_refunds or refund_label for related workflows. An agent must infer from the name alone that this is a reporting/list endpoint.

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, non-destructive and closed-world, so the safety profile is fully covered. The description adds that entries carry size, weight and extra services, which is useful content context, but says nothing about ordering, empty results, or how presets relate to shipment creation.

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 key noun phrase leads. It reads as a sentence fragment ('Your Saved Packages from Settings: ...') rather than a verb-led statement, which is a minor stylistic weakness but wastes no space.

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 zero-parameter, read-only listing tool with rich annotations and no output schema, the description gives enough about what comes back (size, weight, extra services) to call it confidently. Only a note on ordering or empty-list behavior would make it fully complete.

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 and the schema is an empty object at 100% coverage, so there is nothing for the description to disambiguate. The description correctly stays focused on output content instead of inventing parameter behavior.

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 specific resource (Saved Packages stored in Settings) and the fields returned (size, weight, extra services), which lets an agent distinguish it from siblings like list_package_types or create/update_saved_package. It never uses an explicit verb, relying on the tool name for the 'list' action, so it falls short of a full 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 context ('from Settings', plus what each entry holds) implies you call this when you need the user's pre-configured package presets, e.g., before creating a shipment. There is no explicit when-to-use, when-not, or pointer to alternatives such as list_package_types, so the agent must infer the boundary.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuine value by disclosing the shape of the result: forms grouped per ship-from address, each with a PDF link, plus identification of labels that lack a SCAN form. It does not address pagination, volume, or freshness of the data.

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 compact sentence with no filler, and the core noun (USPS SCAN Forms) is front-loaded. The trailing clause 'with their PDF links and labels still without one' is compressed to the point of ambiguity, slightly undercutting an otherwise efficient structure.

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 zero-parameter read tool with annotations covering safety and no output schema, the description covers what is returned at a high level. It omits grouping/ordering behavior and whether the PDF links are pre-signed or time-limited, which are the remaining things an agent would want to know before calling.

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 of 4 applies. Schema coverage is 100% and the schema is empty.

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 (USPS SCAN Forms) and the organizing key (Ship From Address), plus the payload (PDF links, labels lacking a form). However, it never states the operation as a verb ('list/retrieve') and the phrasing 'labels still without one' is telegraphic, so an agent must infer that this is a read-only enumeration rather than a diagnostic about missing forms.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.