Quote, hold and book US house cleaning jobs on a customer's behalf, at each business's own prices.
Scored across 10 tools
The tools map cleanly onto a booking lifecycle (search → discover → quote → hold → book → modify/cancel → status), and each verb targets a distinct action. There is mild overlap: search already returns prices and bookable windows 'so you can go straight to hold', and book and status share duplicated state-machine text, but the boundary between reserving (hold) and committing (book) is clearly stated.
Names follow a very predictable convention: short, lowercase, single-token names throughout (book, cancel, discover, hold, modify, quote, register, search). The only minor deviation is that status and taxonomy are nouns while the rest are verbs, which slightly breaks the verb pattern but stays readable.
Ten tools is well-scoped for a marketplace booking domain, and each one earns its place (registration, discovery, quoting, holding, booking, modifying, cancelling, status, taxonomy). Nothing looks redundant or padded.
The full job lifecycle is covered—search, discover, quote, hold, book, modify, cancel, status, plus auth and taxonomy lookup. The main gap is enumeration: there is no tool to list an agent's own jobs or open holds (status is single-transaction_id), so an agent with several bookings must track and poll ids itself and cannot inspect its hold quota.
Commit a hold with the customer's details. Returns booked, or pending_approval (the owner must say yes: the quote's booking_authority was approval_required, or the owner's booking setting tightened since; the time stays reserved; poll status until decide_by, about once a minute: the owner has up to 2 hours, never later than an hour before the job (a job starting within about an hour keeps its hold's time); jobs waiting count toward your open holds; with no answer by then the job is expired: the job ends and the reserved time is released; you may cancel while waiting), declined (with the owner's reason, its canonical code, next_actions and next_available) or expired. Booking an already booked job answers ALREADY_BOOKED. A declined or expired answer carries alternatives and if_changed (businesses one change away: never bookable from the item; ask the customer, then search again without change.word). Every answer carries state (one of quote_incomplete, quoted, held, pending_approval, booked, completed, declined, cancelled, supplier_cancelled, expired), allowed_actions and next_actions; every error carries a code and next_actions. quote_incomplete: Not priced yet: the job needs more facts. needs says which. Nothing is held. Allowed: quote. quoted: An exact price for one exact job version, until expires_at. Nothing is held: the time is not reserved yet. Allowed: hold, quote. held: A time is reserved for this job until hold_expires_at. Book it, or cancel to let it go. Allowed: book, cancel. pending_approval: Asked to book; the owner must say yes by approval.deadline. The time stays reserved while waiting. No answer by then and the job expires and the time is released. Allowed: status, cancel. booked: The owner is committed to do this job at this price and time. Allowed: status, quote, modify, cancel. completed: The job was done. completion.source says who marked it: the owner (merchant) or CommonTape after the window ended (system). Allowed: status. declined: The owner said no. decline.reason says why; decline.next_available is the next open time when there is one. Allowed: status, quote. cancelled: Called off by the agent. The time was released. Allowed: status, quote. supplier_cancelled: Called off by the owner after it was booked. The job can be quoted again elsewhere from job. Allowed: status, quote. expired: Ran out of time: the quote passed expires_at, or the hold or the owner's answer passed its deadline. The time was released. Allowed: status, quote.
| Name | Required | Description | Default |
|---|---|---|---|
| customer | Yes | ||
| transaction_id | Yes | transaction_id from quote or hold | |
| idempotency_key | Yes | Unique per write request (a UUID). Retrying with the same key returns the original result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it discloses approval deadlines, reservation timing, expiration behavior, polling guidance, idempotency-adjacent retry semantics, error codes, next_actions, and the meaning of each returned 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 description is an enormous, run-on block of text with many semicolon-linked clauses. Although it is front-loaded with the core action, the state-machine detail is overlong and poorly structured for quick agent scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description compensates by describing return states, error shapes, deadlines, reservation consequences, and allowed follow-up actions in extensive detail. An agent has enough context to call and interpret results 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 67%, and the description adds little parameter-level meaning beyond 'customer's details.' It does not explain transaction_id, customer subfields, or idempotency_key, leaving the schema to carry most parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource: 'Commit a hold with the customer's details.' It then describes the return states and allowed actions, making clear what the tool does and how it differs from siblings like hold, quote, cancel, and status.
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 explicit state-based usage rules: booking is allowed for held, not for pending_approval (where status/cancel are allowed), and booked jobs allow status/quote/modify/cancel. It also says 'Book it, or cancel to let it go,' providing direct alternatives and when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel your own held, waiting (pending_approval) or booked job and release the slot. Optional reason: customer_changed_plans, customer_booked_elsewhere, booked_in_error, customer_other. The answer carries cancellation (by, at, reason, fee null, policy, capacity_released): CommonTape takes no cancellation fee. Already cancelled answers ALREADY_CANCELLED (with recovery when the business called it off).
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| transaction_id | Yes | transaction_id from quote or hold | |
| idempotency_key | Yes | Unique per write request (a UUID). Retrying with the same key returns the original result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it discloses no cancellation fee, slot/capacity release, idempotent write semantics, and the ALREADY_CANCELLED terminal state with recovery behavior. It stops short of covering auth/permission requirements or failure modes like a non-existent transaction.
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 purpose and scope are front-loaded in the first sentence, followed by the reason enum and return-shape details. It is dense and slightly run-on in the trailing clauses but every sentence carries 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?
There is no output schema, yet the description enumerates the returned cancellation fields (by, at, reason, fee, policy, capacity_released) and the already-cancelled outcome. Combined with the state coverage, an agent has everything needed to invoke and interpret this 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 67% and the reason enum values are already fully enumerated in the schema, so the description's reason list is redundant. It does not add format or constraint detail for transaction_id or idempotency_key beyond the schema, so this lands at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (cancel) plus the exact resource states it applies to (held, waiting/pending_approval, booked) and adds the scope qualifier 'your own' and the side effect 'release the slot'. This clearly separates it from siblings like modify or book.
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 establishes the condition under which cancellation is valid (own held/waiting/booked job) and lists the allowed reasons, giving a clear context for use. It does not name an alternative such as modify for rescheduling, so there is no explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe one merchant: services with pricing_model (packages: each package with its price, limits, kinds and the tasks it includes; the price is the cheapest package that fits the whole home and does every must-have task), typed inputs (incl. its answer for every job condition: no_charge, extra_charge with amount, ask_first, not_taken, not_answered), add-ons and passport (what each service covers, per task word), the business time zone (timezone), service area (area, town and state in area_details, further-out ZIPs in travel), crew, takes (the kinds of home and the largest home it takes; null = not answered; services[].takes are the limits that apply to each service, which may be looser or tighter than the business: judge a job by those; ask_first_above and unsure mean the owner says yes first, never a miss), when (only its plain day-and-hour Nos: min_days_ahead, weekends, evening_starts, holidays; null = not answered), services[].matchable (false = task list not confirmed: not searchable or quotable, reason scope_not_confirmed), brings, products, payment (declared; the customer pays the business directly) and hours in that time zone.
| Name | Required | Description | Default |
|---|---|---|---|
| merchant_slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose domain-meaningful behavior for downstream use (null = not answered, matchable=false means the task list is unconfirmed and thus not searchable or quotable, payment is 'declared' and paid directly), but says nothing about read-only status, permissions, error cases for a bad slug, or rate limits.
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 ~200-word sentence with deeply nested parentheticals ('packages: each package with its price, limits, kinds and the tasks it includes...') that is hard to parse. The purpose is front-loaded, but the remainder is a wall of field documentation with no structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the heavy lifting of documenting the returned payload, including nested services, pricing_model, add-ons, area and takes semantics, so return-value coverage is unusually thorough. However it omits the parameter's meaning, when to call it, and any failure behavior, leaving real gaps for an agent.
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 0% for the single parameter merchant_slug, and the description never explains it - no format, no source, no example. It only implies 'one merchant' is identified, which is weaker than what the schema alone conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening clause 'Describe one merchant' gives a specific verb (describe) and a bounded resource (one merchant), which is distinguishable from siblings like search, quote and taxonomy that operate over sets or pricing. The purpose is clear despite being buried under a very long run-on payload listing, and there is no explicit sibling differentiation beyond the singular 'one merchant'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus search, taxonomy or quote, and no prerequisites such as where merchant_slug comes from. Usage is only implied by the singular 'one merchant', leaving the agent to infer the routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reserve one window from a quote: the quoted job becomes held (same transaction_id). An expired or replaced quote answers QUOTE_EXPIRED: quote again. M-19: pick a window of the quote's job_hours; a window of another length, or one no longer in the business's hours, answers OUTSIDE_HOURS. M-19b: the hold counts the job's cleaners (job_people) against the business's cleaners in all and keeps its time between jobs; a window that no longer fits answers CAPACITY_FULL. Holds expire; book before hold_expires_at. Refused with PRICE_MISMATCH when the quote does not state exactly the window's conditions (weekend, evening, holiday, same-day, next-day): quote again as the message says. M-18: the answer says what it holds (quote_id, price, window, booking_authority); a hold locks the price. If the business changed since the quote the job is judged again: a lower price is held and price_changed says so; a higher one is refused PRICE_CHANGED (old and new amount, reasons, a fresh quote_token) unless accept_price_up_to covers it. HOLD_EXISTS: you already hold this job at this business (transaction_id). BUSINESS_UNAVAILABLE: it stopped taking jobs or no longer does this one. Recoverable refusals carry alternatives (other times, other businesses; never one that breaks a must). Dead ends also carry if_changed: up to 2 businesses that could do the job if the customer gave up ONE thing (change.word), with the price then; never holdable from the item (no token, no slot): ask the customer, then search again without that word. Holds you let run out count: five in 24 hours and the next answers RATE_LIMITED with retry_after_seconds. M-21: a time that is too soon (notice, or the business's same-day / next-day No) answers INSUFFICIENT_NOTICE with error.earliest (RFC 3339, business offset): pick a later window or quote again; a weekend, evening or holiday No answers OUTSIDE_HOURS.
| Name | Required | Description | Default |
|---|---|---|---|
| quote_token | Yes | ||
| allocation_id | Yes | ||
| idempotency_key | Yes | Unique per write request (a UUID). Retrying with the same key returns the original result. | |
| accept_price_up_to | No | Optional. Your own ceiling for this call: a higher price at or under it is held and reported. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly: it details hold expiration, price locking, capacity checks, rate limiting, and numerous refusal codes (QUOTE_EXPIRED, OUTSIDE_HOURS, CAPACITY_FULL, PRICE_MISMATCH, etc.) with their meanings and recovery options. This is exceptionally transparent about tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph cramming many edge cases and error codes. It is not front-loaded for quick scanning and lacks structure (e.g., bullet points or headings). While information-dense, it is far from concise and could be significantly more digestible.
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 complex, stateful tool with no annotations and no output schema, the description covers behavior comprehensively, including return values ('the answer says what it holds') and recovery paths. The main gap is lack of explanation for two required parameters, but overall contextual completeness is strong.
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 50%; idempotency_key and accept_price_up_to have descriptions, but quote_token and allocation_id do not. The description mentions quote_token only in passing ('a fresh quote_token') and never explains allocation_id. It does not compensate for the missing parameter documentation, leaving required parameters semantically unclear.
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 first sentence states a specific verb and resource: 'Reserve one window from a quote: the quoted job becomes held'. This clearly distinguishes it from siblings like book (which finalizes a booking) and quote (which produces a quote). However, it does not explicitly name any sibling tool or contrast its purpose, so it falls short of the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description never says when to use this tool versus alternatives such as book or quote. It implies a workflow ('book before hold_expires_at') but provides no explicit guidance on prerequisites, when to prefer hold over book, or when not to use it. Usage must be inferred entirely from error behaviors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Commit a change to a booked job: first quote it again with its transaction_id, then modify with that quote_token, optionally moving it to another window. The job stays booked; the old version and price are kept. The answer and every refusal carry change: kinds (capacity, commercial, eligibility, approval, non_commercial), rechecked, price from and to; a refused change leaves the booked job as it was. Refused with NEEDS_OWNER_APPROVAL when the new quote adds, drops or rewords something the owner must approve, or would not book on its own and costs more or moves an owner-approved job. A job the business called off answers SUPPLIER_CANCELLED with recovery. Refused with PRICE_MISMATCH when it is for a different ZIP, leaves out a task the booked job asked for (send every booked task again in inputs.addons), drops the home (leaves out a fact of the home the booked job stated: its kind, size or a room count; new values are allowed; refused with next_actions cancel, search), or does not state exactly the day and hour conditions of the window (a job that stays in its window keeps the same-day or next-day condition it was booked with). The owner's yes covered one version only. Check the new quote's price against your customer's limit before you modify: a change is priced against the business's current offering. Moving to a time that is too soon answers INSUFFICIENT_NOTICE with error.earliest; a job that keeps its time is never re-checked.
| Name | Required | Description | Default |
|---|---|---|---|
| quote_token | Yes | ||
| transaction_id | Yes | transaction_id from quote or hold | |
| idempotency_key | Yes | Unique per write request (a UUID). Retrying with the same key returns the original result. | |
| new_allocation_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: the job stays booked, the old version and price are preserved, what the response contains (change kinds, rechecked, price from/to), every refusal code (NEEDS_OWNER_APPROVAL, SUPPLIER_CANCELLED, PRICE_MISMATCH, INSUFFICIENT_NOTICE), and specific success conditions. This is unusually rich behavioral disclosure for a mutation 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?
The purpose is front-loaded, but the body is a dense, run-on wall of text, especially the single PRICE_MISMATCH sentence that strings multiple unrelated failure conditions together. Nearly every clause is substantive, but the structure makes it hard to parse quickly.
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 complex, no-output-schema mutation tool the description covers return fields, failure modes, and side effects thoroughly. Minor gaps remain: the provenance of new_allocation_id (where to obtain a window id) is not stated, and idempotency is left entirely to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, leaving quote_token and new_allocation_id undocumented in the schema. The description compensates by explaining that quote_token comes from the fresh quote and that the optional window move maps to the allocation argument, adding real meaning 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 opening sentence states a specific verb and resource: 'Commit a change to a booked job,' and makes the two-step protocol explicit (re-quote with transaction_id, then modify with quote_token). It implicitly separates itself from book/cancel by scoping to an already-booked job, but it never names a sibling tool outright.
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 establishes the ordering precondition: you must re-quote first and pass the resulting quote_token, and the change is priced against the business's current offering. It does not, however, explicitly contrast with alternatives like cancel or hold, or state when a caller should prefer cancel over modify.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quote one merchant's service. Every quote is a record: it returns transaction_id, quote_id, job_version and state quoted (or quote_incomplete). Pass transaction_id to quote the same job again (its next version; everything asked for before is carried forward); on a booked job that quote is the change modify commits. A job that ended is never revived: quoting it starts a new job. Search already returns prices; a search price is not a promise and becomes a record only when held. status ready = one exact amount, breakdown, expires_at, quote_token; status incomplete = a needs list of inputs still missing (never a range). Call discover first to see each service's inputs. State every job condition that is true in inputs.conditions. A job the business does not take (its kind of home, largest home, or a condition it marked not taken) is refused in plain words. For a service priced by packages, send must-have tasks in inputs.addons. A task the business does not offer on its own is quoted only in a package that includes it. A ready quote's package.includes lists the tasks it covers. Includes bookable windows (allocation_id), each with the day and hour conditions the quote must state to hold it.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | The rooms the job covers: leave_out (rooms not to clean) or clean_only (the only rooms to clean), never both, by space.* key. Under a by_rooms price a room left out comes off the price; other prices do not change. Echoed on every answer and shown to the owner. | |
| inputs | No | ||
| property | No | The home, stated once with the words at /api/v1/taxonomy/house_cleaning (property). Unknown or unclear words are refused with the word meant or the question to ask. Bedrooms, bathrooms (when there is no half bathroom) and square feet feed each price that uses them; no need to repeat them in inputs. A by_rooms price and a fixed price's limits read property.spaces only (state every kind the price counts, 0 included; a living area is living + family + formal living rooms). | |
| service_key | Yes | ||
| customer_ref | No | Optional. Your own label for your customer, so two customers with the same job are not the same job. Never shown to the owner. | |
| merchant_slug | Yes | ||
| transaction_id | No | Quote this job again: its next version. | |
| idempotency_key | No | Optional. A retry with the same key returns the same quote. | |
| special_requests | No | Up to 5 plain-text requests not on the word list. Always needs the owner's approval. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses a state machine (quoted vs quote_incomplete / ready vs incomplete), the ready-quote payload (exact amount, breakdown, expires_at, quote_token), that incomplete returns a needs list and never a range, that jobs are never revived, and that declines are refused in plain words. It stops short of stating auth/permission requirements or retry/rate-limit behavior (idempotency is only in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose and return contract are front-loaded in the first two sentences. The remainder is dense but each clause covers a distinct behavior (re-quoting, packages, refusals, windows), so little is filler. It is heavy and parenthetical, which taxes readability, but the length is largely justified by the tool's complexity.
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 complex, stateful quoting operation with no output schema, no annotations, and only 67% schema coverage, the description supplies the missing behavioral context: return states, refusal handling, package semantics, and bookable-window fields. It is close to complete, missing only secondary details like any required scoping/prerequisite checks beyond calling discover.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, so the description must add meaning, and it does: it clarifies transaction_id semantics (re-quote the same job), that all true job conditions must be stated in inputs.conditions, that package must-haves go in inputs.addons, and how scope/leave_out interacts with by_rooms pricing. It leaves some nested fields (surcharges, quantities, property.size) to 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 opening sentence names a specific verb and resource ('Quote one merchant's service') and immediately states the return contract (transaction_id, quote_id, job_version, state). It explicitly distinguishes itself from siblings: search 'returns prices' but 'a search price is not a promise', and a quote on a booked job 'is the change modify commits', separating it from search, modify, hold and book.
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 concrete routing rules: pass transaction_id to re-quote the same job for its next version; call discover first to see each service's inputs; use inputs.addons for package-priced services; and it explains the search-vs-quote distinction. When-not conditions are also stated (ended jobs start a new job; business-declined jobs are refused).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get your own key, no human needed. Send agent_name (what your agent is called), owner_label (the plain name business owners will see next to a job, 1-40 characters) and contact_email. The key (ct_live_...) is in the answer ONCE: keep it and send it as Authorization: Bearer . Starter limits: 30 requests a minute, 3 open holds, 5 bookings a day; the email sent to contact_email carries a link that raises them to 60 a minute, 10 holds, no daily cap, and your key page (usage, rotate, revoke). 3 keys a day per address. The demo key needs no registration.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_name | Yes | 1-60 characters. | |
| notify_url | No | Optional: an https address of yours. CommonTape POSTs a signed push notice there when one of your jobs is declined, called off, booked on the owner's yes or runs out. The signing secret comes back once, as notify_secret. | |
| owner_label | Yes | The plain name owners see, 1-40 characters. | |
| contact_email | Yes | A working address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the entire burden and does so well: it discloses that the key is shown once and must be kept, the exact auth header format, concrete rate limits (30/min, 3 holds, 5/day), how email verification raises them, a 3-keys-per-day-per-address cap, and that notify_secret is returned once. This is exactly the operational context annotations would otherwise provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The key-issuance fact and the auth format are front-loaded, and the dense sentences on limits and verification each carry real information. It reads slightly run-on and crammed, but nearly 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 explain return values — and it does: the key appears once in the answer, plus notify_secret for push. Combined with limits, the limit-increase path, and the key-management page, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters including notify_url are already documented, making 3 the baseline. The description adds light context for owner_label ('the plain name business owners will see next to a job') and agent_name ('what your agent is called'), but omits notify_url entirely and mostly echoes schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific outcome — 'Get your own key, no human needed' — for a self-serve registration tool, which is clearly distinguishable from transactional siblings like book, hold, and cancel. It stops short of a clean 'registers an agent and issues a key' verb+resource framing, but intent is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It communicates the self-serve context ('no human needed') and gives an explicit exclusion: 'The demo key needs no registration,' steering agents away when a demo key suffices. It does not explicitly state this must be called before the other tools, so it falls just short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start here. Every result carries trust (facts with who vouches for each and until when, lapsed facts, the job record); trust never changes the order, the price, who is eligible or what needs approval. A search result is not a promise: prices and windows are as of availability_checked_at, and only a booked job is committed. Every business line carries facts_confirmed_at (when its owner last confirmed its facts: a save, CommonTape's switch-on or a Yes on the daily email; null if never), stale (true when that is more than 7 days ago or never) and stale_reason in plain words; a stale business ranks after fresh ones (order_keys: outcome, freshness, nice_met, price, rotation). Describe the cleaning job once and get the businesses that can do it: matches (each with one exact price or a needs list, a quote_token and bookable windows, so you can go straight to hold) needs_more (businesses that take the job but whose price needs something the job did not state: a needs list and a plain why) owner_must_quote (businesses that take the job but whose owner quotes it: a plain why, no price, nothing to hold) and near_misses with the reasons they missed (each a plain code and a label). Each match carries booking_authority: auto (books on its own) or approval_required with its reasons (owner_approves_every_job, over_auto_book_limit, business_not_listed, special_request, or the ask-first key); outcome conditional = approval is needed for something the customer asked for, and book returns pending_approval. book may still ask when it said auto (the owner tightened the setting), never the reverse. It is the business's say-so only: your customer's permission to book or spend is yours to keep. Never assume a business does something not in its answer. Anything not on the word list goes in special_requests as plain text. Job conditions go in inputs.conditions (cond.same_day cond.next_day cond.weekend cond.evening cond.holiday cond.pets cond.no_free_parking cond.stairs_no_lift cond.very_dirty cond.nobody_home cond.mould cond.infestation cond.post_construction cond.gated_entry cond.lockbox_entry): each adds the business's charge, adds nothing, needs the owner's approval, or is not taken (the business is then a near-miss, condition_not_taken). A business is never sent a home it does not take (kind, bedrooms, size, bathrooms, floors). Words: task.floors task.dusting task.bathrooms task.kitchen_surfaces task.trash task.mirrors task.appliance_exteriors task.microwave_interior task.make_beds task.change_linen task.fridge_interior task.oven_interior task.cabinets_interior task.cabinet_fronts task.closets_interior task.baseboards task.doors_frames task.walls_spot task.light_fixtures task.vents task.windows_interior task.window_tracks task.blinds task.tile_grout task.upholstery task.pet_hair task.dishes task.laundry task.organizing task.balcony task.garage task.carpet_shampoo task.post_construction_dust brings.supplies brings.vacuum brings.mop brings.steam_cleaner brings.carpet_machine brings.ladder brings.high_reach brings.industrial_vacuum product.eco_friendly product.fragrance_free product.pet_safe product.uses_customer_products product.bleach_free product.hypoallergenic crew.solo crew.two_or_more crew.three_or_more pay.cash pay.card pay.bank_transfer pay.app pay.check invoice.receipt invoice.person invoice.company. Word list version 6. Each business line says availability_source (owner_stated, or calendar_feed when the business lets CommonTape read its own calendar: busy times are never offered) and calendar_checked_at.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | Yes | The customer's 5-digit US ZIP | |
| scope | No | The rooms the job covers: leave_out (rooms not to clean) or clean_only (the only rooms to clean), never both, by space.* key. Under a by_rooms price a room left out comes off the price; other prices do not change. Echoed on every answer and shown to the owner. | |
| inputs | No | The job's price inputs: hours, people, frequency, conditions, and bedrooms, bathrooms, square_feet when not stated in property. Each service uses only what its price needs. | |
| must_not | No | Tasks to leave out, a way to pay the customer cannot use, or crew.solo. | |
| property | No | The home, stated once with the words at /api/v1/taxonomy/house_cleaning (property). Unknown or unclear words are refused with the word meant or the question to ask. Bedrooms, bathrooms (when there is no half bathroom) and square feet feed each price that uses them; no need to repeat them in inputs. A by_rooms price and a fixed price's limits read property.spaces only (state every kind the price counts, 0 included; a living area is living + family + formal living rooms). | |
| arrive_by | No | Optional. The latest start: a date and time like 2026-10-09T10:00 (wall clock in the job ZIP's time zone, the business's zone) or with an offset (2026-10-09T14:00Z). Only windows that start by then are offered; none left is a near miss no_window_fits. Refused: a time that does not exist (clocks going forward), the past, more than 60 days ahead. | |
| finish_by | No | Optional. The latest finish, written like arrive_by: a window is offered only if it starts early enough to end by then (window start plus job_hours, else the window's end). After arrive_by when both are sent. | |
| max_total | No | Optional. The most the customer will pay in all, in dollars (travel and extra charges included). A priced business above it is a near miss over_max_total with the gap in dollars; a window whose own day or hour charge would take the price over it is left out; a business with no price yet (needs_more, owner_must_quote) is listed with max_total not_checked in statuses. | |
| must_have | No | Words the business must offer, e.g. task.fridge_interior, pay.card. Tasks at extra cost, or done only inside a package, are priced in. | |
| service_key | No | house_cleaning.standard | house_cleaning.deep | house_cleaning.move_in_out. Omit to consider all three. | |
| customer_ref | No | Optional. Your own label for your customer, so two customers with the same job are not the same job. Never shown to the owner. | |
| nice_to_have | No | Words that rank a business higher but never exclude it. | |
| special_requests | No | Up to 5 plain-text requests not on the word list. Always needs the owner's approval. | |
| id_to_security_hours_before | No | Optional, with cond.id_to_security in inputs.conditions. How many hours before the job the building wants each cleaner's name and photo ID (1 to 168). A business that can send them at least this far ahead meets it; one that cannot is a near miss id_notice_too_short; one that has not said is not_said in statuses. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discharges it: trust semantics, staleness ranking and order_keys, booking_authority values and approval reasons, condition handling (charge/approve/not-taken/near-miss), availability_source and calendar_checked_at, and near-miss codes. This is unusually rich behavioral disclosure for a mutation-free read 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?
It is a single dense block of ~900 words with the vocabulary lists jammed into running prose and the purpose buried after metadata discussion. Front-loading is poor and structure (no lists, no sections) makes it hard to parse, though much of the content is genuinely necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter, nested-schema tool with no output schema, the description covers result shape, statuses, ranking keys, and failure codes thoroughly. Minor gaps remain around the end-to-end flow beyond search→hold→book, but overall an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the full word list for task.*, brings.*, product.*, crew.*, pay.* and invoice.* keys that the schema only alludes to, plus the behavior of conditions, special_requests and max_total. It goes beyond restating 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 second paragraph gives a specific verb+resource: 'Describe the cleaning job once and get the businesses that can do it,' and enumerates the result buckets (matches, needs_more, owner_must_quote, near_misses). However, the opening sentences ('Start here. Every result carries trust...') describe metadata rather than the tool's purpose, so the actual purpose is delayed, and no sibling (quote, discover, status) is named for contrast.
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?
'Start here' is explicit entry-point guidance, and it says a match lets you 'go straight to hold.' It also flags that book may still ask for approval when it said auto. But it never contrasts itself with quote, discover, or status, so alternative selection is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The authoritative state of one of your jobs and everything needed to act on it: the job (current version), price, quote, window, approval (what needs the owner's yes and why: reasons, the deadline, what happens at it), commitment (who committed the booking: the owner's rule or the owner; your call is your assertion for your customer), decline (reason, code, next_actions, next_available), completion (who marked it done), cancellation (who, when, why, no fee), receipt (what was booked, from the record, with a plain text confirmation for your customer), recovery on supplier_cancelled (the job to search again with), versions, and allowed_actions / next_actions. Never the customer's details. A dead end reached in the last 24 hours (declined, expired, cancelled because the business stopped taking jobs, supplier_cancelled) carries alternatives and if_changed, kept up to 60 seconds (alternatives_worked_out_at). Every answer carries state (one of quote_incomplete, quoted, held, pending_approval, booked, completed, declined, cancelled, supplier_cancelled, expired), allowed_actions and next_actions; every error carries a code and next_actions. quote_incomplete: Not priced yet: the job needs more facts. needs says which. Nothing is held. Allowed: quote. quoted: An exact price for one exact job version, until expires_at. Nothing is held: the time is not reserved yet. Allowed: hold, quote. held: A time is reserved for this job until hold_expires_at. Book it, or cancel to let it go. Allowed: book, cancel. pending_approval: Asked to book; the owner must say yes by approval.deadline. The time stays reserved while waiting. No answer by then and the job expires and the time is released. Allowed: status, cancel. booked: The owner is committed to do this job at this price and time. Allowed: status, quote, modify, cancel. completed: The job was done. completion.source says who marked it: the owner (merchant) or CommonTape after the window ended (system). Allowed: status. declined: The owner said no. decline.reason says why; decline.next_available is the next open time when there is one. Allowed: status, quote. cancelled: Called off by the agent. The time was released. Allowed: status, quote. supplier_cancelled: Called off by the owner after it was booked. The job can be quoted again elsewhere from job. Allowed: status, quote. expired: Ran out of time: the quote passed expires_at, or the hold or the owner's answer passed its deadline. The time was released. Allowed: status, quote.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | transaction_id from quote or hold |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so extensively: it defines every state, its meaning, allowed actions, deadlines, what happens at deadlines, error formats, retention of alternatives (60 seconds), and that customer details are never included. This is rich behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and uses semicolons and lists to organize a large amount of detail. However, it remains a single dense paragraph that could be more scannable with structured formatting, and some sentences are very long.
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 thoroughly documents return values, state meanings, allowed actions, and error formats. It appears complete for the tool's complexity, providing all necessary context for an agent to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter transaction_id is fully documented in the schema. The description adds no additional meaning about the parameter, 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 purpose: 'The authoritative state of one of your jobs and everything needed to act on it,' and enumerates all returned components (price, quote, window, approval, etc.). Clearly distinguishes from action-oriented siblings (book, cancel, quote) by focusing on state retrieval and allowed actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by detailing what the tool returns and the allowed actions per state, but never explicitly says when to use this tool versus alternatives like quote or book. No exclusions or when-not guidance are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The fixed word list (version, groups, every key with its label and synonyms) agents use to describe a job and a home. Public, no key; the same answer as GET /api/v1/taxonomy/house_cleaning. Word list version 6.
| Name | Required | Description | Default |
|---|---|---|---|
| vertical | No | Only house_cleaning today. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that access is public with no key required, that the content is fixed (static, not user-scoped), that it is versioned ('Word list version 6'), and it even names the equivalent HTTP endpoint. It does not mention rate limits or content-type, but the auth and stability profile an agent most needs is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with what the resource is before the access and endpoint details. The parenthetical inventory of contents is slightly rambling, but every clause carries information an agent can use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-auth, zero-required-parameter lookup with no output schema, the description covers the important ground: contents of the payload, access model, stability, and version. The main omission is guidance on how the returned keys should be used downstream, which is a minor gap for a reference-lookup 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 description coverage is 100% and the single vertical parameter is a const with its own explanation, so the baseline is 3. The description adds only a mild reinforcement by citing the house_cleaning-specific endpoint; it introduces no syntax or value guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource concretely (a fixed word list of version, groups, keys with labels and synonyms) and states its role: the vocabulary agents use to describe a job and a home. That is enough to separate it from siblings like book, quote, or search. It lacks an explicit verb such as 'retrieve', so it reads as a noun phrase rather than a stated action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied — an agent infers it should call this to obtain the valid key vocabulary before describing a job or home. There is no explicit when-to-use, when-not-to-use, or comparison against siblings such as search or discover, which might also surface vocabulary.
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.
register1 field changedInput schema / properties / notify_urlAdded value: +{
+ "description": "Optional: an https address of yours. CommonTape POSTs a signed push notice there when one of your jobs is declined, called off, booked on the owner's yes or runs out. The signing secret comes back once, as notify_secret.",
+ "type": "string"
+}search4 fields changedInput schema / properties / arrive_byAdded value: +{
+ "description": "Optional. The latest start: a date and time like 2026-10-09T10:00 (wall clock in the job ZIP's time zone, the business's zone) or with an offset (2026-10-09T14:00Z). Only windows that start by then are offered; none left is a near miss no_window_fits. Refused: a time that does not exist (clocks going forward), the past, more than 60 days ahead.",
+ "type": "string"
+}Input schema / properties / finish_byAdded value: +{
+ "description": "Optional. The latest finish, written like arrive_by: a window is offered only if it starts early enough to end by then (window start plus job_hours, else the window's end). After arrive_by when both are sent.",
+ "type": "string"
+}Input schema / properties / id_to_security_hours_beforeAdded value: +{
+ "description": "Optional, with cond.id_to_security in inputs.conditions. How many hours before the job the building wants each cleaner's name and photo ID (1 to 168). A business that can send them at least this far ahead meets it; one that cannot is a near miss id_notice_too_short; one that has not said is not_said in statuses.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Input schema / properties / max_totalAdded value: +{
+ "description": "Optional. The most the customer will pay in all, in dollars (travel and extra charges included). A priced business above it is a near miss over_max_total with the gap in dollars; a window whose own day or hour charge would take the price over it is left out; a business with no price yet (needs_more, owner_must_quote) is listed with max_total not_checked in statuses.",
+ "type": "number"
+}bookcanceldiscoverholdmodifyquoteregistersearchstatustaxonomyFind, get quotes from and book local service businesses on their own Square or Google calendar.
Agent-first booking of home-service contractors in Canada and the US: quotes, availability, booking.
Find and book local service businesses (plumbers, HVAC, detailers) at real prices, with approval.
Quote and invoice PDFs, cleaning prices, sales tax and leaf blower rules for US service businesses
Add one secure layer between your agents and this server.