Jobs, quotes, invoices and schedule in Tradify.
Scored across 35 tools
The business tools (create_job, list_quotes, send_invoice…) are cleanly distinct from the cotlet_* platform tools, but within each cluster there is overlap: cotlet_browser_open, cotlet_browser_connect and cotlet_browser_navigate all wake/navigate a browser, cotlet_apps and cotlet_whoami both report apps and balance, and cotlet_upload_file vs cotlet_browser_upload differ only subtly. Descriptions are long and do clarify these, but an agent must read carefully to pick the right one.
Everything is snake_case and most names are verb_noun, but the surface mixes a cotlet_* prefix on platform tools with bare names on business tools, and within the prefix group some names are noun-only (cotlet_apps, cotlet_balance, cotlet_whoami). The grouping is inferable but not a single predictable pattern.
35 tools is heavy for this scope, with roughly 15 dedicated to low-level browser primitives (click, type, press, scroll, select, screenshot, read, upload…) on top of a full trades CRUD surface. The browser granularity could have been consolidated into fewer higher-level tools.
Core trades workflows exist end to end (customer → job → quote → invoice → payment → appointment), but there are notable gaps: no update/delete for customers, quotes or jobs beyond status, no get_quote/get_invoice/get_customer, and no cancel or reschedule for appointments. Agents can work around some of these via list tools, but several lifecycle steps dead-end.
The apps of the user's workspace and whether each works now: access granted or requested, the app account in the user's Cloud Browser (connected, signed out, not enabled for agents), and the one step the user has to take, with the console link. Free. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| app | No | Only this app, e.g. skool. |
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.
The user's current credit balance. Free. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still adds non-obvious context beyond them: that the call costs nothing ('Free') and that authentication is required, which are genuine behavioral facts an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the main purpose front-loaded and no padding. The 'Free.' fragment is terse but conveys a meaningful fact efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only lookup with no output schema, the description covers what it returns, what it costs, and what auth it needs. Only minor gaps remain (e.g., currency/format of the balance), which is acceptable at this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify and it does not attempt to misdescribe inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the specific resource returned: the user's current credit balance. The verb ('get'/'retrieve') is implied rather than stated, and it doesn't differentiate from cotlet_whoami or other cotlet_* account tools by name, but the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Free' signals there is no cost/credit consumption to calling it, and the auth prerequisite ('needs the user's Cotlet API key or sign-in') tells the agent what is required before calling. There is no explicit when-to-use vs. alternative guidance, leaving usage implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clicks a link, button or other element of the current page in the user's browser on Cotlet, by its number in the page's element list, and returns the URL and title after the click. It acts as the user on that site. Buttons that pay or buy and buttons on account or sign-in pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
| Name | Required | Description | Default |
|---|---|---|---|
| element | Yes | The element's number in the element list of the current page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructive/openWorld/non-idempotent annotations, it discloses that the tool acts as the user on the site, that certain action classes (payment, account/sign-in) are blocked, what is returned after the click, and the billing model with a 3-minute idle expiry. These are exactly the operational constraints an agent cannot infer from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all load-bearing: action, side-effect return, refusal policy, and cost/lifetime. The final sentence packs two distinct facts (credit cost and 3-minute idle expiry) into one long clause, which slightly hurts scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description covers the return value (URL and title), the side-effect profile, refusal conditions, and the session/cost lifecycle. An agent has everything needed to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is fully documented in the schema (100% coverage), and the description's 'by its number in the page's element list' merely restates the schema text. No extra guidance on how to obtain valid element numbers, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (clicks) and resource (a link, button or other element of the current page in the user's browser) plus the addressing mechanism (its number in the element list) and the return (URL and title). This clearly separates it from siblings like cotlet_browser_press, cotlet_browser_type, cotlet_browser_select and cotlet_browser_navigate without needing to name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit exclusion rules: pay/buy buttons and buttons on account or sign-in pages are refused, which tells the agent when this call will fail. It also frames the cost/session lifecycle (credits per started minute, session ends 3 minutes after the last call), but it never explicitly routes the agent among alternatives such as press vs select vs type for a given widget.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ends the session in the user's browser on Cotlet (with app, that app's browser): the browser keeps its cookies, goes to sleep and the per-minute charge stops. Returns the session's minutes and credits.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial detail beyond annotations: cookies are retained, the browser sleeps, billing stops, and the tool returns session minutes and credits. This is consistent with destructiveHint=false because no cookies or session history are described as destroyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that states the action, side effects, and return value without filler. Every clause contributes useful invocation context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter close tool with no output schema, the description is largely complete: it explains side effects and return values and aligns with the annotations. The only gap is the undefined `app` reference, which slightly undermines clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters and full coverage, which normally supports a baseline of 4. However, the description references `app` even though no such parameter exists in the input schema, creating a small ambiguity about how app scope is selected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: ending the browser session on Cotlet, with app-specific scope noted. This distinguishes it from siblings like cotlet_browser_open, cotlet_browser_connect, and cotlet_browser_sessions without needing their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it by explaining that the per-minute charge stops, but it does not explicitly contrast this with cotlet_browser_sessions or explain when not to close a session. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wakes the user's Cloud Browser of one app (a real Chrome on Cotlet, signed in to that app as the user) and returns cdp_url, a Chrome DevTools Protocol WebSocket that gives a CDP client full control of the browser. It works in one open tab, the app's: the user watches it live, and new tabs are refused. Every started minute of an open connection costs credits. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations: it discloses that only one tab exists, that new tabs are refused, that the user watches live, that credits accrue per started minute of an open connection, and that a Cotlet API key or sign-in is required. These are exactly the operational facts an agent needs before opening a metered, user-visible session, and nothing contradicts the declared hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the action and return value, then constraints, then cost and auth. Minor awkwardness in "It works in one open tab, the app's:" but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return value, auth, cost, and tab restrictions, which is strong for a tool with no output schema. The gap is the missing link between "one app" and the zero-parameter schema: an agent is never told how the target app is chosen, nor that cotlet_browser_close should be called to stop the metered session.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the 4 baseline applies. The description adds the useful note that the browser is tied to "one app" and signed in as the user, which is context the empty schema cannot convey, though it never explains how that app is determined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A specific verb and resource ("Wakes the user's Cloud Browser") plus a concrete return value (cdp_url) makes the operation unambiguous. It distinguishes itself from interaction siblings like cotlet_browser_click/navigate by saying it hands over a CDP WebSocket, but it never names the closest alternative (cotlet_browser_open) so the boundary is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Gives a CDP client full control" implies the use case (you need raw CDP rather than the click/type/navigate helpers), and the auth/cost constraints hint at prerequisites. However, there is no explicit when-to-use versus cotlet_browser_open or cotlet_browser_sessions, and no when-not-to-use guidance despite a crowded browser sibling family.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wakes the user's own browser on Cotlet, a real Chrome hosted for them: their web browser with the sites they signed in to there, or with app that app's browser, signed in to the app. Opens url when given and returns the page's URL and title. The user watches every step live. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | A public http or https address, e.g. https://example.com. In an app's browser, a page of that app. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only declare read-only, open-world, non-idempotent and non-destructive. Beyond them, the description discloses that the user watches every step live, that every started minute costs credits, and that the session ends on close or three minutes after the last call. That billing and expiry model is exactly the context an agent needs before invoking the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense sentences with no filler, and the core identification of what is being opened comes first. The lifecycle/cost details are clustered at the end, which reads a bit run-on but is still well-ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description appropriately states that the page URL and title are returned, and it covers cost and session expiry. The remaining gaps are the error behavior and routing to related session tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the single url parameter is fully documented in the schema, and the baseline is 3. The description does explain the two browsing contexts (the user's signed-in browser versus an app's browser), but it refers to an `app` parameter that does not exist in the schema, which can confuse an agent about what it can pass.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: it wakes the user's own hosted Chrome on Cotlet and opens a URL. That is clear and concrete. However, it never contrasts itself with siblings like cotlet_browser_connect or cotlet_browser_navigate, which an agent must distinguish when starting a browsing session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The agent can infer that this is the entry point for starting a browsing session, and the closing sentence hints at session lifecycle. But there is no explicit 'use this when' versus connect/navigate, nor any guidance on whether to open the browser before calling click/type/read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Presses one key on the current page in the user's browser on Cotlet, on the element that has focus: Tab to the next field, Enter to send, Escape to close a dialog or pop-up, arrows to move through a suggestion list. Returns the URL and title after it. Enter on account pages is refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (destructive, openWorld, non-idempotent) by disclosing a safety guardrail (Enter refused on account pages), the return payload (URL and title after the press), and the billing/session model (every started minute costs credits, session ends on close or 3 minutes after the last call). Those are exactly the non-obvious traits an agent needs before deciding to act.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences: action and scope first, key semantics second, then constraints and side effects. No filler, and the credit/session warning is placed after the operational content where it belongs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one enum-constrained parameter and no output schema, the description still names the return value, the refusal case, and the session lifetime. Nothing material for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a fully enumerated key list, so the baseline is 3; the description adds real meaning by mapping keys to intents (Tab to next field, Enter to send, arrows for suggestion lists), which the bare enum does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Presses one key on the current page in the user's browser on Cotlet') and scopes it to the focused element. The concrete key examples (Tab, Enter, Escape, arrows) separate it cleanly from cotlet_browser_type and cotlet_browser_select without needing their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use guidance per key ('Tab to the next field, Enter to send, Escape to close a dialog or pop-up') plus an explicit refusal rule ('Enter on account pages is refused'). It never explicitly says when to prefer cotlet_browser_type or cotlet_browser_select instead, so it stops short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the current page of the user's browser on Cotlet: its readable text, up to 20,000 characters, and a numbered list of its links, buttons and fields. Field values, cookies and storage are never returned. On a page longer than that, both start near where it is scrolled to. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: limits (20,000 chars), exclusions (field values, cookies, storage), scroll-relative start on long pages, and cost model (credits per started minute, session ends after 3 minutes idle or on close). No contradiction with readOnly/idempotent hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with what the tool returns, then limits, scroll behavior, and cost. Every sentence earns its place and no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but the description fully explains return values (text, numbered list) and key operational details (size limits, exclusions, cost, session lifetime). Complete for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so baseline is 4. The description need not explain parameter semantics; it correctly focuses on return behavior and constraints instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Returns') and resource ('current page of the user's browser on Cotlet'), and enumerates what is returned (readable text, numbered list of links/buttons/fields). This clearly distinguishes it from sibling browser tools like screenshot or click.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage (read the page's text and interactive elements), but provides no explicit when-to-use guidance or alternatives among the many browser tools (e.g., screenshot, navigate). An agent must infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a JPEG image of the visible part of the current page in the user's browser on Cotlet, with its URL and title: boards, canvases and layouts that the page text does not show. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (all of which it is consistent with), the description discloses two things an agent could not otherwise know: cost ('Every started minute of the session costs credits') and session lifecycle ('ends when closed or 3 minutes after the last call in that browser'). For a metered, session-bound tool this is exactly the right kind of added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences; the core output is front-loaded before the cost/lifecycle caveats. The colon-introduced list ('boards, canvases and layouts') is slightly awkward but each clause carries real information rather than restating the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameters, the burden falls on the description, and it covers output form, cost, and timeout. It does not state prerequisites (an active browser session) or what happens when no browser is connected, which is the main remaining gap for a session-scoped tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so no parameter semantics are required — the baseline for a parameterless tool applies. The description correctly adds nothing spurious about inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Returns a JPEG image of the visible part of the current page') and even flags the return payload as URL + title. The clause 'boards, canvases and layouts that the page text does not show' indirectly distinguishes it from cotlet_browser_read, but it never names that sibling, so the differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'that the page text does not show' gives a usable heuristic for choosing screenshots over the text-reading sibling. What is missing is an explicit instruction such as 'use cotlet_browser_read for text' or a note that a browser session must already be connected via cotlet_browser_open/connect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scrolls the current page in the user's browser on Cotlet with the mouse wheel, as a person does: down or up by screens viewport heights (default 0.8), to the top or the bottom, or until element element is in view. Content that loads on scroll appears, and the next read lists it. Returns the URL, title and scroll position (at_top, at_bottom). Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
| Name | Required | Description | Default |
|---|---|---|---|
| element | No | Scroll until this element of the element list is in view. | |
| screens | No | How far, in viewport heights, for down and up. Default: 0.8. | |
| direction | No | Where to scroll. Default: down. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations by disclosing the cost model ('every started minute of the session costs credits'), the session lifecycle ('ends when closed or 3 minutes after the last call'), the implicit lazy-load side effect, and the exact return payload (URL, title, at_top, at_bottom). These are operational facts an agent cannot get from readOnly/idempotent hints alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense but front-loaded paragraph: mode enumeration first, then side effect/return, then billing. Every sentence carries information, though the billing clause is appended to a long sentence and could have been separated for scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by naming the returned fields and their meaning (at_top, at_bottom). Combined with the three-mode explanation and session-cost warning, an agent has everything needed to call this correctly on the first attempt.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3; the description adds cross-parameter meaning the schema does not, namely that `screens` describes distance for the down/up modes while `element` selects the scroll-until-visible mode. It restates the 0.8 default and the direction set, which is mildly redundant with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with a specific verb+resource ('Scrolls the current page in the user's browser') and enumerates the three distinct modes of operation (by screens, to top/bottom, until element). An agent can distinguish it from siblings like cotlet_browser_read or cotlet_browser_navigate without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Content that loads on scroll appears, and the next read lists it' effectively tells the agent when to use this tool (to reach lazy-loaded content, then call cotlet_browser_read). It does not explicitly name a when-not condition or state that element-based scrolling supersedes the screens/direction parameters, so the routing is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Chooses an option of a drop-down list on the current page in the user's browser on Cotlet, by the list's number in the element list and the option's label as read lists it (or its value). Returns the URL and title after it. Card fields and account pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
| Name | Required | Description | Default |
|---|---|---|---|
| option | Yes | The option. | |
| element | Yes | The element's number in the element list of the current page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only flag the operation as destructive, non-idempotent, and open-world; the description goes well beyond that by disclosing the return payload (URL and title after selection), the refusal of card fields and account pages, and the credit/session economics including the 3-minute inactivity timeout. That is exactly the kind of context an agent needs before spending money and mutating page state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core action is front-loaded in the first clause and each following sentence carries distinct information (return values, refusals, billing). It is dense rather than wasteful, though the session-cost sentence is boilerplate that inflates the definition relative to the two-parameter operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers what is returned, what is blocked, and the session lifecycle cost, which is nearly everything an agent needs. The one remaining gap is what happens on an unsuccessful match (error vs. silent no-op), which matters given destructiveHint=true.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already documents both parameters, so the baseline is 3. The description does add a little meaning by clarifying that 'option' can be matched by the label as the list renders it or by its value, but it says nothing about partial matching, case sensitivity, or failure behavior for an unmatched label.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Chooses an option') and resource ('drop-down list on the current page') and scopes it to Cotlet's browser session, which cleanly separates it from navigation or screenshot siblings. It does not explicitly name the neighboring tools (click/type/read) that an agent might confuse with selection, so it stops just short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'On the current page' establishes the precondition that a page must already be loaded, and 'Card fields and account pages are refused' gives an explicit when-not boundary. It stops short of a 5 because it never names the alternative action (e.g., use click or type when the element is not a select).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open Chrome DevTools connections to the user's Cloud Browsers with the minutes and credits each has cost so far, and the cdp_url links still valid. With close: true it ends the open connections and takes back the unused links, of one app or of all. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| close | No | End the connections and revoke the links. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavior beyond the annotations: it discloses the authentication requirement, that costs and minutes are reported, that only still-valid cdp_url links are returned, and that closing revokes unused links. This is consistent with destructiveHint=true and readOnlyHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the main behavior, with the close behavior following immediately. The phrase 'of one app or of all' is unnecessary and confusing given the one-parameter schema, but overall there is little waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with rich annotations and no output schema, the description covers the main return data and authentication. The unresolved 'one app or all' scope is a real gap because the schema cannot express app selection, leaving the agent unsure how to interpret that claim.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the close parameter is already documented. The description adds that close=true ends connections and takes back unused links, but it also mentions 'of one app or of all' even though the schema exposes no app-targeting parameter, which creates ambiguity rather than clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as Cloud Browser sessions and explains that it exposes cost, minutes, and valid cdp_url links, with an optional close behavior. It does not explicitly distinguish itself from sibling tools such as cotlet_browser_close or cotlet_browser_connect, and the opening verb 'Open' is slightly ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a useful condition for the close parameter ('With close: true') and states the authentication prerequisite. However, it does not explain when to use this tool versus cotlet_browser_close or other browser siblings, and the 'of one app or of all' scope is not actionable through the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Types text into a field of the current page in the user's browser on Cotlet, by the field's number in the page's element list, and with submit presses Enter. Returns the URL and title after it. Password, card and one-time code fields and sign-in pages are refused: the user fills those in themselves. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The text to type. | |
| submit | No | Press Enter after typing, e.g. to search. | |
| element | Yes | The element's number in the element list of the current page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses the return value (URL and title after typing), a security refusal policy for sensitive fields and sign-in pages, a credit cost per started minute, and session lifetime ('ends when closed or 3 minutes after the last call'). The mutation/destructive framing is consistent with destructiveHint=true and openWorldHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the action and addressing scheme, then layers behaviour, refusals and cost in three tight clauses. The billing sentence is slightly off-topic for a typing tool but is genuinely useful context, so only a minor deduction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, open-world browser mutation with no output schema, the description covers the action, how elements are addressed, the return value, safety refusals, and session/cost lifecycle — everything an agent needs to call it without surprises.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented, and the description largely restates them (`submit` presses Enter, element numbering from the page's element list). Baseline 3 is appropriate; it adds no constraints or gotchas beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('types text into a field of the current page') plus the addressing scheme ('by the field's number in the page's element list'), which cleanly separates it from siblings like cotlet_browser_press, cotlet_browser_select and cotlet_browser_click.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear when-to-use context via the `submit` note ('presses Enter after typing, e.g. to search') and an explicit when-not: password, card, one-time code fields and sign-in pages are refused and left to the user. It does not name the sibling to use instead for keystrokes like Tab/Escape, so it stops just short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Puts files into a file field of the current page in the user's browser on Cotlet, or into the file picker that an upload button opens, by its number in the element list. A file is given as {"url": "https://..."} for a file online or {"file_id": "..."} for one uploaded to Cotlet first; up to 10 files, 20 MB each. Returns the URL and title after it. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | The files. | |
| element | Yes | The element's number in the element list of the current page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive, open-world, non-idempotent behavior, and the description adds real value on top: accepted file source shapes, the 10-file / 20 MB limits, the returned URL and title, and the per-minute credit cost with the 3-minute idle timeout. It does not say what happens on partial failure or whether existing field content is replaced, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, purpose and input shape front-loaded, with cost/session policy last. Every clause carries information, though the credit-and-timeout clause sits somewhat awkwardly in a tool-purpose description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly states the return value (URL and title), and it covers input forms and limits. The main gap is the missing reference to how a browser session must already exist and how this differs from cotlet_upload_file.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description restates the url/file_id alternatives and the element-number meaning that the schema already documents, adding limits (10 files, 20 MB) but no genuinely new semantics such as how the element list is obtained or what happens if element is not a file input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('puts files into a file field of the current page in the user's browser'), plus the targeting mechanism (element number). It distinguishes itself from generic upload behavior by naming the browser/session context, but it never contrasts itself with the sibling cotlet_upload_file, which an agent could easily confuse it with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The browser-session framing and the note that the session ends on close or 3 minutes after the last call imply when this tool fits, but there is no explicit 'use this instead of cotlet_upload_file when...' guidance, and no prerequisites (e.g. needing an open browser session from cotlet_browser_open/connect) are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of an earlier Cotlet call, by its call_id: pending (waits for the owner's approval in the Cotlet console), approved, running, success, rejected, expired, blocked or failed. For a call that answered with status pending or running.
| Name | Required | Description | Default |
|---|---|---|---|
| call_id | Yes | call_id from the earlier call |
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.
Sends a report straight to the Cotlet team: a tool that failed or returned wrong data, an error you could not get past, or a tool, field or app the task needed and Cotlet lacks. The report carries the error text and call_id when there is one, never passwords or tokens. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| app | No | App slug the report is about, e.g. 'skool'. | |
| kind | Yes | bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else. | |
| tool | No | Tool or endpoint name, e.g. 'skool_list_members'. | |
| title | Yes | One line, e.g. 'skool_list_members stops after 50 members'. | |
| client | No | Agent or tool sending this, e.g. 'Claude Code'. | |
| call_id | No | call_id of the call that went wrong, if any. | |
| description | Yes | What you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets. |
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.
Requests access to apps for the user's workspace, as Request access in the console: a live app is granted at once, any other goes to the Cotlet team, who answer within 72 hours. Takes app slugs as listed at https://cotlet.dev/api/v1/apps. Free. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| apps | Yes | App slugs, e.g. ["skool", "substack"]. |
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.
Returns a one-time upload_url and a file_id for a local file (an image for a post, an attachment). The file is sent to upload_url with an HTTP PUT; an argument that takes a file accepts {"file_id": "..."}. Up to 25 MB, the URL works once. Free. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | File name, e.g. photo.jpg. | |
| content_type | No | MIME type, e.g. image/jpeg. |
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.
The Cotlet account this connection acts as: email, workspace, access status, the API key or OAuth client in use with its scope, the apps the workspace may call and its credit balance. Free. Needs the user's Cotlet API key or sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
New customer profile, optionally with contact details and a physical address.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| name | Yes | Customer or company name. | |
| No | Email for quotes and invoices; commas for more. | ||
| phone | No | ||
| state | No | State or region. | |
| mobile | No | ||
| address | No | Street address. | |
| contact | No | Contact person. Default: the name. | |
| postal_code | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, yet the description does not explain the consequences: whether re-submitting creates duplicates, whether an email match merges or errors, or what side effects (quote/invoice linkage) a customer creation has. For a non-idempotent, destructive, open-world write, that is the most valuable context and it is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with no filler, which is good, but brevity here comes at the cost of under-specification rather than being earned concision.
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?
Nine parameters, no output schema, and a mutation flagged destructive/non-idempotent demand more disclosure than one fragment. The agent is left without knowing what is returned (new customer ID?) or how to recover from a duplicate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 56% and several parameters (phone, mobile, city, postal_code) have no schema description, so the description needs to compensate but adds nothing. It mentions 'contact details and a physical address' generically without mapping to fields or clarifying that comma-separated emails are supported.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource ('New customer profile') and the optional facets, but it is a noun phrase with no explicit verb – creation is inferred from the tool name/title rather than stated. It does implicitly separate this from list_customers, but it never distinguishes create from update-type operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this versus a sibling (e.g. list_customers to check for an existing match first), no prerequisites, and no mention of duplicate handling. The word 'optionally' is the only guidance, and the schema already encodes required vs. optional.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Draft invoice from an approved or accepted quote, for all of it or part of it.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| lines | No | line_items: positions of the quote's lines to invoice, 1 for the first. | |
| amount | No | percentage: percent of the quote total (e.g. 50). fixed_amount: amount with tax. | |
| quote_id | Yes | Quote ID from list_quotes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the description does not need to repeat the safety profile. The description adds useful context by saying this creates a draft from an approved/accepted quote and supports partial invoicing, but it does not explain side effects such as whether the quote status changes or what makes the operation destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. The prerequisite and scope are stated efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers the basic action and prerequisite but leaves important gaps around mode semantics and side effects. Annotations help with the safety profile, but an agent still lacks full guidance on how the partial-invoicing modes interact with the parameters.
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 most parameters have descriptions, but the critical 'mode' parameter has no schema description and the tool description only vaguely says 'all of it or part of it'. It adds some meaning around full versus partial invoicing but does not explain how the enum modes map to lines and amount.
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 ('Draft invoice from ... quote') and adds the key scope condition ('approved or accepted') plus partial/full behavior. It distinguishes the tool from unrelated siblings, though it does not explicitly name alternative tools such as list_quotes or 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?
It clearly states the prerequisite that the quote must be approved or accepted, and that the invoice can cover all or part of the quote. It does not explicitly discuss when not to use the tool or name alternatives, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
New job for a customer. It starts as Unassigned.
| Name | Required | Description | Default |
|---|---|---|---|
| contact | No | Job contact. Default: the customer's. | |
| reference | No | Your reference, e.g. a PO number. | |
| customer_id | Yes | From list_customers or create_customer. | |
| description | Yes | What the work is. | |
| site_address | No | Default: the customer's address. | |
| contact_phone | No | Default: the customer's phone. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, non-idempotent and open-world, so the safety profile is covered structurally. The description contributes one genuine behavioral fact — the job starts in 'Unassigned' status, i.e. post-creation state — but says nothing about required permissions, what happens if a duplicate is submitted (non-idempotent), or what the caller receives 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?
Two short sentences, zero filler and front-loaded, but the brevity is under-specification rather than efficiency — there was room to state the return value or the customer prerequisite without bloat.
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?
This is a mutating, non-idempotent create tool with no output schema, so the description should carry the return shape (e.g. a new job id) and the key side effect. Annotations cover safety hints and the schema covers fields, but an agent still doesn't know what it gets back after calling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents defaults for contact, site_address, contact_phone and the source of customer_id. The description adds nothing about parameters, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The fragment 'New job for a customer' identifies the resource and implies creation, and the sibling set (create_customer, create_quote, get_job, list_jobs) makes the intent inferrable. But it never states an explicit verb and doesn't differentiate itself from the other create_* tools beyond the noun.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use create_job versus create_quote or schedule_appointment, and no prerequisites such as needing a customer_id that exists. The only clue comes indirectly from the schema's 'From list_customers or create_customer' reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Draft quote with line items. Nothing is sent until you call send_quote.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | Link the quote to this customer's job (list_jobs). | |
| reference | No | Customer reference. | |
| line_items | Yes | ||
| customer_id | Yes | From list_customers or create_customer. | |
| description | No | Shown on the quote. | |
| expiry_date | No | Default: your expiry days setting. | |
| tax_inclusive | No | Prices include tax. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context that annotations cannot convey: the record is created in draft state and no delivery occurs until send_quote is invoked, which reshapes how the agent reasons about the risk of a 'destructive' create.
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, zero filler, and the lifecycle constraint is placed where the agent will read it. Nothing is redundant with the title or 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?
For a creating tool with rich schema coverage and no output schema, the description covers the one non-obvious fact an agent needs: the quote is a draft that is not delivered. It does not mention that the created quote's ID is needed for send_quote or list_quotes, a minor gap against 7 parameters and an array of line items.
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 86%, so nearly every parameter (customer_id, line_items fields, expiry_date defaults, tax_inclusive) is already documented in the schema. The description contributes only the phrase "with line items" and adds no format, constraint, or default details beyond that. 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?
"Draft quote with line items" gives a specific verb (draft/create) and resource (quote) plus the essential payload, which clearly separates it from send_quote. It stops short of explicitly naming sibling alternatives, but the draft-vs-send framing makes the role obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Nothing is sent until you call send_quote" tells the agent where this tool sits in the workflow and which sibling to call next, which is exactly the routing guidance needed. It omits prerequisites (e.g. that customer_id must come from list_customers/create_customer) and any when-not conditions, but the sequencing context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full job: description, site, tasks, notes, appointments, costs, linked quotes and invoices.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job ID from list_jobs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. What the description does add is the breadth of the returned aggregate (description, site, tasks, notes, appointments, costs, linked quotes and invoices), which is genuinely useful since no output schema exists. It stops short of covering error behavior for an unknown job_id or payload shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Eleven words with no filler, and the field enumeration is front-loaded. The weakness is that it is a bare fragment rather than a sentence, so the most important piece of information (this retrieves one job) is implicit rather than leading.
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 single-parameter, fully annotated, read-only fetch with no output schema, listing the included sub-resources is a reasonable stand-in for describing the return value. Missing only edge-case behavior (e.g., invalid or deleted job_id) to be fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, and the schema documents it at 100% coverage with 'Job ID from list_jobs.' With coverage this high the schema carries the semantics, so the baseline 3 applies; the description adds nothing about the ID format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun fragment ('Full job: ...') that enumerates the payload contents, so it does convey what the tool returns, but it never states the action (fetch a single job by ID) and relies on the name/title for the verb. It also never explicitly contrasts itself with the sibling list_jobs, so an agent must infer that this is the detail view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance, and no mention of alternatives such as list_jobs (for scanning) or create_job/update_job_status. The closest hint, 'Job ID from list_jobs,' lives in the schema, not the description, so the description itself offers no routing information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scheduler appointments in a date range, with staff, job, times and notes.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Last day, up to 31 days after from. | |
| from | Yes | First day. | |
| staff | No | Only these staff members, by full name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds a modest hint about returned content (staff, job, times, notes), but says nothing about pagination, result-set size, or what happens when the 31-day cap is exceeded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler, which is good for scannability, but it is under-specified rather than concise. It reads as a label restated rather than a front-loaded statement of action.
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 partly compensates by naming the fields returned. However, for a 3-parameter read tool with an implicit date-range cap, an agent still lacks any statement of result shape, ordering, or volume limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already documents from, to (with the 31-day constraint) and the staff name filter. The description adds no parameter-level detail beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun fragment ('Scheduler appointments in a date range, with staff, job, times and notes') with no verb, so it only implicitly conveys a listing/query operation. It names the resource and the scope, but does not distinguish it from siblings like schedule_appointment or get_job beyond the date-range hint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as schedule_appointment (for creating) or get_job (for a single job's details). The date-range framing hints at bulk retrieval but leaves selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Customer profiles with contact details and sites.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | next_cursor from the previous call. | |
| search | No | Matches name, contact, email or phone. | |
| archived | No | List archived customers instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint false, so the safety profile is covered. The description adds that customer profiles include contact details and sites, which is useful return-content context, but it says nothing about pagination, ordering, or the archived option.
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 very short and contains no fluff, but it is a sentence fragment rather than a well-structured statement. It is front-loaded in the sense that there is only one clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with strong annotations and mostly documented schema parameters, the definition is minimally adequate. However, it does not explain when to use this versus other list tools, how search and archived interact, or that results are paginated.
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 75%, with cursor, search, and archived documented in the schema; only limit lacks a description. The description adds no parameter meaning beyond the schema, so it neither compensates for the missing limit description nor improves on the already-documented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource ('Customer profiles') and some returned fields ('contact details and sites'), but it is a noun phrase without a clear verb such as 'list' or 'retrieve'. It distinguishes itself from create_customer by implication, but does not explicitly differentiate from other list tools like list_jobs or list_invoices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of filtering or pagination behavior. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invoices with customer, job, due date, total, amount paid and amount due.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | next_cursor from the previous call. | |
| search | No | Matches number, reference or customer. | |
| status | No | approved (sent, not fully paid; default), overdue, paid, draft, cancelled or all. | approved |
| customer_id | No | Only this customer's invoices (list_customers). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful detail of which fields each invoice carries, but says nothing about pagination, result ordering, or that the default status filter is 'approved' (which materially changes what comes 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?
A single short fragment with no waste, but it spends its only sentence on output fields and omits the operation itself. Efficient, yet under-specified rather than concise.
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 fills the biggest gap by enumerating returned invoice fields, which is the most valuable thing it could add for a read tool. Missing are pagination behavior and the default status='approved' scoping, which matter for a list tool but are partially recoverable from the cursor and status schema descriptions.
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% with only 'limit' lacking a description (it still has default 50 and min/max bounds), so the schema does the heavy lifting. The description contributes no parameter meaning at all — the listed fields are return values, not filters, so it neither compensates for the limit gap nor clarifies filter interactions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun fragment listing returned fields (customer, job, due date, total, paid, due) rather than stating a verb. Combined with the name list_invoices it's inferable as a listing operation, but nothing distinguishes it from list_quotes, list_jobs or list_customers beyond the resource word.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus siblings (list_quotes, get_job, list_customers) or versus fetching a single invoice. It also never mentions that results are filterable by status, search or customer, so an agent gets no cue about the querying workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Jobs with number, customer, site address, status and assigned staff.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | next_cursor from the previous call. | |
| search | No | Matches job number, customer or reference. | |
| status | No | active (default), all, unassigned, assigned, scheduled, in_progress, to_invoice, on_hold, complete, cancelled or the name of a custom status. | |
| customer_id | No | Only this customer's jobs (list_customers). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered without the description. The description adds nothing beyond that: no mention of pagination via cursor/limit, no note that results default to active-only status, and no indication of what the returned fields are.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single short fragment with no waste, but it is under-specified rather than concise: it reads as a field listing without a leading verb or the tool's actual behaviour front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter, filterable list tool with no output schema, the description should at minimum state that it lists jobs, note pagination and the default active-status filter, and route to get_job for a single record. It does none of these, though annotations and schema cover safety and most parameters.
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 effectively 80% (all parameters except 'limit' carry descriptions, including the important 'active (default)' status semantics). The description mentions output fields that do not map to any parameter, so the schema is doing all the work; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun fragment ('Jobs with number, customer, site address, status and assigned staff') that restates the resource and its fields but supplies no verb and no scope. Only the name/title ('list_jobs') tell the agent this is a listing operation, and nothing distinguishes it from get_job or list_customers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus get_job (single record) or the other list_* siblings. Prerequisites, pagination workflow, and default filtering behaviour are left entirely to inference from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quotes with customer, total, quote date, expiry date and status.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since | No | Only quotes dated on or after this day. | |
| cursor | No | next_cursor from the previous call. | |
| search | No | Matches number, reference or customer. | |
| status | No | awaiting_acceptance (default), draft, accepted, expired, cancelled, declined or all. | awaiting_acceptance |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety is covered. The description adds nothing behavioral beyond that: it omits that results are paginated and, critically, that the default status filter is 'awaiting_acceptance' — a caller expecting all quotes would be silently misled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short and front-loaded with zero filler, but it is a sentence fragment rather than a definition, so brevity comes at the cost of meaning. The space used is not wasted, yet it does not earn its place by conveying an operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With five filter/pagination parameters, a non-obvious default status, and no output schema, the description should carry real weight. Enumerating return fields gives partial credit for the missing output schema, but pagination, defaults, and filter behavior go unexplained, leaving the agent under-informed for a tool it will likely call often.
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 80%, so the schema already documents since, cursor, search, and status; the baseline of 3 applies. The description's mention of 'status' and 'quote date' loosely aligns with the status/since filters but adds no syntax, default, or interaction detail, and says nothing about the undocumented limit parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The text is a noun fragment ('Quotes with customer, total, quote date, expiry date and status.') that largely restates the title 'List quotes' while enumerating return fields. It never states a verb or scope (e.g., 'Lists quotes'), so an agent must infer the operation from the name rather than the description, and nothing separates it from siblings such as create_quote, send_quote, or list_invoices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of the other list tools (list_invoices, list_jobs, list_customers), and no note about prerequisites or exclusions. The agent gets no signal about choosing this tool over any sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a payment received against an invoice and reduce the amount due.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Payment date. Default: today. | |
| amount | Yes | Amount received, at most the amount due. | |
| method | No | Payment method name, e.g. Bank Deposit, Cash, Credit Card. Default: Unknown. | |
| reference | No | e.g. the check number. | |
| invoice_id | Yes | Invoice ID from list_invoices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known. The description adds a useful behavioral fact — that recording a payment reduces the amount due — but says nothing about irreversibility, what happens on duplicate calls, or returned results, which matters for a non-idempotent mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the verb and resource and includes the key side effect with no filler. 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?
Annotations and schema together cover safety and parameters well, and there is no output schema to explain. However, for a destructive, non-idempotent mutation the description omits what a successful call returns and any error/validation behavior, leaving meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each of the five parameters documented including defaults and the 'at most the amount due' constraint. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (record a payment) plus its effect on the invoice balance, so the operation is unmistakable. It does not explicitly contrast with siblings like send_invoice or list_invoices, but those are different operations so disambiguation is largely inherent.
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 says what the tool does but never states when to use it versus alternatives, prerequisites (e.g., invoice must exist via list_invoices, amount must not exceed amount due), or the partial-payment case. All such guidance is only implicit or buried in parameter descriptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Book a job appointment on the Scheduler for staff, optionally emailing the customer a confirmation. Waits for the owner's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ISO 8601; without a zone, company time. | |
| notes | No | Notes for the crew. | |
| staff | No | Staff member names, one appointment each. Default: you. | |
| start | Yes | ISO 8601; without a zone, company time. | |
| job_id | Yes | Job ID from list_jobs. | |
| email_customer | No | Email the customer a confirmation. | |
| customer_message | No | Extra text in that email. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool is not read-only, not idempotent, open-world, and destructive. The description adds meaningful behavioral context by noting optional customer confirmation emailing and that the booking 'Waits for the owner's approval.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core action and then add the optional email and approval workflow. There is no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, open-world appointment-booking tool, the description covers the key approval workflow and optional customer email, while the schema fully documents all parameters. It does not explain conflict handling or return behavior, but no output schema exists and annotations carry the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all seven parameters are already documented in the input schema. The description only reinforces 'staff' and the optional customer email, without adding new syntax or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Book a job appointment on the Scheduler for staff.' It also clarifies optional customer email and owner approval, making the action distinguishable from list_appointments and create_job.
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 'Book a job appointment' and 'for staff,' but the description gives no explicit when-to-use guidance, no exclusions, and does not point to alternatives such as list_appointments for checking existing bookings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Approve the invoice and email it to the customer, with payment reminders if enabled. Waits for the owner's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Recipient emails. Default: the customer's email. | |
| message | No | Email text. Default: your invoice template. | |
| subject | No | Default: your invoice email template. | |
| invoice_id | Yes | Invoice ID from list_invoices or create_invoice_from_quote. | |
| send_me_a_copy | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real behavior beyond the annotations: it emails the customer, includes payment reminders if enabled, and blocks waiting for the owner's approval. That approval gate is a genuinely useful non-obvious trait; it still does not say what happens on denial or whether the invoice status changes.
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 tight sentences, front-loaded with the action and immediately followed by the key constraint (owner approval). Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, open-world, non-idempotent operation with no output schema, the description covers the approval gate but omits the outcome: what is returned, what happens on rejection, or whether the invoice is marked sent. Adequate but leaves gaps for a consequential write action.
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 parameters like to, message, subject, and invoice_id are already documented with defaults. The description adds only a general notion of emailing the customer and reminders, with no extra detail on recipients or copy 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?
States a specific verb+resource: approve the invoice and email it to the customer, plus the reminder behavior. It is clearly distinguished from send_quote and create_invoice_from_quote by naming the invoice-specific action, though it does not explicitly name the siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (send an existing invoice, sourced from list_invoices or create_invoice_from_quote per the schema), but the description never states when to choose this over send_quote or when not to call it, e.g. for drafts or unpaid-approval states.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Approve the quote and email it to the customer with a link to accept or decline online. Waits for the owner's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Recipient emails. Default: the customer's email. | |
| message | No | Email text. Default: your quote template. | |
| subject | No | Default: your quote email template. | |
| quote_id | Yes | Quote ID from list_quotes or create_quote. | |
| send_me_a_copy | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare openWorldHint, destructiveHint, and idempotentHint=false, so the risk profile is largely covered. The description adds useful context that the send is gated on the owner's approval, but it is ambiguous whether the tool blocks until approval or sends immediately, and it doesn't warn about duplicate sends or what happens when approval is denied.
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 core action and followed by the key gating constraint. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-idempotent, externally visible send with no output schema, the description covers the action and the approval gate but leaves open the return behavior and error/denial handling. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already documents defaults for 'to', 'message', and 'subject'. The description adds no parameter-level meaning beyond that, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Approve the quote and email it to the customer') and explains the accept/decline link, so the agent knows exactly what the tool does. It doesn't explicitly contrast with close siblings like send_invoice, but the quote-specific framing makes the distinction reasonably clear.
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?
'Waits for the owner's approval' implies the context in which this tool runs, but there is no explicit when-to-use vs. when-not guidance and no mention of alternatives such as send_invoice or create_invoice_from_quote. 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.
Set a status on a job, built-in or one of your custom statuses.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job ID from list_jobs. | |
| status | Yes | unassigned, assigned, scheduled, in_progress, to_invoice, on_hold, complete, cancelled or the name of a custom status. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive=true, idempotentHint=false and openWorldHint=true; the description adds almost nothing beyond restating the name. It omits whether the change notifies the customer, whether it is reversible, whether custom statuses must pre-exist, and what happens on failure. For a declared-destructive mutation this is a real 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?
A single short sentence with no waste, front-loaded with the action. It is concise but arguably under-specified rather than dense with 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?
A destructive, non-idempotent mutation with no output schema needs more than one sentence: what the response looks like, consequences of the status change, and any state preconditions are all absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the status enum values are fully enumerated in the schema, so the description's mention of 'built-in or custom statuses' adds no new detail. Baseline 3 applies since the schema carries the parameter burden.
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 (set) plus resource (a job's status) and scope (built-in or custom statuses). Enough to distinguish from get_job/list_jobs/create_job, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No indication of when to use this versus other job tools, no prerequisites (e.g., whether the job must exist or be in a particular state), and no mention of side effects or follow-up steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
cotlet_appscotlet_balancecotlet_browser_clickcotlet_browser_closecotlet_browser_connectcotlet_browser_navigatecotlet_browser_opencotlet_browser_presscotlet_browser_readcotlet_browser_screenshotcotlet_browser_scrollcotlet_browser_selectcotlet_browser_sessionscotlet_browser_typecotlet_browser_uploadcotlet_get_callcotlet_report_issuecotlet_request_appscotlet_upload_filecotlet_whoamicreate_customercreate_invoice_from_quotecreate_jobcreate_quoteget_joblist_appointmentslist_customerslist_invoiceslist_jobslist_quotesrecord_paymentschedule_appointmentsend_invoicesend_quoteupdate_job_statusField service management for trades: clients, jobs, estimates, invoices, schedule and reports.
Job cards for trades and field service: hours and materials per job, open to invoiced.
Manage jobs, customers, scheduling, estimates and invoices for a field service business.
Quotes, jobs and invoices for HVAC, plumbing and electrical shops. Drafts good-better-best quotes.
Add one secure layer between your agents and this server.
