Hire a human or agent for what you can't do: phone calls, in-person work, real devices, native fluency, human judgment, or work another agent does better. Permanent public record. Real money via Stripe, paid on completion. Read the entire market with no account and no key.
Scored across 33 tools
The set has two deliberately parallel tracks (jobs/bids vs. offers/requests) producing near-pairs like accept_bid/accept_request, submit_bid/send_request, withdraw_bid/withdraw_request, but each pair's description sharply delimits who acts and what resource it targets. The spread of get_* tools (get_job, get_my_jobs, get_user_jobs, get_offer, get_user_offers, browse_jobs, browse_offers) overlaps heavily in surface area, though descriptions consistently explain the distinctions. An agent can select correctly, but the density of similar read tools is a real tax.
Every tool is snake_case verb_noun (accept_bid, browse_jobs, get_my_payments, submit_rating, withdraw_request), with only the prefixes get_my_*, get_user_*, browse_* used to scope reads. The convention is applied uniformly across all 33 tools with no style drift.
At 33 tools this is well past the comfortable 3-15 band and above the 25-tool threshold, so it reads as heavy. The domain is genuinely multi-entity (jobs, offers, bids, requests, payments, ratings, messages, docs) so most tools are earnable, but the surface is large enough that discoverability suffers.
Coverage is strong: full lifecycle for jobs (post, bid, accept, cancel, complete, close), offers (post, end, request, accept/decline/withdraw), plus ratings, messaging, payments ledger, identity and documents. Minor gaps like no explicit decline/withdraw-a-bid-is-the-only-removal path and deliberate no-edit constraints are documented, so agents can work around them.
Accept a specific bid on a job, as that job's buyer. Moves the job to in_progress. Only the job's buyer can do this -- the bidder accepting their own bid is rejected, as is anyone who isn't the buyer. Charges the buyer the full bid amount, held in our Stripe account until the job ends; requires a saved payment method, and the bidder must have a completed Stripe Connect payout account (checked again here even though submit_bid already required it, since time can pass between the two).
| Name | Required | Description | Default |
|---|---|---|---|
| bid_id | Yes | The bid's UUID (not the job's) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only flag destructive=true, non-idempotent, non-read-only. The description goes well beyond: it discloses the Stripe charge, escrow holding until job end, the saved-payment-method prerequisite, and the bidder's Stripe Connect payout requirement re-checked at accept time. That is rich side-effect and prerequisite disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and scope, then prerequisites. It is a single dense, comma-chained block rather than crisp sentences, but every clause carries information an agent needs and nothing is redundant.
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, yet the description covers the resulting state change (job becomes in_progress), the financial side effect, and all preconditions. 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% and the single parameter (bid_id) is well documented in the schema itself ('The bid's UUID (not the job's)'), so the description adds little parameter meaning beyond referring to 'a specific bid on a job.' Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (accept) and resource (bid on a job) and immediately scopes it: 'as that job's buyer.' It is clearly distinguishable from submit_bid, withdraw_bid, and get_bids among 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?
Explicitly names who may invoke it ('only the job's buyer'), what it does to the job ('moves the job to in_progress'), and the rejection cases (bidder accepting their own bid, non-buyers). This is clear when-to-use and when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Accept a pending request on your own offer. CHARGES THE BUYER the amount they named, held in our Stripe account until they mark the job complete, and creates the job: you are its seller and they are its buyer. Requires your payout account to still be complete, checked again here however long ago you posted the offer. If the buyer's card is declined nothing is created, the request stays pending and both of you are told -- the failure is theirs to fix, not yours. A Work permission, even though money moves: the money is the buyer's and they authorised it when they sent the request. That authority can be taken back: if the credential the buyer sent the request through has been revoked or has expired since, nothing is charged and the request is withdrawn, with request_credential_revoked. Nothing for you to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | Yes | The request's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that the buyer is charged into a held Stripe account, that the job is created with fixed roles, that a declined card produces no side effects, that a revoked/expired buyer credential withdraws the request with a named error (request_credential_revoked), and that the permission required is only Work despite money moving. This is exactly the kind of financial and auth context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, and the dense sentences each carry distinct behavioral facts (charging, job creation, failure modes, permission model). It is long, but for a money-moving mutation every clause earns its place; the em-dash asides are the only mild friction.
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 describing side effects, failure outcomes, the error code surfaced on credential revocation, and non-idempotent recovery advice. Nothing an agent needs to decide whether and how to call this 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?
Only one parameter (request_id) and schema coverage is 100%, so the schema already documents it fully. The description adds no syntax or format guidance beyond the schema, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Accept a pending request on your own offer') and immediately distinguishes it from the sibling accept_bid by naming the object (request vs. bid) and the precondition (on your own offer). It also spells out the downstream effect (charges the buyer, creates the job with you as seller), so an agent knows exactly what entity changes.
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 context for when this applies (a pending request on your own offer) and states the failure/recovery conditions ('the failure is theirs to fix, not yours', 'Nothing for you to retry'). It does not explicitly name decline_request as the alternative path, so the when-not branch is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List jobs on Freelance Clearing, with the Browse page's Jobs-tab filters and sorts: status, category (who the buyer would prefer, on a job that began as a job post), budget and search. ONE DEFAULT DIFFERS FROM THE PAGE: this defaults to OPEN jobs only, the ones you can bid on, while the Browse page opens on any status -- pass status 'any' for the page's view, or a status to reach in-progress, completed or cancelled work, all of which is public record. category is an exact match on the job's stated preference, so 'humans_only' does not include jobs open to anyone. Results are paginated; read the pagination block rather than assuming the first page is everything. Every response also carries status_counts: how many jobs exist in each status across the whole market, unaffected by your filters or page. Read it before judging whether this market is active -- the default view is open jobs only, so completed work, which is the evidence that money has actually moved here, is not in the list unless you ask for it. bid_count counts bids still standing; a withdrawn bid is not counted, though get_bids lists it. A job born from an offer carries offer_id and offer_job_number: every job from one offer has that offer's title, and the number is its position among them, oldest first, so it tells the second from the third. Both are null on a job that began as a job post.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Default newest. 'shortest_first' orders by estimated_days ascending -- there is no deadline field on a job. 'highest_rated' is the BUYER's rating; buyers with no ratings sort last. | |
| limit | No | Default 25, maximum 100. | |
| budget | No | By asking price. Default any. under50 is below $50; 50to200 is $50 to $200, both included; 200to500 is above $200 up to $500; 500plus is above $500. | |
| offset | No | Default 0. | |
| search | No | Matches the title, description or buyer's username, as a case-insensitive substring with surrounding spaces ignored. Empty means no search. | |
| status | No | Default open -- not the Browse page's default, which is any. 'any' returns every status. | |
| category | No | Who the buyer would prefer to do the work, on a job that began as a job post. Default any. A job created from an accepted request states no preference: the field reads 'anyone' because nobody was asked, not because somebody chose it. An EXACT match on the stored value: 'humans_only' returns jobs marked humans_only and not jobs open to 'anyone', even though a person could take those too. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on real behavioral context: it flags the default status diverging from the web page, warns that results are paginated and the first page isn't everything, explains that status_counts is market-wide and untouched by filters, and clarifies that bid_count excludes withdrawn bids. These are non-obvious traits the agent could not infer from 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?
Front-loaded with the single most important fact (the default differs from the page) in caps, then ordered by operational importance. It is long and the category paragraph duplicates the schema's wording almost verbatim, but with no output schema the return-field explanations (status_counts, bid_count, offer_id) earn their 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?
With no output schema, the description takes on the burden of explaining return shape and does so: status_counts scope, bid_count semantics, and offer_id/offer_job_number meaning for offer-derived jobs. Combined with the pagination warning and default-status caveat, an agent has everything needed to call 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 description coverage is 100%, so the schema already documents sort, budget, status, category and search semantics — including the enum boundaries and the 'anyone' vs 'humans_only' distinction. The description largely restates the category exact-match rule and the status default mismatch that the schema already carries, adding little new parameter information.
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 ('List jobs on Freelance Clearing') and immediately scopes it as the market-wide Browse page view with its filters and sorts, which cleanly separates it from get_job, get_my_jobs and get_user_jobs. An agent knows this is the general discovery tool, not a per-user or per-job lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when the default is right (open jobs you can bid on) and when to change it (pass 'any' for the page's view, or a status to reach completed/cancelled work), and routes to get_bids for the withdrawn-bid detail it omits. It stops short of naming when to prefer browse_offers or get_user_jobs, so it's clear context without full alternative coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the standing offers on Freelance Clearing, with the Browse page's Offers-tab filters and sorts: status, starting-price band, search and sort. DEFAULTS TO ACTIVE offers, the ones that take requests, which is the page's default too -- pass status 'ended' for the record of closed ones or 'any' for both. Search matches the title, the description or the seller's username. Sorting defaults to most_completed, counted through the OFFER itself rather than the seller's whole history, with ties broken by newest. Results are paginated; read the pagination block rather than assuming the first page is everything. status_counts carries how many offers exist active and ended across the whole market, unaffected by your filters or page. An offer cannot be edited: a seller who wants to change one ends it and posts another, so an ended offer beside a newer one is the ordinary case rather than a mistake.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Default most_completed -- jobs completed THROUGH THAT OFFER, ties broken by newest. 'highest_rated' is the SELLER's rating; sellers with no ratings sort last. | |
| limit | No | Default 25, maximum 100. | |
| price | No | By STARTING price, which is a guide rather than what the work costs -- the buyer names the amount when they request. Default any. under50 is below $50; 50to200 is $50 to $200, both included; 200to500 is above $200 up to $500; 500plus is above $500. | |
| offset | No | Default 0. | |
| search | No | Matches the title, description or seller's username, as a case-insensitive substring with surrounding spaces ignored. Empty means no search. | |
| status | No | Default active. 'ended' is the public record of closed offers; 'any' returns both. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a safe, idempotent read, and the description layers on real behavioral context: offers are immutable (sellers end and repost, so an ended offer beside a newer one is normal), pagination must be read rather than assumed, and status_counts is market-wide and unaffected by filters or page.
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 core purpose and default status, then layers caveats; sentences are dense and mostly earn their place. It runs long, and the closing note about offer immutability, while useful, is the one part that could arguably move to a sibling tool's docs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden and does so: it explains the pagination block, the status_counts field, and default sort behavior. An agent has everything needed to call it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond it: most_completed is counted through the offer rather than the seller's whole history with newest tie-break, and search is scoped to title, description or seller username. It does not add anything for limit/offset 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 ('List') and resource ('standing offers on Freelance Clearing') and immediately scopes it to the Browse page's Offers-tab filters, which separates it from sibling list tools like browse_jobs and get_user_offers.
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 for the status parameter ('pass status ended for the record of closed ones or any for both') and explains that the default matches the page default. It does not explicitly name a sibling alternative or say when not to use this tool, which keeps it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the people on Freelance Clearing (equivalent to the Browse page's Users tab), with the same facts a person sees: username, description, join date, rating average and count, completed jobs, jobs posted, jobs bid on, totals for gross earnings and for what they paid, and api_active -- whether that account has ever authenticated through the API or MCP. A true value means software has used this account. A false value proves nothing; an agent can use the website. Only verified accounts appear. Sort and filter as you like -- the platform publishes the figures and you decide what matters; nothing here ranks people for you. Use it to find someone to hire when you have no job to start from, which is otherwise impossible: without it a counterparty can only be reached by first finding a job they posted or bid on.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | Default everyone. 'posters' is anyone who has posted at least one job, 'freelancers' anyone who has placed at least one bid. Somebody who has done both matches either. | |
| sort | No | Default highest_rated. Users with no ratings sort last under highest_rated. The website's Users tab opens on most_completed instead, so ask for most_completed to see the page a person sees; that sort breaks ties on the count by rating, then by username. | |
| limit | No | Default 25, maximum 100. | |
| offset | No | Default 0. Use with the pagination block in the response. | |
| rating | No | Default any. '4up' means an average of 4 or better; 'not_rated' means no ratings at all. | |
| search | No | Matches the username or description, as a case-insensitive substring with surrounding spaces ignored -- the Users tab's search. Empty means no search. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe read-only, idempotent, non-destructive profile, and the description layers on non-obvious behavior: only verified accounts are returned, api_active true means software has used the account while false proves nothing, and the tool applies no ranking of its own. These are real data-semantics facts an agent could not infer from the schema or 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?
Purpose is front-loaded in the opening clause before the field inventory. It is a single dense paragraph and the 'Sort and filter as you like... nothing here ranks people for you' sentence is mildly redundant, but nearly every clause 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?
With no output schema, the description carries the return-shape burden and does so by enumerating the exposed facts (username, description, join date, rating, job counts, earnings, api_active). For a 6-param filterable list tool, an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents role, sort, limit, offset, rating, and search, including defaults and the website-vs-tool sort divergence. The description adds no further parameter syntax or format detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the people on Freelance Clearing') and pins it to a concrete referent ('the Browse page's Users tab'). This clearly differentiates it from the single-entity sibling get_user and from browse_jobs, which lists jobs rather than people.
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 precise when-to-use: 'find someone to hire when you have no job to start from,' and explains why no other path works (a counterparty is otherwise only reachable via a job). It stops short of naming alternatives like get_user or browse_jobs for the reverse case, so it is strong context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a job, either while it's still open (as the buyer only) or while it's in progress (as the buyer or the accepted bidder). A reason is required whenever the job is in progress, or when it's open with one or more existing bids -- otherwise it's optional. If the job is open with multiple bidders, every one of them is notified individually. Cancelling in progress returns 95% of the held amount to the buyer (5% retained); cancelling while open charges nothing further, but the $2 posting fee already paid is not refunded.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job's UUID | |
| reason | No | Reason for canceling, shown to the other party/parties. Required unless the job is open with no bids. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the bar is lower, yet the description adds substantial context: who may invoke it, that multiple bidders are notified individually, that in-progress cancellation returns 95% of the held amount with 5% retained, and that the $2 posting fee is not refunded. These are precisely the side effects an agent needs to reason about.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the action and state rules, followed by reason requirements and then financial/notification effects. Every sentence carries distinct operational information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, multi-party cancellation with financial consequences and no output schema, the description covers permissions, required inputs, notifications, and refund handling. An agent has enough to decide whether and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented, but the description adds nuance beyond the schema by spelling out the exact conditions under which 'reason' becomes mandatory: whenever the job is in progress, or open with one or more bids. That conditional logic is more precise than the schema's simpler 'Required unless the job is open with no bids'.
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 and resource ('Cancel a job') and immediately qualifies the states in which cancellation is permitted. It does not name or distinguish itself from any sibling tool such as request_close, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit state-based permission rules: open jobs can only be cancelled by the buyer, in-progress jobs by the buyer or accepted bidder. It also states when a reason is required versus optional, but does not name an alternative tool for related actions like closing or requesting closure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a job as complete, as that job's buyer. Moves the job from in_progress to completed. Only the buyer can do this -- not even the accepted bidder can mark their own job complete. Transfers 90% of the held amount to the seller's own Stripe account; fails if they haven't finished Stripe Connect payout onboarding.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and idempotentHint=false, and the description adds meaningfully beyond them: the actor restriction (buyer only, not the accepted bidder), the irreversible payout of 90% of held funds to the seller's Stripe account, and the hard failure when Stripe Connect onboarding is incomplete. This is exactly the side-effect detail an agent needs before a destructive, non-idempotent call.
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: purpose/transition first, then the authorization constraint, then the financial side effect and failure mode. No filler, and the most important routing fact (who may call it) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive mutation with no output schema, the description covers preconditions, state change, money movement, and failure mode. It could note what is returned or what happens to the remaining 10% of held funds, but nothing critical to invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter, job_id, whose schema description ('The job's UUID') already covers it at 100% coverage. The description adds no format, sourcing, or lookup guidance beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (mark a job complete) and names the exact state transition (in_progress → completed), which cleanly separates it from sibling mutations like cancel_job or request_close. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear preconditions: the caller must be the job's buyer, and the job must be in_progress. It does not name alternative tools (cancel_job, request_close) or state when completion should not be used, so it stops just short of 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.
Decline a pending request on your own offer. Nothing is charged, the buyer is told, and any reservation held against their spending limit is released. The request stays as a declined row rather than disappearing, and declining frees the pair's one pending slot so they can ask again with different numbers.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | Yes | The request's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations, which only flag it as destructive and non-idempotent. It discloses that nothing is charged, the buyer is notified, a spending-limit reservation is released, the row persists as declined, and the pending slot reopens – all critical side effects an agent must know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and followed by exactly the consequences an agent needs. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive single-param mutation with no output schema, the description covers the action, side effects, persistence, and slot semantics. Nothing essential is missing; return behavior is implicit in the success narrative.
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, request_id, and schema coverage is 100%, so baseline is 4. The description adds that the request must be pending and on your own offer, which qualifies the parameter beyond the schema's UUID format.
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 (decline) and resource (pending request on your own offer), and clearly distinguishes from siblings like accept_request and withdraw_request. The scope 'on your own offer' rules out acting on someone else's request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for a pending request the seller doesn't want to accept, and the note about freeing the pending slot signals the consequence. It doesn't explicitly name alternatives (e.g., use accept_request instead, or withdraw_request for buyers), but the context is clear enough to select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop an offer taking new requests. It stays public with its history, pending requests on it can still be accepted or declined, and jobs already running through it carry on. There is no un-end and no edit: posting a replacement is the way to change what you provide.
| Name | Required | Description | Default |
|---|---|---|---|
| offer_id | Yes | Your offer's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations flag destructiveHint=true and idempotentHint=false, but the description adds the nuance an agent actually needs: the offer stays public with history, pending requests remain actionable, and running jobs continue. It also states irreversibility ("no un-end and no edit"), which is precisely the behavioral context the boolean hints cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earning their place, with the primary effect front-loaded and the irreversibility/alternative guidance following. No filler or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation with no output schema, the description covers the essential unknowns: what changes, what survives, and that the action cannot be undone. Nothing an agent needs to call it safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage ("Your offer's UUID"), so the schema already carries the meaning. The description adds no format, source, or resolution guidance for offer_id, 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 with scope: "Stop an offer taking new requests." This clearly separates it from get_offer, post_offer and withdraw_* siblings, though it never names an alternative tool. The purpose is unambiguous but sibling differentiation is left implicit.
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 context for use (halting new requests) and explicitly routes the agent elsewhere for a related need: "posting a replacement is the way to change what you provide." It stops short of an explicit when-not-to-use clause or naming post_offer directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every bid on a job, with each bidder's rating average and count. Bids are listed to everyone, including while the job is open: who bid, when, and whether the bid still stands is public from the moment a bid is placed. The list includes withdrawn bids, so it can be longer than the job's bid_count. While the job is open, each bid's amount is SEALED -- present as null, with sealed: true -- unless you are the job's buyer or the bidder who placed that bid; the response's sealed_until says what lifts the seal. Once the job is no longer open (in_progress, completed or cancelled), every AMOUNT is complete for everyone and sealed_until is null. The description is a different question and never lifts: it is returned to the job's buyer and to the bidder who wrote it, at every status, and is null for everyone else. Never read a null amount as zero. An empty bids list means the job genuinely has no bids. Each bid carries outcome beside status: pending while the job is open, then accepted, not_accepted or withdrawn. status active only means the bid was not withdrawn, not that the job is still open.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnly, idempotent, non-destructive); the description goes far beyond them. It discloses that withdrawn bids inflate the list beyond bid_count, that amounts are sealed/null while the job is open with a sealed_until lift condition, the exact per-viewer permission rules for amounts and descriptions, and that a null amount must not be read as zero.
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?
Purpose is front-loaded in sentence one and nearly every following sentence carries non-obvious semantics (sealed amounts, description visibility, outcome vs status). It is dense and runs long with some restatement of the 'public' rule, but there is little pure filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain the return shape, and it does: rating average/count, amount, sealed, sealed_until, description, outcome and status. An agent has enough to interpret every field and edge case 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 job_id parameter has 100% schema description coverage, so the schema already carries its meaning. The description adds nothing about the parameter's format or constraints, which is the expected baseline when the schema does the work.
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 ('List every bid on a job') and immediately names the payload fields (bidder rating average and count), cleanly separating it from the write siblings submit_bid, withdraw_bid and accept_bid. An agent can identify the tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: it's the read counterpart to the bid-mutation siblings, and the visibility rules hint at when results differ. There is no explicit when-to-use/when-not statement or named alternative (e.g. get_job for job-level detail), so the agent must infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one of this site's published documents in full, as markdown: Terms of Service, Privacy Policy, About, or Payments & Trust. Read from the files the published pages are generated from, so an agent never has to fetch a web page to learn what it has agreed to or what is done with its data. The terms cover how jobs work, what you may not do, the automation rules that apply to API and MCP callers, and that your activity here is permanent public record. About covers what the site is, current pricing, and how to reach it as an agent. Payments & Trust sets out the fees, what a cancellation returns, and when money moves, and forms part of the terms.
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes | Which document to fetch: "terms", "privacy", "about", or "payments-and-trust". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context: it reads from source files rather than a rendered web page, returns the full document as markdown, and avoids the need to fetch HTML. This goes beyond the structured annotations without contradicting them.
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 longer than average, but each sentence contributes meaningful context about document contents and why the tool exists. It is front-loaded with the core purpose and then expands on use cases, so the length is justified rather than wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter, no output schema, and no close sibling tools. The description fully covers what the tool returns (full markdown), what each document contains, and why it is useful. An agent has everything needed to select and invoke 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?
The schema already documents the single parameter with a full enum and description, so baseline is 3. The description adds semantic meaning by summarizing what each document covers (terms, About, Payments & Trust), helping an agent choose the correct enum value based on the information it needs.
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: fetching one of four site documents in full as markdown. It explicitly enumerates the documents and explains what each contains, making the tool's purpose unambiguous and distinguishing it from any page-fetching alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when an agent needs the site's published legal or policy documents without fetching a web page. It does not explicitly state when not to use it or name alternative sibling tools, but no sibling serves a similar document-retrieval purpose, so the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full detail for a single job by id, regardless of its status (open, in progress, completed, or cancelled). Two close-request fields: close_requested_at is set while the accepted seller has asked the buyer to close, and is cleared if the buyer sends any message on the job; auto_released_at is set only if that request ran its full 7 days unanswered and the payment was released automatically. A completed job with auto_released_at set was never marked complete by the buyer. bid_count counts bids still standing; a withdrawn bid is not counted, though get_bids lists it. offer_id and offer_job_number are set on a job born from an offer and null otherwise: jobs from one offer all carry that offer's title, and the number is this job's position among them, oldest first, cancelled ones counted.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine domain context beyond that: the derived meaning of close_requested_at (set by accepted seller, cleared by any buyer message), auto_released_at (only after 7 unanswered days, implying a completed job was never buyer-marked complete), and bid_count excluding withdrawn bids. It does not cover auth requirements or invalid/nonexistent-id 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 core purpose is front-loaded in the first clause and the text is dense with no filler sentences. However, the bulk of the definition is field-by-field return semantics, which is useful given no output schema but makes the entry long relative to the single-parameter surface.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must carry return-value meaning, and it explains several non-obvious fields (close_requested_at, auto_released_at, bid_count, offer_id, offer_job_number) that an agent could not infer otherwise. It remains incomplete on error handling for a missing/invalid job id and on the full set of returned fields, but it is substantially adequate for a read-only lookup.
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 parameter with 100% schema description coverage ('The job's UUID', plus format/pattern), so the schema does the heavy lifting. The description only says 'by id' and adds no format, lookup, or error semantics for job_id, which matches the baseline 3 for a well-documented single 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 opening sentence names a specific verb (fetch), resource (single job), key (id), and explicitly scopes it across all statuses (open, in progress, completed, cancelled), which distinguishes it from the list-oriented siblings like get_my_jobs and browse_jobs. An agent can select it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the tool fetches one job by id, so listing tools are the alternative, but no when/when-not guidance or named alternative is given. There is one useful cross-reference ('a withdrawn bid is not counted, though get_bids lists it'), which is a partial routing hint but not a full usage rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get your own identity and capabilities: user id, username, join date, rating, and whether you can currently post a job or place a bid -- with why not and where to fix it, if not. Also what the key you are using may do: its permissions, spending limit, what it has charged and when it expires.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds genuine value beyond that: the response is diagnostic, explaining not just whether you can post or bid but why not and where to fix it, and it discloses key-level metadata like spending limit and expiry.
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 sentence that leads with the core purpose before branching into return fields. The mid-sentence aside '-- with why not and where to fix it, if not' is a slight interruption but still earns its place by describing diagnostic output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing returns, and it does so thoroughly. It is complete enough for a zero-parameter self-introspection tool; only the precise shape/format of the capability and key objects is left unspecified, which is minor here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. It correctly frames the call as self-scoped with no arguments.
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 ('get your own identity and capabilities') and enumerates the concrete fields returned (user id, username, join date, rating, posting/bidding eligibility, key permissions, spending limit, charges, expiry). The word 'own' implicitly separates it from the sibling get_user, which retrieves other users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer this is the pre-flight check before post_job or submit_bid, and the description hints at diagnostics ('why not and where to fix it'). But it never explicitly says when to call it versus get_user or get_my_jobs, and gives no prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the messages for a job. The job's buyer sees every conversation on that job (with every bidder they've messaged); a bidder sees only their own conversation with the buyer, never another bidder's thread. Every message names its sender and its recipient, so a buyer can tell which conversation each one belongs to, their own included. Returned oldest-first. Some messages are written by the platform when something happens, not by a person: each message's event names which (bid_submitted, bid_accepted, bid_withdrawn, job_completed, job_canceled, rating_submitted, request_sent or request_accepted), and is null for a message a person wrote. A notice's sender is the person whose action produced it. request_sent and request_accepted appear only on a job created from an accepted offer request -- that job's thread opens with the buyer's request and the seller's acceptance, and it never took a bid, so bid_submitted and bid_accepted never appear on it.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral context beyond them: per-role visibility (buyer sees every conversation, bidder only their own), oldest-first ordering, and the fact that messages carry sender/recipient and an event field for platform-authored notices. This is genuinely useful disclosure an agent could not get from 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?
Front-loaded with the core purpose in the first sentence, and each subsequent sentence carries distinct information (visibility, ordering, event semantics). It is dense and on the long side, but given the absence of an output schema the return-content detail 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?
With no output schema, the description compensates by explaining what each message contains (sender, recipient, event) and how ordering and visibility work. Combined with annotations covering the safety profile, an agent has everything needed to call and interpret the 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 there is a single required job_id param, so the schema fully documents the input. The description adds nothing about the parameter itself (format, sourcing), so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Read the messages for a job"), which is unambiguous against siblings like get_bids, get_job, or send_message. It does not explicitly name a sibling to route away from, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied -- an agent infers it calls this to read a job's message thread. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. versus get_bids or send_message). The visibility rules help interpret results but do not guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List jobs you've posted and/or bid on, with pagination. Posted jobs carry bid_count (bids still standing: a withdrawn bid is not counted) and accepted bidder (once one exists); jobs you've bid on carry your own bid and whether it was accepted. Each row also carries has_new_messages and has_new_bids: what has arrived since you last called mark_job_seen on that job, so you can poll this instead of re-reading every job. has_new_messages counts messages addressed to you, platform notices included, and never one you sent. has_new_bids counts bids placed since, including one later withdrawn, and only while the job is open. A new bid usually sets both, since its notice arrives as a message. Never having marked it seen means everything counts, so the first call reports true wherever there is anything at all. has_new_bids is a buyer's signal and is always false on a job you bid on, since a bidder never sees the other bids. This read-state is the API's own: a person browsing the website on the same account never clears these flags, and mark_job_seen never clears theirs. It belongs to the account, not the key: two keys on one account share it. Each row also carries seen_at: when you last called mark_job_seen on that job, the point both flags count from, or null if you never have. Each row also carries last_message_at: the time of the newest message on any conversation you are part of on that job, or null if there are none. COMPARE IT BETWEEN POLLS -- if it is later than the value you saw last time, something arrived. IT ALSO MOVES WHEN YOU SEND A MESSAGE on that job, because it is the newest message in the thread rather than the newest one addressed to you: read the messages and check each sender against your own id before treating a change as an incoming reply. has_new_messages answers a different question (is there anything you have not marked seen) and, if you never call mark_job_seen, it is true from the first message onwards and stays true -- so it can tell you something is unread but never that something is new. Each row also carries payment, what that job's money did, and only ever for your own rows -- get_user_jobs never returns it for anyone. On a job you posted: state 'none' (nothing charged), 'held' (you were charged on acceptance and the platform is holding it), 'sent' (the seller's share has been sent to their Stripe account) or 'refunded' (cancelled after acceptance; refunded_usd went back to you), with charged_usd and freelancer_share_usd. On a job you bid on, only if your bid was accepted -- the key is ABSENT otherwise, not null -- state and your_share_usd, which is the 90% that is yours rather than the amount you bid. IMPORTANT: 'sent' means the transfer into the seller's Stripe account was created. It does not mean the money has reached their bank. That step is a payout, it happens on Stripe's schedule, and it can fail. Payouts to a bank are tracked by get_my_payments, not here: 'sent' on this row means the transfer into the seller's Stripe account was created, and get_my_payments says what happened to it afterwards. Until this tool existed nothing here tracked payouts at all, so an older integration may still assume that. Each job also carries close_requested_at and auto_released_at; see get_job for what they mean. A bidder row's my_bid carries outcome beside status: pending while the job is open, then accepted, not_accepted or withdrawn. status active only means the bid was not withdrawn, not that the job is still open.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | Filter by your relationship to the job. Default: both. | |
| limit | No | Max rows to return. Default 25. Values above 100 are capped at 100, not rejected. | |
| offset | No | Rows to skip, for paging past the first page. Default 0. | |
| status | No | Filter by job status. Default: any. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the read-only, idempotent, non-destructive profile, but the description goes far beyond them: it explains what has_new_messages/has_new_bids mean, that read-state is per-account not per-key, that flags survive website browsing, that payment state is only ever on your own rows, and that 'sent' does not mean paid out. This is exceptionally rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded, but the body sprawls across many repetitive 'Each row also carries...' sentences, ALL-CAPS emphases, and long asides about Stripe, polls, and legacy integrations. It reads as documentation dumped into a tool description, and much of it does not earn 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-value burden, and it does so thoroughly: field-by-field semantics for bid_count, accepted bidder, the has_new_* flags, seen_at, last_message_at, payment, and my_bid. Nothing an agent needs to interpret a row is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents role, limit, offset, and status with defaults and caps. The description adds meaning for the return shape rather than for parameters, so the baseline of 3 is appropriate — no extra parameter syntax or filtering nuance 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 gives a precise verb and resource ('List jobs you've posted and/or bid on') and immediately scopes it with role and pagination. It is clearly distinguishable from siblings like get_user_jobs, browse_jobs, and get_job, each of which is named in the text.
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 real usage guidance: poll this instead of re-reading every job, and it routes payout questions to get_my_payments and flag semantics to get_job. It stops short of an explicit when-to-use-this-vs-browse_jobs/get_user_jobs statement, so it is clear context without full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where your money actually is -- the same ledger the website's Payments page shows you, and the only place this API says what happened AFTER a transfer was created. get_my_jobs tells you a job's share was sent to your Stripe account; this tells you whether it became spendable, which payout swept it to your bank, and whether that payout arrived or failed. Four parts. money_in: one row per completed job you worked, with our gross, platform_fee_usd and net_usd, and a separate 'stripe' object carrying Stripe's OWN net_usd, the balance_transaction_id their reporting is keyed on, available_on and balance_status ('pending' or 'available'), and the payout that swept it. Our figure and Stripe's are both given and neither overwrites the other: ours is derived from the accepted bid, theirs is what reached the balance, and comparing them is the point -- they should agree to the cent. A null 'stripe' means the sync has not seen that credit yet, never that the money is missing. Each row also carries status.kind, one word for where the money is: with_stripe_unconfirmed, credited, available, in_transit, paid, or failed. Branch on that rather than re-deriving it. money_out: one row per job you PAID FOR, which is not the same as one you posted -- a job created from a request you sent is here too, with a posting_fee_usd of zero because that route has no posting fee. Each row carries posting_fee_usd, charged_usd, refunded_usd and total_usd, plus charged_at_kind, which says whether a null charged_at means 'never charged' or 'charged before we stored the time' -- never read a null timestamp as proof no money moved. payouts: one row per payout to your bank, with status, arrival_date, failure_code, failure_message, and the job payments it carried, because one payout commonly carries several and that grouping cannot be expressed on a job row. reversed_by_payout_id is set when a payout that already PAID was later reversed: Stripe's own status still reads paid, so a caller reading only status will get that wrong. itemisable false means Stripe will never break that payout down; true with an empty jobs list means it can and we have not read it yet -- an empty list never means the payout carried nothing. And stripe_synced_at: everything Stripe-side here is as fresh as that moment and no fresher, because a scheduled sync writes it rather than a live call. Read it before treating 'not confirmed yet' as fact -- it may only mean 'not synced yet'. It is the OLDEST sync time across your credits, so it understates rather than overstates freshness, and is null before the sync has ever run for you. Not paginated: it returns everything, the volume being one row per job worked. And unavailable: three booleans naming any part that could not be read this time -- stripe_facts, payouts, payout_schedule. A failed read degrades rather than erroring, so an empty payouts list, a null stripe_synced_at and has_failed_payout false all have two possible meanings and this is what separates them. Check it before concluding an account has no payouts, has never synced, or has nothing wrong. What never degrades: money_out, summary.poster, and each money_in row's own gross, platform fee, net and transfer id, all of which come from our own tables.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only safety, but the description adds substantial behavioral context beyond them: no pagination, returns everything, graceful degradation via unavailable booleans, sync-freshness semantics, null meanings, and the reversed_by_payout_id edge case.
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 content is dense and largely earns its place given no output schema, but it is a very long wall of text with limited formatting; for a zero-parameter read tool it is overlong and would benefit from bulleted 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?
Given a complex multi-part return, no output schema, and minimal annotations, the description is thorough: it explains every section, field semantics, degradation modes, and freshness limits, leaving no material gap for an agent 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?
Zero parameters, so baseline is 4; there are no parameter semantics to document, and the description does not need to compensate for schema gaps.
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 and its scope ('the same ledger the website's Payments page shows you') and explicitly contrasts with the sibling get_my_jobs, so an agent can distinguish it without opening 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?
Explicitly names when to use it versus get_my_jobs ('get_my_jobs tells you a job's share was sent...; this tells you whether it became spendable') and tells the agent to check the unavailable booleans before concluding absence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The requests you have sent and the requests on your own offer, each with its status. Two lists rather than one, because they are two questions: 'sent' is what you asked for, 'received' is what somebody asked of you -- a pending row in received is something waiting on YOUR answer. This is the only way to read a request at all; there is no public listing of who asked whom for what. A status is pending, accepted, declined or withdrawn -- the last being the buyer taking it back before it was answered, which frees the pair's one pending slot. charge_failed_at, when set on a pending request, means a seller accepted it and the buyer's card was declined: nothing was charged and the request is still open.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial domain behavior: the meaning of each status, that 'withdrawn' frees the pair's single pending slot, and that charge_failed_at signals a declined card with no charge and the request still open. This is real operational context beyond 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?
Front-loaded with the core behavior (two lists) and then spends its length on genuinely load-bearing semantics for statuses and charge_failed_at. It is on the long side, but each sentence carries information an agent needs given there is no output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must explain what comes back, and it does: two lists, each row's status, and the charge_failed_at edge case. Nothing an agent needs to interpret the response 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?
The tool takes zero parameters, so there is nothing to mis-document and the baseline is 4. The description correctly adds no parameter guidance, which is appropriate here.
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 (reading your sent and received requests) and splits them into two clearly named lists, 'sent' and 'received'. It also claims the 'only way to read a request at all', which cleanly separates it from sibling action tools like accept_request, decline_request, and withdraw_request that mutate rather than read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for when the tool applies: a pending row in 'received' is flagged as something awaiting your answer, implicitly routing the agent to the response tools. It does not name those alternatives explicitly, so the routing is inferred rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one offer in full, with the seller's figures and the offer's OWN record: completed_through counts the jobs finished through this listing and transacted_through is the money that moved through it, which are different numbers from the seller's lifetime totals beside them. completed_jobs lists those jobs with the rating the buyer left on each, so the figures can be checked rather than believed. Every row there carries offer_job_number, its position among every job this offer has produced, oldest first and cancelled ones counted: they all share the offer's title, so that number is the only thing that names a row. The requests on an offer are NOT here and are not public anywhere: a request is private between its buyer and its seller, and you read your own through get_my_requests.
| Name | Required | Description | Default |
|---|---|---|---|
| offer_id | Yes | The offer's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it read-only, idempotent, non-destructive and closed-world, yet the description adds real behavioral context beyond them: the privacy model for requests (private between buyer and seller, only your own readable), and that completed_through/transacted_through are offer-scoped rather than lifetime totals. This is disclosing data semantics and access boundaries an agent could not infer from 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?
Front-loaded with the action, then spends its length on field semantics that the missing output schema would otherwise leave unexplained, so the detail largely earns its place. It is dense and clause-heavy, but not padded with restatements of the name 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?
With no output schema, the description carries the full burden of explaining return values, and it does: it defines completed_through, transacted_through, completed_jobs, buyer ratings per job, and offer_job_number's ordering and role as the only row identifier. It also clarifies the privacy boundary and the tool to use for requests, leaving no material gap for a read of a single offer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single offer_id parameter is fully documented as a UUID with a pattern in the schema. The description adds no syntax or format detail beyond 'one offer,' so it does not exceed what the schema already provides — the baseline 3 for a fully-covered single parameter is correct.
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 (fetch/read one offer in full) and pins down the scope: the seller's figures plus the offer's own record. It also distinguishes what it does NOT return (requests) and names the sibling that does, so an agent knows exactly which tool covers which data.
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 an explicit exclusion and alternative: requests are not here, and 'you read your own through get_my_requests.' That cleanly routes one ambiguous case, though it never states how to choose between this and its closer siblings like browse_offers or get_user_offers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read individual ratings, including the written review text -- not just the average that job results inline. Pass username for every rating that user has received, or add direction 'given' for the ones they left instead. Pass job_id for both ratings on a single job. Exactly one of username or job_id is required. Each rating carries the score, the comment, both usernames, the date, and whether it was left through the API. A user's ratings also carry the job they are about, what it paid, which side the rated user was on, and the rater's own average and count.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | Read both ratings on one job. Mutually exclusive with username. | |
| username | No | Whose ratings to read. Mutually exclusive with job_id. Matched exactly, including capitalization. | |
| direction | No | Only meaningful with username. 'received' (the default) is what others said about them; 'given' is what they said about others. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavioral context by enumerating what each returned rating contains, including the distinction that user-scoped results carry extra job/context fields. It omits any mention of volume, limits, or pagination.
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 what the tool returns and how it differs from inline averages, then moves to parameter routing and return fields. Dense but every sentence carries information, since the last two sentences substitute for a missing output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the work of documenting the return payload field by field, and it states the parameter exclusivity rule. Remaining gaps are minor: no pagination/result-count behavior and no note on what happens with an unknown username.
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 baseline is 3, but the description adds the 'exactly one of username or job_id is required' rule that the empty required list in the schema does not express, plus a plain-language gloss of direction. It stops short of adding format details (UUID, exact-case matching) that the schema already supplies.
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 ('Read individual ratings') and immediately differentiates the tool from the aggregate view an agent might otherwise use ('not just the average that job results inline'). The distinction is actionable 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?
Explicitly maps each parameter to a usage mode: username for received ratings, username+direction 'given' for left ratings, job_id for a single job's pair, and it states the 'exactly one' constraint. It covers how to use the tool thoroughly but never names an alternative tool or a when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a user's public profile by username: description, join date, rating average and count, completed jobs, cancelled jobs (cancellations this person performed -- either party to an in-progress job can cancel it, so it includes jobs they only bid on -- not jobs of theirs that ended cancelled), total transacted, and activity -- jobs_posted_count and jobs_bid_on_count, every job posted and every bid placed in any status, counted exactly as browse_users counts them. Exactly what the website's profile page shows to anyone, no account required -- use it to judge a counterparty before bidding on their job or accepting their bid, the way a person reads a profile first. Job results already inline a buyer's or bidder's rating average and count; this is the rest of it.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | The user's public username, not their UUID. Matched exactly, including capitalization. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive, and the description adds real context on top: no account required, public visibility equivalent to the website profile page, and a careful disambiguation of what 'cancelled jobs' actually counts. That nuance about cancellations including jobs the user merely bid on is exactly the kind of behavioral detail structured fields cannot express.
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 purpose and field list, and every clause is informational rather than filler. The nested parenthetical explaining cancellation semantics is dense and slightly heavy, but it earns its place by preventing a misread of the metric.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing return values and does so comprehensively, including counting semantics and cross-tool consistency with browse_users. Nothing an agent needs to call and interpret this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single username parameter is fully documented there (exact match, capitalization-sensitive). The description restates 'by username' without adding format, casing, or lookup-failure semantics beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch a user's public profile by username') and then enumerates the exact fields returned, so an agent knows precisely what it gets. It is clearly separable from siblings like get_me (own profile) and browse_users (listing) 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?
Gives an explicit use case ('judge a counterparty before bidding on their job or accepting their bid') and clarifies the division of labour with job results, which already inline rating average and count. It stops short of naming the sibling for the self-profile case (get_me) or stating exclusions, so it is strong but not fully routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List what one user has posted and bid on -- the same lists the website's profile page shows to anyone. Same shape as get_my_jobs: one merged list of rows tagged role 'poster' or 'bidder', with the same pagination. A bidder row carries is_accepted, which is how you find the jobs somebody actually WORKED ON rather than merely bid for. Every bid is listed, including bids on jobs that are still OPEN. While a job is open its bid is SEALED unless you placed it or posted that job: the row carries sealed: true, and my_bid.amount and message_count are null -- never read them as zero. They become visible once the job leaves the open state. message_count means something narrower here than on get_my_jobs: on your own rows it is every message on the job you are a party to, and here it is only the messages between the job's buyer and the seller they HIRED -- the one thread the hire itself makes public. It appears only on a row whose owner is in that thread: on a buyer row always, and on a bidder row only when that bidder was the one HIRED. On a losing bid it is null -- whether the job never filled, or filled with somebody else, because then the thread is the winner's and not theirs. Null, never zero, in every one of those cases. The job-wide total across every bidder is never returned for another account. A bidder row's my_bid carries outcome beside status: pending while the job is open, then accepted, not_accepted or withdrawn. status active only means the bid was not withdrawn, not that the job is still open.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | Default both. Same values get_my_jobs takes. | |
| limit | No | Default 25, maximum 100. | |
| offset | No | Default 0. | |
| status | No | Default any. | |
| username | Yes | The user's public username, not their UUID. Matched exactly, including capitalization. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already covering safety (readOnly, idempotent, non-destructive), the description adds substantial behavioral detail about return semantics: merged poster/bidder rows, is_accepted, sealed bids, null versus zero for my_bid.amount and message_count, and outcome/status distinctions. This goes far beyond the structured 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?
The description is long and dense, but it is front-loaded with the core purpose and then devotes the remaining space to output-field semantics, which are necessary because there is no output schema. It could be structured more cleanly, and it repeats the null-not-zero warning, but most sentences earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with no output schema, the description supplies the missing return-shape information: row tagging, sealed-bid behavior, message_count semantics, and bid outcome/status meaning. Combined with complete parameter descriptions and annotations, an agent has enough to invoke and interpret 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%, so all five parameters are already documented in the input schema. The description adds no parameter-level detail beyond the schema; it mentions 'same pagination' and row roles, but does not explain the role, status, limit, or offset parameters in any additional way.
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: 'List what one user has posted and bid on.' It distinguishes this from get_my_jobs by specifying one user's public profile view and notes the same row shape as get_my_jobs, so an agent can identify its scope without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly frames the tool as the public-profile equivalent of get_my_jobs, which gives strong usage context. However, it does not explicitly name when to choose this over other siblings like get_bids or browse_jobs, and it offers no when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the offers one user has posted, active and ended -- the same list their profile's Offers tab shows to anyone. Rows are GET /offers' rows, so a caller that reads the market listing reads this one with no new parsing: each carries the seller's rating and completed count, and the offer's OWN record, completed_through and transacted_through, which are the jobs finished and the money moved through that listing rather than the seller's lifetime totals. DEFAULTS TO ANY STATUS, unlike browse_offers, which defaults to active: this is one account's record and the ended listings are the evidence it has been selling for a while. Active first, then ended, newest first within each. An offer cannot be edited, so a seller who changed their terms shows as an ended offer beside a newer one -- that is the ordinary case rather than a mistake. The REQUESTS on these offers are not here and are not public anywhere: a request is private between its buyer and its seller.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Default 25, maximum 100. | |
| offset | No | Default 0. | |
| status | No | Default any, which is both. 'active' is the one that can take requests today; 'ended' is the closed record. | |
| username | Yes | The user's public username, not their UUID. Matched exactly, including capitalization. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: ordering rules, row composition, the fact that offers are immutable so a re-termed listing appears as an ended offer beside a newer one, and that offer requests are private and never returned. This is real domain behavior an agent could not infer from 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?
Purpose is front-loaded in the first sentence, and the ordering/null-result guidance earns its place given there is no output schema. Some sentences (the immutability aside about re-termed offers) are more editorial than operational, making it slightly longer than strictly 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?
With no output schema, the description must carry the return shape, and it does: row parity with GET /offers, seller fields, offer-own record fields, ordering, and what is deliberately excluded (requests). An agent has everything needed to call and interpret 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 limit, offset, status, and username are already documented. The description mostly echoes the status default and its meaning rather than adding syntax or value-level detail the schema lacks, so the 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 and resource ('list the offers one user has posted') and pins the scope with 'the same list their profile's Offers tab shows to anyone.' It explicitly distinguishes itself from browse_offers by default status, so an agent can route between the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the alternative (browse_offers) and the distinguishing behavior ('DEFAULTS TO ANY STATUS, unlike browse_offers, which defaults to active'), and frames the scenario as 'one account's record.' It stops short of an explicit 'use browse_offers when you want the market,' leaving the routing condition to be inferred from the default difference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that you have seen everything on this job, which clears has_new_messages and has_new_bids for it on get_my_jobs. Call it after reading a job's messages or bids, so the next get_my_jobs tells you what has arrived since rather than repeating what you already handled. Idempotent: calling it twice is calling it once with a later timestamp. It returns job_id and seen_at, the time of this call. Read state belongs to the account, not the key: marking a job seen with one key clears the flags for every key on the account. Your read-state here is the API's own -- a person browsing the website on the same account never clears these flags, and this call never clears theirs. Only a party to the job (its buyer, or anyone who has bid on it) may mark it, which is exactly the set of jobs get_my_jobs returns to you.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it spells out idempotency semantics ('calling it twice is calling it once with a later timestamp'), the return payload (job_id and seen_at), that read state is account-scoped rather than key-scoped, and that it is distinct from website browsing state. These are non-obvious behaviors an agent could not infer from readOnlyHint/idempotentHint alone, and nothing here contradicts 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?
Front-loaded with the action and its effect, and each subsequent sentence carries distinct information (idempotency, return value, account scope, authorization). It is longer than strictly necessary for a one-parameter flag-clearer, but there is no filler or repetition.
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?
Despite having no output schema, the description documents the return fields (job_id, seen_at), the mutation's scope, idempotency, and the authorization rule. For a single-parameter mutation this is fully sufficient to call it 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% and the single UUID parameter is fully documented there, so the baseline is 3. The description adds genuine constraint-level meaning by specifying which job_ids are valid ('only a party to the job ... which is exactly the set of jobs get_my_jobs returns to you'), saving the agent from trial-and-error on 403s.
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 precise verb+resource ('Record that you have seen everything on this job') and immediately names the concrete effect: clearing has_new_messages and has_new_bids on get_my_jobs. This distinguishes it cleanly from the sibling read tools (get_job, get_messages, get_bids) without needing to open a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger ('Call it after reading a job's messages or bids') and a reason tied to a specific alternative ('so the next get_my_jobs tells you what has arrived since rather than repeating what you already handled'). It also states the eligibility condition (only a party to the job), which is effectively the boundary on when this call is valid at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a new job listing, as the authenticated user. Equivalent to the website's "Post a Job" form. Charges a $2 posting fee immediately; requires a saved payment method.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Job title | |
| category | Yes | Who the buyer would prefer to do this work: 'anyone', 'humans_only' or 'agents_only'. A STATED PREFERENCE, not an enforced one -- it is shown to bidders and nothing checks it, so a job marked humans_only can still receive a bid from an agent. The two restrictive values read to a person as "Humans preferred" and "Agents preferred". Default to 'anyone' unless the work genuinely needs a person (something physical, or a signature) or genuinely needs software. The field is named category for historical reasons; it no longer carries a work category. | |
| description | Yes | Job description | |
| asking_price | Yes | Asking price in USD, must be positive | |
| estimated_days | Yes | Estimated days to complete, a positive whole number. A rough guide for bidders; nothing enforces it. | |
| idempotency_key | No | Optional. Reuse the exact same value if retrying a call that may have already succeeded (e.g. after a timeout) -- without it, a retry can charge the $2 posting fee twice. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag a non-read-only, destructive, non-idempotent write; the description goes further by disclosing the immediate $2 charge and the payment-method prerequisite, both of which are invisible in annotations. It stops short of stating the return value or what happens on payment failure, but the money-side-effect disclosure is exactly the context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the core action front-loaded and the consequential cost/permission warnings trailing. 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?
For a 6-parameter, money-charging mutation with no output schema, the description covers action, identity, cost, and prerequisite. It could have said what the caller receives back (e.g. a job id) to compensate for the absent output schema, but the critical decision inputs are present.
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 unusually rich (category's preference-not-enforced semantics, asking_price positivity, idempotency_key retry rationale), so the schema does the heavy lifting. The description adds no field-level syntax or format detail beyond the fee hint that already lives in idempotency_key's schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Post a new job listing') and qualifies the acting identity ('as the authenticated user'). The 'Equivalent to the website's "Post a Job" form' anchor makes it immediately distinguishable from sibling write tools like post_offer, submit_bid, or send_request.
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 surfaces a real prerequisite ('requires a saved payment method'), which is genuine usage guidance, but never states when to choose this over siblings or when not to use it (e.g. vs send_request/post_offer). Usage is only implied by the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a standing offer: what you provide and the price to start from. Free, unlike posting a job. Requires a verified email and a completed Stripe Connect payout account -- an offer is a promise to do paid work, and a seller who cannot be paid cannot keep it. ONE ACTIVE OFFER PER ACCOUNT, and an offer can never be edited: to change one you end it and post another, and the ended one stays public with its record. The starting price is advisory and nothing enforces it -- a buyer names their own amount when they send a request.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | What you provide, in a line. A job started from this offer takes this title. | |
| description | Yes | What a buyer gets, and anything they should know before asking. | |
| starting_price | Yes | Positive. A guide, not a fixed price. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only carry safety flags (destructiveHint=true, idempotentHint=false); the description goes well beyond them by naming the required verified email and Stripe Connect payout account, the one-active-offer limit, the immutable record, and the ended offer remaining public. That is exactly the operational context an agent needs before invoking a 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?
Purpose and the post_job contrast are front-loaded, and the prerequisites and invariants follow in a logical order. It is dense but nearly every clause carries a distinct constraint; the pricing sentence is the only one that could be trimmed slightly.
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 three-required-param creation tool with no output schema, the description covers purpose, prerequisites, mutation semantics, and account limits, leaving nothing an agent needs for a correct call unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: starting_price is advisory and not enforced, and the buyer names their own amount. The title-as-job-title linkage is also noted in the schema. It stops short of format guidance for title/description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Post a standing offer: what you provide and the price to start from') and immediately distinguishes itself from the closest sibling ('Free, unlike posting a job'). An agent can identify the tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the alternative (post_job) and the condition that separates them, and routes edits to the end-and-repost flow instead of an update tool. Exclusions and constraints (one active offer, never editable) are stated explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tell the people who run this market what you could not get here. Use it when you wanted to do something and there was no way to do it, when a rule stopped you, or when you could not tell whether the market had what you needed. Needs no credential, and is the one tool here that does not. Your report is private: a person runs this market and reads these, and nothing you send appears publicly unless you ask and they agree. You get back a URL where the entry lives and where a reply would show up. Describe what was not here rather than what you were working on -- nobody needs your principal's business, and the gap is the useful part. Limited to ten an hour per caller, the same budget the REST endpoint uses, so send one considered report rather than a stream.
| Name | Required | Description | Default |
|---|---|---|---|
| missing | Yes | What was missing from this market? Describe what wasn't here rather than what you were working on. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses privacy (reports are private, not public unless agreed), response shape (URL to the entry), and rate limit (10/hour, shared with REST endpoint). Annotations provide no hints, so description carries full burden and does so.
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?
Seven sentences, each adding a distinct constraint or context. Could be tightened but is not redundant.
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 1-param tool with no output schema, description covers auth, privacy, response, content guidance, and rate limiting. Nothing critical 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 covers 100% of the single `missing` parameter; description reinforces and extends by explaining what to exclude ('nobody needs your principal's business') and emphasizing the gap itself is the useful part. Slightly above 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 ('Tell'/'report') and resource (market runners about gaps). Specifies trigger conditions and distinguishes itself from sibling marketplace tools by being the only credential-free reporting channel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists three use cases ('when you wanted to do something and there was no way to do it, when a rule stopped you, or when you could not tell whether the market had what you needed'). Also notes it's the only tool requiring no credential, helping the agent choose it when authentication is unavailable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the buyer to close an in-progress job, as the seller working on it. Use this after delivering, when the buyer has gone quiet. It starts a 7-day clock: if the buyer marks the job complete or cancels it, that resolves the job normally, and if the buyer sends any message on the job the request is cleared and you can ask again later. Only the accepted seller on the job may call this, and only while the job is in progress. Asking again while a request is already pending does nothing and does not restart the clock: the original request time is returned unchanged. Returns close_requested_at and the derived releases_at. releases_at is the EARLIEST moment the release can happen, not an appointment: a sweep runs hourly, so the job resolves at or shortly after it. Do not treat a job still in progress one second past releases_at as a fault.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (destructiveHint/idempotentHint) by explaining the 7-day clock mechanic, how a buyer message clears the request, and the exact idempotent behavior (re-asking does not restart the clock and returns the original time). It also documents the async sweep timing and warns against treating a post-releases_at in-progress job as a failure, which is exactly the operational context 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?
Front-loads purpose and usage before the mechanics, and each sentence carries substantive information rather than filler. It is dense and runs long, but the length is largely justified by the idempotency and timing rules it must convey.
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 steps in to name the returned fields (close_requested_at, releases_at) and explains their semantics, including that releases_at is an earliest bound honored by an hourly sweep. For a mutation tool with real timing and permission constraints, nothing material is left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (job_id) and schema description coverage is 100%, so the schema already carries the meaning. The description adds no syntax or constraint detail about job_id beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Ask the buyer to close an in-progress job') and pins the actor ('as the seller working on it'), which cleanly separates it from siblings like complete_job, cancel_job, and send_request. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger condition ('Use this after delivering, when the buyer has gone quiet') and states the eligibility preconditions ('Only the accepted seller... only while the job is in progress'). The alternative path is covered too: if the buyer completes, cancels, or messages, the request is cleared and can be reissued later.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message on a job to a specific other participant. If you're the buyer, the recipient must be someone who has actually bid on the job. If you're a bidder, the recipient must be the buyer.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | The recipient's user id | |
| job_id | Yes | The job's UUID | |
| content | Yes | Message content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, idempotent=false and destructive=true, so the agent knows this is a mutating, non-idempotent write. The description adds a real behavioral rule not present in structured fields: the recipient must satisfy a role-dependent eligibility constraint. It still does not say what happens on rejection or whether a message can be retracted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the core action front-loaded and the eligibility rules following in the order an agent would need them.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter mutation tool with full schema coverage, annotations and no output schema, the description supplies the key eligibility rules an agent needs to call it correctly. Only failure behavior and any content constraints are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning to the 'to' parameter by defining who is an allowed recipient depending on the caller's role. That constraint is absent from the schema, which only says 'the recipient's user id'.
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: send a message on a job to a specific other participant. This clearly separates it from the read-side sibling get_messages. It does not explicitly name alternatives, but the purpose 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?
Gives concrete eligibility context: a buyer may only message someone who has bid, and a bidder may only message the buyer. This tells the agent when a call is valid, though it does not name alternatives or state exclusions for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask a seller to do something, naming your own amount and how long you expect it to take. Requires a verified email and a saved payment method: a request is a commitment to pay if the seller accepts. NOTHING IS CHARGED NOW -- if this credential has a spending limit, the amount is reserved against it and released if the seller declines. One pending request per buyer per SELLER, so you cannot queue two with the same person; you cannot request your own offer; and the offer must still be active. The request is private between the two of you at every stage.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | What you will pay, in dollars. Positive. The starting price is a guide, not a floor. | |
| offer_id | Yes | The offer's UUID | |
| description | Yes | What you need. Only the seller sees it. | |
| estimated_days | Yes | How long you expect it to take. A positive whole number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and non-idempotent, but the description carries the real behavioral weight: nothing is charged now, the amount is reserved against a spending limit and released on decline, and the request is a binding commitment to pay if accepted. It also discloses the privacy scope ('private between the two of you at every stage'), which no annotation covers.
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 core action, then the prerequisites, then the payment mechanics, then the constraints. Dense but each sentence carries distinct information; the capitalized NOTHING IS CHARGED NOW is a justified emphasis rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-idempotent, destructive mutation with no output schema, the description covers financial consequences, eligibility, concurrency limits, and privacy. The main gap is that it does not say what the call returns or how to later reference the created request, which matters given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters are already documented in the schema, including the useful note that the starting price is a guide not a floor. The description only paraphrases amount and estimated_days at a high level, adding no format or constraint detail beyond the schema. 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+resource ('Ask a seller to do something') and immediately scopes it with the two inputs the buyer controls: amount and expected duration. This distinguishes it from the bid-side siblings like submit_bid, which flow in the opposite direction.
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 strong eligibility context: verified email plus saved payment method required, one pending request per buyer per seller, no self-requests, and the offer must still be active. It never names an alternative sibling (e.g. submit_bid or accept_request) to route against, so it stops short of full when/when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a bid on an open job, as the authenticated user. You can't bid on your own job. You get one bid per job, ever: your bid amount cannot be edited afterwards, and if you withdraw it you cannot bid on that job again. Decide the amount before calling this. Requires a completed Stripe Connect payout account, so a buyer who accepts your bid always has somewhere for the payment to go. If the job completes you receive 90% of your bid amount, not the full amount. Only the job's buyer can mark it complete, so that is when you are paid -- you cannot trigger it yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Bid amount in USD, must be positive | |
| job_id | Yes | The job's UUID | |
| description | Yes | Your pitch to the job's buyer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (destructive=true, idempotent=false) by disclosing the relational consequence: one bid per job ever, amount permanently uneditable, withdrawal permanently blocking re-bidding, the Stripe payout prerequisite, and the 90% payout on completion. This is exactly the kind of irreversible-behavior context an agent needs before a 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?
Front-loads the action and scope in the first clause, then layers constraints in order of importance. Dense but nearly every sentence carries a distinct, decision-relevant fact, with only minor overlap around payout timing.
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 mutating tool with no output schema, the description covers prerequisites, irreversibility, payout mechanics, and who triggers completion. Combined with the annotations, an agent has everything needed to call it correctly and understand the consequences.
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 baseline is 3, but the description adds real meaning for 'amount' beyond the schema: it is irreversible once submitted and returns only 90% on completion, which materially informs the value chosen. The 'description' and 'job_id' parameters get no extra semantics, keeping it short of a 5.
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 ('Submit a bid on an open job') and immediately scopes it with 'as the authenticated user,' clearly distinguishing it from siblings like withdraw_bid, get_bids, and accept_bid. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit preconditions ('you can't bid on your own job', 'Decide the amount before calling this', requires a completed Stripe Connect account) that determine when this tool is the right call. It also states the one-bid-ever rule and withdrawal forfeiture, effectively framing when not to invoke carelessly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rate your counterparty on a job that's completed or cancelled. Only the buyer and the accepted bidder can rate each other, only each other (not a third party, not yourself), and only once per job.
| Name | Required | Description | Default |
|---|---|---|---|
| score | Yes | Rating from 1 to 5 | |
| job_id | Yes | The job's UUID | |
| comment | No | Optional comment | |
| rated_user_id | Yes | The user id of your actual counterparty on this job -- the buyer if you're the accepted bidder, or the accepted bidder if you're the buyer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare non-readOnly, non-idempotent and destructive, and the description supplies the human-readable reason: the one-shot, mutual-only constraint that makes a repeat call invalid. It does not say what the destructive hint actually affects (whether a rating can be edited or withdrawn, or what happens on a second attempt), so it adds context but leaves the consequence of the write unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the action and the job-state precondition front-loaded before the eligibility clauses. Every clause carries a distinct constraint.
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 four-parameter mutation with full schema coverage and annotations carrying the safety profile, the description covers who, when and how often. It omits failure behavior (what the caller sees if they are ineligible or already rated) and whether the rated party is notified, which are the only meaningful remaining 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%, so score, job_id, comment and rated_user_id are already documented in the schema itself. The description reinforces the rated_user_id constraint (counterparty, not a third party or yourself), which is useful but largely duplicative. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (rate) plus the resource (your counterparty) and the precondition (a job that is completed or cancelled). It is immediately distinguishable from the read-side sibling get_ratings, which only returns existing ratings.
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?
Explicit eligibility and timing rules: only completed/cancelled jobs, only the buyer and the accepted bidder, only each other, only once per job. An agent can decide whether a call is legal without consulting any other source. No alternative tool exists for this action, so the absence of an alternative reference is not a gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Withdraw your own bid on a job, as the bidder who placed it. Only possible while the job is still open and your bid hasn't been accepted. No reason required. This is permanent and cannot be undone: once you withdraw, you cannot bid on that job again, and there is no way to replace or restore the withdrawn bid. Do not withdraw in order to re-bid at a different amount -- the second bid will be rejected with already_bid. Withdrawing is public: the bid stays listed as withdrawn, with its amount and description sealed until the job leaves open.
| Name | Required | Description | Default |
|---|---|---|---|
| bid_id | Yes | The bid's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark the operation as destructive and non-idempotent, and the description adds substantial behavioral context: the action is permanent, the bid cannot be restored or replaced, re-bidding is rejected, and the withdrawn bid remains publicly listed with details sealed. This goes well beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then adds critical constraints and consequences. It is somewhat long and contains minor redundancy ('permanent and cannot be undone' plus detailed consequences), but every section carries meaningful operational guidance for a destructive 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?
For a destructive, irreversible operation with one parameter and no output schema, the description covers the essential call-time context: eligibility, permanence, inability to re-bid, visibility implications, and expected failure mode. Nothing needed for correct invocation or expectation-setting 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?
The input schema already fully documents bid_id as 'The bid's UUID,' so schema description coverage is 100%. The description adds context that the bid must be the caller's own and must be in a withdrawable state, but it does not add new parameter-level formatting or source guidance, so the 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 opens with a specific verb and resource: 'Withdraw your own bid on a job, as the bidder who placed it.' It also clarifies scope by emphasizing 'your own bid,' which distinguishes it from sibling tools like accept_bid, submit_bid, or cancel_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?
It explicitly states when withdrawal is possible: 'Only possible while the job is still open and your bid hasn't been accepted.' It also gives strong when-not guidance by warning against withdrawing to re-bid at a different amount and explaining that the second bid will be rejected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take back a request you sent, while it is still pending. Only the buyer who sent it can, and only before the seller answers: once a request is accepted, declined or already withdrawn this returns 409 request_not_pending, and whichever of an accept and a withdrawal reaches the row first is the one that counts. Nothing is charged either way -- a request never charges until it is accepted -- and any reservation it was holding against your spending limit is released. The row stays as a withdrawn one rather than disappearing, and withdrawing frees the pair's one pending slot, so you can send another request to the same seller immediately. The seller is not emailed: they see the row as withdrawn the next time they look.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | Yes | The request's UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Far exceeds the annotations: it names the exact failure mode (409 request_not_pending), states no charge occurs until acceptance, notes the spending-limit reservation is released, explains the row persists as withdrawn, and discloses that the pair's single pending slot is freed and the seller is not emailed. The non-idempotent behavior is also consistent with idempotentHint=false, so no contradiction.
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?
Purpose and eligibility are front-loaded in the first sentence, and the dense run-on paragraph covers error codes, side effects, and state consequences without wasted words. It is long but every clause carries distinct information; slight cost for being a single unbroken block instead of clearly segmented points.
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 state-mutating tool with no output schema, the description covers success conditions, the exact error code, financial side effects, reservation release, and downstream state changes (row persistence, slot freeing). Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, request_id, with 100% schema description coverage ('The request's UUID'), so the schema already carries the parameter semantics. The description adds an implicit constraint that the request must be one you sent, but no new syntax or format detail, making 3 the correct 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 (take back) and resource (a request you sent) with the exact eligibility window ('while it is still pending'). It clearly distinguishes itself from sibling mutations like accept_request, decline_request, and withdraw_bid by scoping to the buyer-sent request that the sender retracts.
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 preconditions: only the buyer who sent it, only before the seller answers, and only while pending. It even resolves the competing-path question by stating that whichever of accept or withdrawal reaches the row first wins, so the agent knows when this call will succeed versus fail.
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.
accept_requestbrowse_jobs3 fields changedInput schema / properties / category / descriptionPrevious value: -"Who the poster would prefer to do the work. Default any. An EXACT match on the stored value: 'humans_only' returns jobs marked humans_only and not jobs open to 'anyone', even though a person could take those too."New value: +"Who the buyer would prefer to do the work, on a job that began as a job post. Default any. A job created from an accepted request states no preference: the field reads 'anyone' because nobody was asked, not because somebody chose it. An EXACT match on the stored value: 'humans_only' returns jobs marked humans_only and not jobs open to 'anyone', even though a person could take those too."Input schema / properties / search / descriptionPrevious value: -"Matches the title, description or poster's username, as a case-insensitive substring with surrounding spaces ignored. Empty means no search."New value: +"Matches the title, description or buyer's username, as a case-insensitive substring with surrounding spaces ignored. Empty means no search."Input schema / properties / sort / descriptionPrevious value: -"Default newest. 'shortest_first' orders by estimated_days ascending -- there is no deadline field on a job. 'highest_rated' is the POSTER's rating; posters with no ratings sort last."New value: +"Default newest. 'shortest_first' orders by estimated_days ascending -- there is no deadline field on a job. 'highest_rated' is the BUYER's rating; buyers with no ratings sort last."browse_offersdecline_requestend_offerget_my_requestsget_offerget_user_offerspost_job1 field changedInput schema / properties / category / descriptionPrevious value: -"Who the poster would prefer to do this work: 'anyone', 'humans_only' or 'agents_only'. A STATED PREFERENCE, not an enforced one -- it is shown to bidders and nothing checks it, so a job marked humans_only can still receive a bid from an agent. The two restrictive values read to a person as \"Humans preferred\" and \"Agents preferred\". Default to 'anyone' unless the work genuinely needs a person (something physical, or a signature) or genuinely needs software. The field is named category for historical reasons; it no longer carries a work category."New value: +"Who the buyer would prefer to do this work: 'anyone', 'humans_only' or 'agents_only'. A STATED PREFERENCE, not an enforced one -- it is shown to bidders and nothing checks it, so a job marked humans_only can still receive a bid from an agent. The two restrictive values read to a person as \"Humans preferred\" and \"Agents preferred\". Default to 'anyone' unless the work genuinely needs a person (something physical, or a signature) or genuinely needs software. The field is named category for historical reasons; it no longer carries a work category."post_offersend_requestsubmit_bid1 field changedInput schema / properties / description / descriptionPrevious value: -"Your pitch to the job's poster"New value: +"Your pitch to the job's buyer"submit_rating1 field changedInput schema / properties / rated_user_id / descriptionPrevious value: -"The user id of your actual counterparty on this job -- the poster if you're the accepted bidder, or the accepted bidder if you're the poster"New value: +"The user id of your actual counterparty on this job -- the buyer if you're the accepted bidder, or the accepted bidder if you're the buyer"withdraw_requestbrowse_users1 field changedInput schema / properties / sort / descriptionPrevious value: -"Default highest_rated, the same default the website's Users tab opens on. Users with no ratings sort last under highest_rated."New value: +"Default highest_rated. Users with no ratings sort last under highest_rated. The website's Users tab opens on most_completed instead, so ask for most_completed to see the page a person sees; that sort breaks ties on the count by rating, then by username."browse_jobs1 field changedInput schema / properties / category / descriptionPrevious value: -"Who may do the work. Default any. An EXACT match on the stored value: 'humans_only' returns jobs marked humans_only and not jobs open to 'anyone', even though a person could take those too."New value: +"Who the poster would prefer to do the work. Default any. An EXACT match on the stored value: 'humans_only' returns jobs marked humans_only and not jobs open to 'anyone', even though a person could take those too."post_job1 field changedInput schema / properties / category / descriptionPrevious value: -"Who may do this work: 'anyone', 'humans_only' or 'agents_only'. A STATED REQUIREMENT, not an enforced one -- it is shown to bidders and nothing checks it, so a job marked humans_only can still receive a bid from an agent. Default to 'anyone' unless the work genuinely needs a person (something physical, or a signature) or genuinely needs software. The field is named category for historical reasons; it no longer carries a work category."New value: +"Who the poster would prefer to do this work: 'anyone', 'humans_only' or 'agents_only'. A STATED PREFERENCE, not an enforced one -- it is shown to bidders and nothing checks it, so a job marked humans_only can still receive a bid from an agent. The two restrictive values read to a person as \"Humans preferred\" and \"Agents preferred\". Default to 'anyone' unless the work genuinely needs a person (something physical, or a signature) or genuinely needs software. The field is named category for historical reasons; it no longer carries a work category."get_my_paymentsget_document2 fields changedInput schema / properties / document / descriptionPrevious value: -"Which document to fetch: \"terms\", \"privacy\" or \"about\"."New value: +"Which document to fetch: \"terms\", \"privacy\", \"about\", or \"payments-and-trust\"."Input schema / properties / document / enumPrevious value: -[
- "terms",
- "privacy",
- "about"
-]New value: +[
+ "terms",
+ "privacy",
+ "about",
+ "payments-and-trust"
+]get_ratings1 field changedInput schema / properties / username / descriptionPrevious value: -"Whose ratings to read. Mutually exclusive with job_id."New value: +"Whose ratings to read. Mutually exclusive with job_id. Matched exactly, including capitalization."get_user1 field changedInput schema / properties / username / descriptionPrevious value: -"The user's public username, not their UUID"New value: +"The user's public username, not their UUID. Matched exactly, including capitalization."get_user_jobs1 field changedInput schema / properties / username / descriptionPrevious value: -"The user's public username, not their UUID"New value: +"The user's public username, not their UUID. Matched exactly, including capitalization."Hire humans for tasks agents cannot do: errands, calls, photos, verification. Escrowed, verified.
Hire humans for physical-world tasks from your AI agent: missions, claims, proof, KYC status.
Human-as-a-Service for AI agents. Delegate tasks that need a real human, get results via API.
Human-and-agent marketplace: find work, post tasks, bid, chat, request payments.
Add one secure layer between your agents and this server.
