Tradify by Cotlet

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?

Goes well beyond the annotations by disclosing that it acts as the user on the site, that certain clicks are refused for safety, and that every started minute consumes credits with the session ending on close or after 3 minutes of inactivity. That is material operational context an agent cannot infer from destructiveHint/openWorldHint 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?

Four sentences, each doing distinct work: action and return value first, then acting-as-user semantics, then refusal policy, then cost/session lifetime. No filler and no repetition of the schema.

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). Combined with refusal rules and billing/session behavior, an agent has everything needed to decide to call it and to interpret the result.

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 at 100% schema coverage, so the schema carries it; the description reinforces that the index refers to the element list of the current page, which ties the parameter to the read tool that produces that list. It adds modest but useful framing rather than new syntax.

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?

Specific verb+resource: clicks an element of the current page in the user's Tradify Cloud Browser, addressed by its index in the page's element list, and states what is returned (URL and title). It is clearly separable from siblings like cotlet_browser_press, cotlet_browser_type, cotlet_browser_select, and cotlet_browser_navigate.

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 constraints on when the tool will refuse to act (pay/buy buttons, account or sign-in pages), which is real usage guidance. It does not explicitly contrast with siblings such as press/navigate for link-following, so the routing is implied rather than spelled out.

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

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

Annotations already declare non-destructive, idempotent, non-open-world behavior; the description adds real value on top by explaining that cookies are retained, the session is merely put to sleep (recoverable), billing stops, and the response contains minutes and credits consumed. That covers consequences, reversibility, and return content for a zero-annotation-gap 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 sentence with the action front-loaded and every clause — cookie retention, sleep state, billing stop, return values — carrying information an agent needs. Nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters, no output schema, and annotations already covering safety and idempotency, the description fills the remaining gaps: session state after closing, cost implications, and the shape of the result. Nothing required for a correct call 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?

There are no parameters, so there is nothing to mis-specify, and the description instead documents what the call returns (minutes and credits). Baseline 4 applies for a parameterless 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?

States a specific verb ('Ends the session') and resource ('the user's Tradify Cloud Browser'), making it trivially distinguishable from sibling cotlet_browser_open and the other browser_* action tools. The added clauses about cookies persisting and billing stopping confirm exactly what kind of 'end' this is.

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 clear: it is the shutdown counterpart to cotlet_browser_open, and the note that the per-minute charge stops signals when an agent should call it (when done browsing). It stops short of naming the alternative or stating explicit exclusions, but no inference is needed to know this is a teardown call.

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

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

Beyond the annotations, the description discloses important behavior: only Tradify pages open, navigation returns the final URL and title, each started minute costs credits, and the session ends when closed or three minutes after the last call. These are substantive operational details that meaningfully supplement the read-only and open-world 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?

The description is front-loaded with the core action and return behavior, followed by scope, cost, and session lifetime. Every sentence adds useful information and there is no redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high schema coverage, clear annotations, and absence of an output schema, the description covers what an agent needs: accepted address scope, return values, session lifetime, and credit cost. No critical context for invoking the tool appears to be 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?

The schema already documents the single url parameter at 100% coverage, setting the baseline at 3. The description adds a meaningful constraint by stating that only Tradify pages open, which clarifies accepted URL values beyond the schema's generic public http/https wording.

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 uses a specific verb and resource: it opens a public http or https address in the Tradify Cloud Browser and returns the final URL and title. This is clear, but it does not distinguish itself from the sibling cotlet_browser_open tool, so sibling differentiation is missing.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by stating it opens a public http or https address and restricts this to Tradify pages, but it does not explicitly say when to use this tool versus cotlet_browser_open or other browser actions. The cost and session timeout notes add useful context but not direct alternative 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?

Adds a lot beyond the readOnly/openWorld annotations: per-minute credit cost, a 3-minute idle termination, and the fact that the user watches live. That is exactly the kind of context annotations cannot express. It leaves one costly ambiguity given idempotentHint=false — whether a second call reuses the live session or spawns a new billed one.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with identity and scope, then call-scoping, then cost and lifetime. Every sentence carries information an agent would otherwise have to guess, including the non-obvious billing side effect.

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 compensates by stating it returns the page's URL and title, and it covers cost and session expiry. The remaining gap is session lifecycle on repeat invocation, which matters for a non-idempotent, credit-metered tool surrounded by browser siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single `url` parameter is fully described there. The description only restates that `url` is opened when given; it adds no format or validation detail beyond the schema's 'public http or https address' 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?

States a concrete verb and a precisely characterized resource: it wakes the user's Tradify Cloud Browser, a real Chrome hosted on Cotlet already signed in as the user. It also draws the boundary against the sibling API tools with 'Use it for what the Tradify tools do not cover,' so an agent can place it 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?

'Use it for what the Tradify tools do not cover' is an explicit selection rule against the create_/list_/get_ family. It does not address the closest ambiguity, however: when to open a fresh URL versus using cotlet_browser_navigate on an already-open session.

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 context beyond the annotations: the return value (URL and title after the press), the account-page refusal rule, the per-minute credit cost, and the session lifetime ('ends when closed or 3 minutes after the last call'). These are non-obvious operational constraints an agent cannot infer from destructiveHint/openWorldHint 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?

Three sentences, front-loaded with the action and target, then the key examples, then return value and guardrails. No filler; the cost/session sentence is dense but earns its place as decision-relevant 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?

With a single enum parameter, no output schema, and no annotations explaining cost or failure modes, the description fills exactly those gaps: return shape, refusal condition, and session/credit economics. Nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a closed enum, so the schema already defines valid values; the description still adds meaning by explaining what the most common keys accomplish in-page (Tab advances focus, Escape dismisses dialogs). It does not cover the remaining enum members, but those are self-describing.

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 ... in the user's Tradify Cloud Browser') plus the exact target ('the element that has focus'), which implicitly separates it from cotlet_browser_click (targets a chosen element) and cotlet_browser_type (enters text). The enumerated key-to-outcome examples (Tab/Enter/Escape/arrows) make the operation 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 concrete situational guidance ('Tab to the next field, Enter to send, Escape to close a dialog or pop-up, arrows to move through a suggestion list') and a hard exclusion ('Enter on account pages is refused'). It never names a sibling tool such as cotlet_browser_type as the alternative for text entry, so the routing 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations: 20,000-character cap, truncation anchored near the current scroll position, explicit exclusion of field values, cookies and storage, and a credit/session cost model with a 3-minute idle termination. That is exactly the operational context annotations cannot convey.

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 the resource and payload, then truncation behaviour, then the cost caveat. No sentence is redundant and the cost warning is placed at the end where it is still noticeable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of describing return values and does so precisely, including limits and what is deliberately omitted. Nothing an agent needs to call this 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?

The tool takes no parameters and the schema coverage is 100%, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly spends no words on 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 a specific verb and resource ('Returns the current page of the user's Tradify Cloud Browser') and enumerates what comes back: readable text plus a numbered list of links, buttons and fields. That content profile implicitly separates it from cotlet_browser_screenshot, but the siblings are never named, so the differentiation 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?

Use is implied by the returned content ('readable text' + interactive element list), which suggests calling it before click/type to learn what is on the page. There is no explicit when-to-use/when-not statement and no pointer to the screenshot or navigate siblings for the cases this tool does not cover.

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 safety is covered. The description does add genuinely useful context beyond that: JPEG output, inclusion of URL and title as visible part only, per-started-minute credit cost, and session expiry three minutes after the last call. A 4 is warranted for that added cost/lifecycle context, though it omits what happens if the browser is not open.

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, front-loaded with what the agent gets back, followed by the credit/session constraint. No filler and nothing repeated from the schema.

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 still explains the return value (JPEG image plus URL and title) and the key operational constraint (credits per started minute, session ends on close or after three idle minutes). It does not mention resolution or behavior when no page is loaded, which keeps it from a 5.

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 no parameter semantics for the description to compensate for; the baseline of 4 applies. The description also correctly implies the implicit target is the current page in the user's browser session.

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 ('Returns a JPEG image of the visible part of the current page') plus the extra payload (URL and title). The clause 'boards, canvases and layouts that the page text does not show' implicitly separates it from the text-based siblings like cotlet_browser_read, so an agent can pick the right tool without opening a schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'that the page text does not show' gives a clear rule for choosing this over the text-reading sibling, and the note about session lifetime and credits tells the agent to batch calls. It stops short of naming alternatives explicitly or stating when not to screenshot (e.g. already-loaded text content).

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 openWorldHint, yet the description still adds substantial context: lazy-loaded content appears after scrolling, the return payload (URL, title, at_top, at_bottom), the credit cost per started minute, and the 3-minute session expiry after the last call. It omits failure behavior (e.g., element never found, timeouts), which keeps it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and modes, then behavioral details and the return values. Every sentence carries information, though the trailing billing/session sentence is tangentially about the browser session rather than the scroll operation itself.

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, but the description compensates by naming the returned fields (URL, title, at_top, at_bottom). Combined with full parameter schema coverage and the lazy-load explanation, an agent has what it needs to call and interpret the result; only edge-case failure handling 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?

Schema coverage is 100% so the baseline is 3, but the description goes further by tying the `screens` magnitude to viewport heights and default 0.8, and by framing the `direction`/`element` modes as distinct scroll intents (down/up, top/bottom, until element in view). This adds usable semantic framing beyond the field-level schema text.

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 ('Scrolls the current page ... with the mouse wheel') and enumerates the distinct scroll modes (down/up by screens, to top/bottom, until element in view). This clearly separates it from siblings like cotlet_browser_click, cotlet_browser_press and cotlet_browser_read.

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 clear usage context ('Content that loads on scroll appears, and the next read lists it'), which implicitly routes the agent to cotlet_browser_read afterwards. It does not, however, say when to prefer this over alternatives such as keyboard-based paging via cotlet_browser_press, nor state any exclusions.

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

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

Annotations already declare destructive=true, openWorld=true, and idempotent=false, and the description adds real context beyond them: the return value (URL and title), the security refusal for card fields and account pages, and the session billing model (credits per started minute, 3 minutes after the last call). It does not say whether a selection is reversible or what happens if the option label is ambiguous.

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, front-loaded with the action and its two identifiers, followed by return value, refusals, and session economics in descending order of importance. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does supply the return value (URL and title), plus the refusal and billing constraints, so an agent can invoke it and anticipate cost. Minor gaps remain around failure modes (option not found, page state) but nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns more by clarifying that 'option' may be the option's label as the element list reads it or its underlying value, which the schema's generic 'The option.' does not convey. It also reinforces that 'element' is the list's index in the page element list.

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 (chooses) and resource (an option of a drop-down list on the current page), scoped to the Tradify Cloud Browser. It is clearly distinguishable from cotlet_browser_click because it names the drop-down/select-list target and the two-part identifier model.

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 for drop-down/select elements, and gives an exclusion: "Card fields and account pages are refused." However, it never explicitly says to prefer this over cotlet_browser_click, nor what to do when the option isn't in the list, so 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?

Beyond annotations (destructiveHint, openWorldHint), it discloses that sensitive fields and sign-in pages are refused, that the URL and title are returned, and that session time costs credits and expires 3 minutes after the last call. That's substantive behavioral context an agent cannot get from annotations 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?

Four front-loaded sentences with no fluff; purpose comes first followed by returns, refusals, and session constraints. Slightly dense but each sentence carries useful 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?

With no output schema, the description explicitly explains the return value (URL and title), covers refusal cases, and documents session lifetime and credit cost. An agent has everything needed to call it 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 coverage is 100% and all three parameters are already documented with descriptions. The description's mention of element numbering and submit-presses-Enter largely restates what the schema says, so it adds little beyond the baseline.

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?

Specific verb ('Types text') + resource ('a field of the current page') + mechanism ('by the field's number in the element list'). It is clearly distinguishable from siblings like browser_click, browser_press, browser_select, and explains the submit side effect and the return value.

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?

States clear context and exclusions: refuses password, card, one-time code fields and sign-in pages because the user fills those themselves. However, it doesn't explicitly route to an alternative sibling (e.g., press/select) or describe the prerequisite that the page must be current.

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 hard limits (up to 10 files, 20 MB each), the return payload (URL and title), and a non-obvious cost/session model (every started minute costs credits; the session ends on close or 3 minutes after the last browser call). Those are operationally decisive facts an agent cannot infer from destructiveHint/idempotentHint/openWorldHint.

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 action and target are front-loaded, and the limits, return value, and cost model follow in short clauses with no filler. The first sentence is dense with comma-joined clauses and could be split, but every sentence carries useful 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 write-capable, open-world tool with no output schema, the description covers the target, the input sourcing rules, size/count limits, return values, and billing/session lifetime. Nothing material is left for the agent to guess.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns a step up by clarifying that 'element' can denote either a file field or a button whose picker will be opened, and by restating the mutually exclusive url/file_id sourcing. The 10-file and size limits duplicate maxItems in the schema rather than adding new detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Puts files into a file field ... or into the file picker that an upload button opens') and names the exact page context ('the user's Tradify Cloud Browser') plus the addressing mechanism ('by its number in the element list'). This clearly separates it from the other browser_* interaction tools and from cotlet_upload_file, which only stages files in Cotlet.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the two valid input modes ({url} for an online file, {file_id} for one uploaded to Cotlet first) and the two attachment targets (a file input or a picker opened by an upload button), which tells an agent when this tool applies. It stops short of naming cotlet_upload_file as the prerequisite for obtaining a file_id, or stating exclusions.

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

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

Annotations already declare 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 readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds real value by saying the record is created with company defaults exactly as the New Customer form does, and that nothing is sent externally. However, it never warns that repeat calls will create duplicate customers (non-idempotent) — the single most important behavioral risk here — so it doesn't go far beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the create action and the default-behavior note; almost every clause earns its place. The closing fragment 'It reaches no one and stays inside Tradify' is grammatical shorthand that takes a moment to parse.

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 9-parameter write tool with no output schema, the description omits the single fact an agent most needs next: what is returned (a customer id?) so the new customer can be referenced by create_quote, create_job or schedule_appointment. Duplicate-suppression behavior is also unaddressed, leaving meaningful gaps against the tool's 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?

Schema description coverage is 56%, so the description needs to compensate but largely restates what is there: the comma-separated multi-address rule for email and 'quotes and invoices go there' duplicate the schema's own wording. Nothing is said about phone vs mobile, city, state or postal_code, leaving those four parameters undocumented in both places.

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 (create a new customer profile) plus the optional payload shape. It explains the resulting state (active customer with default price group, document theme and tax settings), which distinguishes it from list_customers, but it doesn't name which sibling to use before/after it.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the reader can infer this is the step before create_quote/create_job, but no explicit when-to-use or when-not-to-use is given, and the sibling list (list_customers, create_job, create_quote) is never referenced. The one contextual clue is 'It reaches no one and stays inside Tradify', which frames the call as non-notifying.

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 say readOnly=false, destructiveHint=true, idempotent=false, openWorld=true; the description adds materially more — the result is a DRAFT that is not finalized until send_invoice, it is linked to the quote and its job, due dates derive from payment terms, and the part modes are plan-gated. That resolves the key ambiguity an agent would otherwise have about the destructiveHint and about whether the action is final.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and sized reasonably for a five-mode tool; nearly every clause carries information (mode semantics, pro gating, draft state). However, it is delivered as dense run-on sentences without list formatting, making the mode-by-mode semantics harder to scan than necessary.

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, it covers preconditions, mode behavior, downstream finalization, and plan gating. The remaining gap is that it never says what comes back (e.g., the new draft invoice's ID), which the agent needs to chain into send_invoice — though the description implies linkage.

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 documents lines, amount, and quote_id (75% coverage) but leaves the required, behavior-defining `mode` enum undocumented; the description fills exactly that gap by defining all five modes and their interaction with the other parameters. It adds less for `lines`/`amount` since the schema already explains those, and adds the unstated rule "A part is one line at the quote's tax rate."

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?

Specific verb+resource ("Creates a draft invoice from a quote") plus an explicit anchor to the equivalent UI path ("as Create Invoice > From Quote does"). It also enumerates the five modes, so an agent can distinguish this from siblings like create_quote or send_invoice at a glance.

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 states the precondition ("from an approved or accepted quote"), describes what each mode is for, and points to send_invoice as the follow-up step. It also flags the plan requirement ("Needs a plan with progress invoicing (Pro) for the part modes"). It stops short of naming explicit exclusions versus other invoice-creation paths, so not 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?

Goes meaningfully beyond the annotations: the job is auto-numbered, starts Unassigned, contact/phone/site_address are inherited from the customer, and critically 'It reaches no one and stays inside Tradify' tells the agent no notifications are dispatched. It does not explain the idempotency implication of auto-numbering (duplicate calls create duplicate jobs), which is the main remaining 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 first three sentences say the same thing twice ('New job for a customer. It starts as Unassigned.' followed by 'Creates a job for a customer, as New Job does... It starts Unassigned'), and the 'as New Job does' aside references something the agent cannot see. Restatement crowds out the details that would actually help.

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 should say what comes back — particularly the new job's identifier, since the agent needs it to call schedule_appointment or update_job_status next. That is missing, though the creation semantics (state, numbering, inheritance) are otherwise adequately covered for a 6-param creation 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 the schema already documents all six parameters including defaults for contact, contact_phone and site_address. The description restates the defaulting rule but adds no format, constraint, or interaction detail beyond the schema; 'reference' and 'description' are untouched. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Creates a job for a customer') and pins down the initial state ('starts as Unassigned') and numbering behavior, which distinguishes it from siblings like create_quote or schedule_appointment. The opening fragment 'New job for a customer. It starts as Unassigned.' is then largely restated, but the substance 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?

It points forward to schedule_appointment ('books staff on it'), which implies the natural next step, but never says when to prefer create_job over create_quote/from-quote paths or what preconditions exist (e.g. customer must already exist). Usage is implied 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 declare a non-read-only, non-idempotent, destructive mutation, and the description adds real context beyond them: the object stays a draft, totals are computed server-side ('as Tradify does'), tax falls back to the default rate, and expiry comes from a settings value. It does not describe what is returned or whether repeated calls create duplicates, which the non-idempotent hint makes relevant.

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 key fact (draft only, nothing sent) is front-loaded, but it is restated verbatim at the end ('The quote stays a draft until send_quote'), and the parenthetical line-item explanation is dense mid-paragraph. The redundancy costs space that could have covered return values.

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 7-parameter creation tool with no output schema, the description covers inputs and defaults well but says nothing about what comes back, leaving the agent unsure whether a quote id is returned for the subsequent send_quote call. That is the one thing an agent needs to chain the draft-to-send workflow.

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 86%, so the baseline is 3; the description earns a step up by explaining pricing provenance (time lines take the price from the customer's price group unless unit_price is given) and the constraint that job_id must belong to the same customer. These are behavioral relationships not expressed in 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?

Opening sentence gives a specific verb and resource ('Draft quote with line items') and immediately distinguishes the tool from send_quote. The line-item model (misc vs time) is stated up front, so an agent can tell what this tool produces without opening the schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the send step to send_quote ('Nothing is sent until you call send_quote') and names a real limit ('Price list items and kits are not supported yet') that tells the agent when to abandon this path. It stops short of naming alternatives for the unsupported cases or stating prerequisites like permissions.

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 establish that this is a safe read-only, idempotent, non-destructive operation. The description adds useful behavioral context by enumerating what is returned, noting that appointment times include the company's UTC offset, and instructing the agent to read before changing a job.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then expands into the returned data. It is somewhat list-heavy and repeats the field enumeration at two levels of detail, but the detail is useful because there is no output schema.

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?

Because there is no output schema, the description carries the burden of explaining return values, and it does so comprehensively: customer, contact, site, status, reference, description, staff, tasks, notes, appointments with UTC offset, costs, and linked quotes/invoices. Combined with the annotations and fully documented parameter, it gives the agent enough context to call the 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?

There is a single required parameter, job_id, and the schema already documents it at 100% coverage as 'Job ID from list_jobs.' The description does not add any further meaning about the parameter or its format, so the schema does the heavy lifting.

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 and scope: it returns one full job with its customer, site, tasks, notes, appointments, costs, quotes, and invoices. It distinguishes itself from list-style siblings by emphasizing 'Returns one job,' though it does not explicitly name list_jobs as the alternative.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete usage rule: 'Read it before changing a job.' That clearly establishes when this tool is needed in the workflow, but it does not mention when not to use it or explicitly compare it to sibling tools such as list_jobs.

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 genuine value beyond that: it discloses the inclusive date bounds, the 31-day ceiling, the status vocabulary, the ISO 8601 timestamps expressed in the company's UTC offset, and that the staff filter is a name-based whitelist.

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, no filler, with the resource and scope front-loaded in the first sentence and the return shape in the second. The opening fragment ('Scheduler appointments in a date range...') is slightly telegraphic, and the second sentence is dense, 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?

There is no output schema, so the description carries the return contract itself and does so thoroughly: job, customer, staff member, start/end with timezone, notes, and enumerated status. Combined with the disclosed 31-day bound, an agent has everything needed to call this 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: both endpoints are inclusive ('both days included') and the staff parameter keeps only the named people by full name. This clarifies range and filter behavior beyond the terse schema descriptions.

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 (list/return) and resource (Scheduler job appointments) with clear scope: a date range with an optional staff filter. It implicitly separates itself from schedule_appointment (creation) by describing a read/list operation with filtering, though it never names the 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?

Usage is implied rather than stated: the 31-day range cap and the staff filter suggest when the tool fits, but there is no explicit 'use this when...' guidance and no mention of alternatives such as get_job or schedule_appointment. An agent must infer the boundary conditions.

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 useful behavior beyond that: pagination via next_cursor, the matching fields for search, and the note that email may be a comma-separated list. It omits ordering guarantees and page-size behavior, keeping it just shy 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?

Front-loads the returned resource and fields, then packs search usage, archived behavior, and cursor semantics into tight sentences. Dense but no filler; slightly cramped rather than bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries the burden of describing return contents, which it does (contact, email, phone, mobile, address, sites). Pagination and search semantics are covered; ordering and empty-result behavior are not, a minor gap for a list 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 75% and the description reinforces the meaning of `search` (matches name/contact/email/phone), `archived` (lists archived instead), and `cursor` (pass next_cursor back). Only `limit` is left to the schema, which is self-evident, so the description adds real value on the non-obvious params.

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 (lists) and resource (customers) plus the returned fields (contact, email, phone, mobile, address, sites). The opening sentence establishes exactly what the tool produces, distinguishing it from mutation siblings like create_customer and unrelated list_* 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?

Explicitly says to use `search` to find a customer_id before creating a job or quote, and clarifies that `archived` switches to archived customers. It gives clear positive usage context but does not explicitly exclude or contrast against all sibling list tools (e.g., list_quotes/list_jobs), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description adds genuinely useful behavior: newest-first ordering, the exact definition of 'approved' (approved but not fully paid), how amount due is computed (total minus payments and credits), and the next_cursor round-trip. It stops short of covering page size limits or what an empty result means.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the resource and return fields, then status semantics, then filters, then pagination — a logical progression with no filler. The opening fragment ('Invoices with customer, job, due date, total, amount paid and amount due') largely repeats the field list in the next sentence, a small redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With five optional params, no output schema and an 80% schema coverage, the description adequately covers the return shape, ordering, status semantics, filtering interaction and pagination. Remaining gaps (page size bounds, empty-result behavior) are minor and partly covered by the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so baseline is 3, but the description goes further: it likely clarifies status semantics beyond the enum description and explains the customer_id-plus-status filtering order, which the schema does not convey. It says nothing about search or limit, which are schema-documented or self-evident.

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 (Lists) and resource (invoices), plus the exact fields returned (customer, job, due date, total, paid, due) and the ordering (newest first). An agent can immediately distinguish this from send_invoice, create_invoice_from_quote or record_payment without opening a schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the semantics of every status value and clarifies the non-obvious interaction between customer_id and status (status filters the page you get). It does not explicitly name an alternative tool or say when not to use it, 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 read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: newest-number ordering, default active-only scope, and how next_cursor should be passed 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?

The description is front-loaded and mostly efficient, but 'Jobs with number...' and 'Lists jobs' are slightly redundant. It is appropriately sized for a filtered list tool.

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 valuably names the returned fields. It covers default scope, ordering, filtering, and pagination, leaving only minor details like search and max limit to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the baseline is 3. The description adds meaning for status defaulting and the customer_id-then-status interaction, and clarifies cursor reuse, though it does not discuss search or 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?

The description gives a specific verb and resource ('Lists jobs') and adds returned fields plus ordering, so the purpose is clear. It does not explicitly differentiate from siblings such as get_job or list_customers, which keeps it below the top score.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains the default active-job scope and how status all, built-in statuses, custom statuses, and customer_id interact to narrow results. It stops short of stating when to choose this over get_job or other listing alternatives.

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 non-obvious behavior: ordering (newest first), what the default filter actually returns, and the pagination contract ('pass next_cursor back as cursor'). It does not mention the 50/100 limit bounds, but those are in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the resource and key filters, which is good, but the first two sentences duplicate the same field list ('customer, total, quote date, expiry date and status' then 'customer, linked job, total (with tax), quote, expiry and accepted dates and status'). Roughly a sentence of redundancy in a short 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?

No output schema exists, so the description carries the burden of conveying return shape, and it does enumerate the fields plus ordering and cursor handoff. It omits default page size and what next_cursor looks like, minor gaps for a read-only list endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the baseline is 3; the description earns more by disambiguating enum semantics the schema does not ('expired is the ones awaiting acceptance past their expiry date') and by clarifying since as 'dated on or after that day'. It leaves search and limit to the schema, but those are already documented.

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 (lists) and resource (quotes) plus the returned fields and ordering ('newest quote date first'). It is clearly distinguishable from write-side siblings like create_quote, send_quote, or create_invoice_from_quote.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains that the default is awaiting_acceptance, that expired means awaiting_acceptance past its expiry date, and gives a concrete recipe ('use status accepted with since to find what was won in a period'). It lacks explicit exclusions, but for a list tool the practical filter guidance is the useful part and it is present.

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 side effects: no charge, no email, amount capped at the amount due, full payment marks the invoice paid, and a sync to any connected accounting app. It does not address what happens on repeated calls (idempotentHint=false) or how to correct a mistaken payment, which is a real gap given destructiveHint=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?

Four short sentences, front-loaded with the core action and effect, then constraints, then the external side effect. The 'amount cannot exceed what is due' line repeats the schema slightly, but it reinforces a hard failure condition rather than wasting 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 destructive, non-idempotent mutation with no output schema, it covers preconditions, constraints and downstream sync well. The remaining hole is the return value and whether a recorded payment can be amended or voided, which the agent must know before invoking a destructive write.

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 schema coverage at 100%, the schema already documents all five parameters, so baseline is 3. The description adds genuine value by specifying that the method is supplied by name from Settings > Payment Methods and that reference carries something like a check number, which the schema only gestures at.

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 ('Record a payment received against an invoice') and the resulting effect ('reduce the amount due'), which no sibling tool does. The line 'as Add Payment does' anchors it to a known UI action, and 'charges nobody and emails nobody' implicitly separates it from send_invoice.

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?

Establishes the precondition clearly: a payment you already received, against an approved invoice. The 'charges nobody and emails nobody' remark steers the agent away from using this to bill a customer, but no sibling tool is named as the alternative for that case.

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

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

With destructiveHint=true and idempotentHint=false already declared, the description adds real context: staff receive a 'You've been scheduled' notice, the job transitions from Unassigned/Assigned to Scheduled, an optional customer confirmation email is sent containing customer_message, and there is a per-call confirmation plus an owner-approval gate. It does not explain reversibility (how to unschedule) or what happens on overlapping bookings, which matters given destructiveHint=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?

The key action and its scope are front-loaded in the first sentence, and each subsequent sentence carries information (staff default, status transition, email contents, confirmation/approval). It is somewhat run-on with mild redundancy around 'as the Scheduler does' and the repeated 'Books the job on the Scheduler', but nothing is wasted enough to distract.

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 7-parameter mutation tool with no output schema, the description covers side effects, prompts, approval, and state changes well. It still leaves gaps an agent would want: what the call returns (created appointment identifiers) and failure behavior on conflicts or unavailability are unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds modest value—'by full name' for staff and the fact that customer_message is embedded in the confirmation email—but largely restates what the schema already documents (staff default, one appointment each, email_customer 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 opening sentence states a specific verb and resource ('Book a job appointment on the Scheduler') plus the optional email side effect, and the body clarifies scope: one appointment per named staff member, start-to-end. It is clearly distinguishable from the sibling list_appointments (read) and create_job (job creation) without opening a schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: 'job_id' comes from list_jobs and the tool applies only to Unassigned or Assigned jobs, but there is no explicit 'use X instead when...' guidance or stated preconditions (e.g. what happens if the job is already Scheduled or Completed). The approval/confirmation note is about execution flow, not tool selection.

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 by disclosing the 2-Step Security precondition that aborts the call before approval, the per-call confirmation gate that can be disabled, and the state change (draft becomes approved and numbered). The resend capability also implicitly clarifies why idempotentHint is false while the operation stays repeatable.

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, but the payment-reminder clause is stated twice in consecutive sentences and the email/approval points are re-explained, padding an otherwise three-sentence definition.

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 annotation-level detail on side effects, the description covers the important operational facts: approval side effect, external email delivery, security precondition, confirmation behavior. It omits what the call returns (sent status, message id), which an agent may want after invoking it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the schema already documents defaults and limits for to, message, subject and invoice_id. The description only restates the same defaults (recipient falls back to customer email, subject/body fall back to the template) and adds nothing on send_me_a_copy, which is undocumented in both places.

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 compound action on a specific resource: approve a draft invoice and email it to the customer, including what the approval does (assigns an invoice number). It is clearly separable from the nearest sibling, send_quote, and from create_invoice_from_quote.

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 usable context: it applies to a draft invoice, an already-approved invoice can be re-sent, and omitted recipients fall back to the customer's email. It never names an alternative tool or states when *not* to send (e.g. unsent-paid invoices), so it falls short of explicit routing 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 flag destructiveHint and openWorldHint, but the description adds real depth beyond them: the state transition (draft to awaiting acceptance), the hard 2-Step Security precondition that aborts before approving, resend behavior, the default per-call confirmation and its opt-out, and that it waits on the owner's approval. An agent knows exactly what will happen and what can block it.

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, but the first two sentences restate the same approve-and-email-with-link behavior almost verbatim, wasting space. Several distinct constraints are packed into one dense block rather than ordered by importance.

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 mutation with no output schema, the description covers the state change, prerequisites, resend semantics, confirmation behavior and parameter defaults well. Only minor gaps remain, such as the send_me_a_copy flag and what the response returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the schema already documents most parameters. The description nonetheless clarifies defaulting behavior for 'to', 'subject' and the message body against the email template, which is meaningful added context; only send_me_a_copy goes unmentioned.

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 plus the concrete effect: approves a draft quote, moving it to awaiting acceptance, and emails it with an accept/decline link. This is clearly distinguishable from siblings like send_invoice or create_quote without opening the schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear operating context: omission of 'to' routes to the customer's email, an already-approved quote can be resent, and sending is blocked unless 2-Step Security is configured. What's missing is an explicit pointer to alternatives (e.g. send_invoice) when the user's intent is ambiguous.

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 adds meaningful context beyond those: 'It reaches no one' (no notifications are sent) and 'one more call sets it back' (the change is reversible). This helps an agent understand side effects and recovery.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and appropriately sized for a simple mutation tool. The first two sentences are slightly redundant ('Set a status on a job… Sets a job's status…'), but the rest earns its place with examples and caveats.

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 status naming, custom status conventions, reversibility, and notification behavior. It does not mention permission requirements or invalid-status behavior, but those are minor gaps given the available structured data.

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 useful detail beyond the schema by explaining that custom statuses come from Settings > Jobs > Job Statuses and that spaces are rendered as underscores, which is not captured in the schema's status description.

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 ('Set a status on a job') and immediately scopes it to built-in or custom statuses, mirroring the 'Change Status' action on the Jobs list. It is clearly distinct from sibling tools like get_job or create_job without needing to open the schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the reference to 'Change Status on the Jobs list,' and the reversibility note hints at when it is safe to call. However, there is no explicit guidance on when to use this versus alternatives (e.g., schedule_appointment) or any exclusions.

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