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 23 tools
Each tool has a clearly distinct purpose: browse/get for lists vs details, get_my_jobs vs get_user_jobs for own vs other users' jobs, and accept_bid/complete_job/cancel_job/request_close cover separate lifecycle actions. No two tools appear to overlap in function, and descriptions explicitly clarify boundaries.
Nearly all tools follow a snake_case verb_noun pattern (accept_bid, browse_jobs, get_job, submit_bid, withdraw_bid). Minor deviations include get_me lacking a noun and the possessive 'my' in get_my_jobs/get_my_payments alongside 'user' in get_user_jobs, but the convention remains predictable.
23 tools is on the heavy side, falling into the borderline 16-25 range. While each tool covers a distinct subdomain (jobs, bids, users, messages, payments, ratings, documents, reporting), the volume may burden tool selection and is more than a typical well-scoped server.
The surface covers the core freelance marketplace lifecycle: posting, browsing, and managing jobs; submitting, withdrawing, and accepting bids; messaging, ratings, payments, and platform documents. Minor gaps like profile editing, job editing, or formal dispute handling are absent, but agents can work around them or they may be outside the stated scope.
Accept a specific bid on a job, as that job's poster. Moves the job to in_progress. Only the job's poster can do this -- the bidder accepting their own bid is rejected, as is anyone who isn't the poster. Charges the poster 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?
Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description discloses critical side effects and preconditions: job state change to in_progress, charging the poster's full bid amount held in Stripe, requiring a saved payment method, and re-checking the bidder's Stripe Connect payout account. This gives an agent a solid basis for predicting the tool's impact.
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 three sentences, each conveying essential operational information: the action and scope, the authorization rule, and the financial/precondition details. There is no filler; the contextual note about re-checking Stripe Connect is defensible because time can pass between submit_bid and accept_bid.
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 financial mutation with no output schema, the description covers the action, state change, permissions, payment method requirement, and bidder payout account requirement. It does not mention what happens if the bid is no longer valid or the job is not in a biddable state, but those are edge cases beyond the tool's core contract.
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's description for bid_id already explains 'The bid's UUID (not the job's)', which semantically disambiguates the only parameter. The tool description refers to 'a specific bid' but does not add substantial new parameter meaning. Since schema coverage is 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with a specific verb and resource: 'Accept a specific bid on a job, as that job's poster.' It states the core outcome, moves the job to in_progress, and clearly distinguishes this from bidder-side actions like submit_bid or withdraw_bid by restricting it to the poster.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates who should use this tool ('Only the job's poster can do this') and who should not ('the bidder accepting their own bid is rejected, as is anyone who isn't the poster'). It provides clear context but does not explicitly name alternative sibling tools, such as withdraw_bid, for the bidder case.
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 poster would prefer), 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.
| 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 POSTER's rating; posters 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 poster'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 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, non-destructive), and the description adds real behavioral context on top: the pagination block must be read rather than assuming page one is complete, status_counts spans the whole market unaffected by filters, and bid_count excludes withdrawn bids. This is the kind of return/interpretation detail 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 critical default discrepancy. However, the open-jobs-only caveat is restated at both the top and the closing sentences, which is mild redundancy in an otherwise dense paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the return burden and does so: it explains pagination, status_counts, and bid_count. Combined with 100% parameter coverage, an agent has everything needed to call and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents every parameter in detail (sort, budget boundaries, search semantics, status, category). The description reinforces the status and category semantics but adds little the schema does not already state, 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 (List) and resource (jobs) and scopes it to the Browse page's Jobs-tab filters. An agent can distinguish it from get_my_jobs, get_user_jobs, and get_job 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 explains when to use it versus the page default, tells the agent to pass status 'any' for the page view or a specific status for other work, and points to get_bids for withdrawn bids. The trigger conditions are spelled out rather than inferred.
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, the same default the website's Users tab opens on. Users with no ratings sort last under highest_rated. | |
| 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 establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds real context beyond them: only verified accounts appear, api_active means the account has authenticated via API/MCP, and nothing is ranked for the agent. It does not discuss pagination behavior beyond pointing at the response's pagination block.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose and the key api_active caveat are front-loaded, and the closing sentence earns its place by justifying the tool's existence. Several clauses are wordy (the api_active false-value explanation, the earnings totals list), but there is little outright waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of describing return fields—username, description, join date, ratings, job counts, earnings totals, api_active—and does so thoroughly, while also covering access rules (verified only) and defaults. 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?
Schema description coverage is 100%, and each enum parameter (role, sort, rating) is already documented in the schema with defaults and edge-case behavior. The description says only 'sort and filter as you like', adding no syntax or 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 ('List the people on Freelance Clearing') and anchors it to a concrete equivalent ('the Browse page's Users tab'), which separates it from the singular get_user. It then enumerates the exact facts returned, so an agent knows precisely what this tool yields.
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 when-to-use scenario ('find someone to hire when you have no job to start from') and explains why the alternative path is worse ('a counterparty can only be reached by first finding a job they posted or bid on'). No explicit when-not guidance, but the context is clear enough to route correctly.
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 poster only) or while it's in progress (as the poster 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 poster (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?
The description goes well beyond the destructiveHint annotation by disclosing financial consequences (95% refund, 5% retained, non-refundable $2 fee), reason requirements, and bidder notifications. This is exactly the behavioral context an agent needs for a destructive operation.
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 dense yet well-structured. Each sentence adds essential information about roles, conditions, notifications, or financial impact, with 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?
For a destructive tool with no output schema, the description thoroughly covers authorization, reason requirements, notifications, and financial consequences. Nothing critical is missing for an agent to understand how to invoke and evaluate 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%, so the schema already documents both parameters. The description reinforces the reason-required condition but does not add substantial new meaning 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?
The description states a specific verb and resource ('Cancel a job') and distinguishes the action across job states (open vs. in progress) and roles (poster, accepted bidder). This clearly separates it from siblings like withdraw_bid and request_close.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly identifies when cancellation is allowed and who may perform it, and explains when a reason is required. It does not explicitly mention alternatives or exclusions, but the role/state conditions provide strong contextual guidance.
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 poster. Moves the job from in_progress to completed. Only the poster can do this -- not even the accepted bidder can mark their own job complete. Transfers 90% of the held amount to the freelancer'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?
The description discloses meaningful behavior beyond the destructiveHint annotation: it transfers 90% of the held amount to the freelancer's Stripe account and fails if payout onboarding is incomplete. This gives the agent a realistic expectation of side effects, which is especially valuable for a financial 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?
Three sentences, all information-dense: the action, the permission model, the state change, the financial effect, and a failure condition. No filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, no-output-schema tool, the description covers the key runtime preconditions (poster-only, in_progress state, Stripe onboarding) and the primary side effect (funds transfer). It is complete enough for an agent to call the tool correctly and anticipate results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the only parameter, job_id, is fully described in the schema as 'The job's UUID'. The description adds no additional parameter-level detail, but none is needed given the schema's completeness.
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 ('Mark'), a concrete resource ('a job'), and the actor ('as that job's poster'). It clearly distinguishes itself from sibling tools like cancel_job by stating the state transition (in_progress to completed) and the financial transfer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: only the poster can do it, the bidder cannot; it moves the job from in_progress to completed; and it requires Stripe Connect payout onboarding to succeed. It does not explicitly name alternatives or when not to use it beyond these constraints, but the context is sufficient for an agent to determine applicability.
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 and description are SEALED -- present as null, with sealed: true -- unless you are the job's poster 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 bid is complete for everyone and sealed_until is null. 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 already mark the tool as read-only and idempotent, but the description goes far beyond that: it discloses that withdrawn bids are included, explains the sealed behavior for amount/description while the job is open, clarifies null handling ('Never read a null amount as zero'), and defines the meaning of an empty list. It adds significant behavioral context that annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every sentence delivers new, essential information – from the core listing function to edge cases (sealed data, withdrawn bids) and final semantic clarifications (outcome vs status). It is front-loaded with the purpose and then logically progresses into exceptions and clarifications, with no redundant language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description must fully explain the response shape and behavior. It does so exhaustively: covers rating average/count, sealed fields and sealed_until, null handling, withdrawn-bid inclusion, empty-list semantics, and the distinction between outcome and status. An agent has enough information to correctly interpret every field it will receive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only one parameter (job_id) and 100% schema description coverage ('The job's UUID'), the schema fully documents the parameter. The description adds no parameter-specific detail beyond the context of 'job', so it does not exceed the schema's value. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List every bid on a job' – a specific verb and resource – and immediately specifies the returned data (bidder's rating average and count). This clearly distinguishes it from write-oriented siblings like submit_bid and withdraw_bid, and from lookup tools like get_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?
The purpose is self-evident – retrieve bids on a job – but the description never explicitly compares this tool to alternatives or states when not to use it. There is no mention of get_job or other tools that might offer related context, so an agent must infer usage from the description alone.
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 freelancer has asked the poster to close, and is cleared if the poster 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 poster. bid_count counts bids still standing; a withdrawn bid is not counted, though get_bids lists 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?
The description adds substantial behavioral context beyond the readOnly hint: close_requested_at lifecycle, auto_released_at semantics over the 7-day window, the distinction between poster-marked completion and auto-release, and bid_count excluding withdrawn bids while get_bids lists them. This is exactly the kind of state-machine nuance an agent needs to interpret the returned object correctly.
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, then each subsequent sentence adds necessary edge-case semantics without fluff. Every sentence earns its place by explaining fields that would otherwise be misinterpreted.
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?
Even without an output schema, the description provides enough context to call the tool correctly: it promises full detail, clarifies tricky field states, and even routes the agent toward get_bids for withdrawn-bid listings. For a single-parameter read-only tool, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter and the schema already fully describes it as 'The job's UUID' with 100% coverage. The description does not need to add parameter syntax or format details; baseline 3 is appropriate because the schema carries the weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') with a clear resource ('full detail for a single job') and unique identifier ('by id'). It also covers all job statuses, making the tool's scope unambiguous and distinguishing it from listing-style siblings like get_my_jobs or browse_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states this tool is for single-job detail retrieval by id and explicitly says status does not matter, so there is no hidden exclusion. It does not name alternative tools or provide when-not-to-use guidance, but the 'by id' framing makes the intended usage clear.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable behavioral detail beyond annotations: it explains that the tool reports whether the agent can currently post a job or place a bid, and includes reasoning ('why not') and remediation ('where to fix it'). This discloses failure modes and output content that the annotations do not, so a 4 is warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the core purpose ('Get your own identity and capabilities') before listing specifics. Every clause adds value, and there is zero redundancy or fluff. It is both concise and well-structured.
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 there is no output schema, no parameters, and a straightforward purpose, the description fully covers what an agent needs to know: what it returns and the capability-check behavior. It also implicitly communicates that no input is required, and the sibling list provides alternatives. Nothing is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the baseline is 4 per the rubric. The description does not need to explain parameter semantics, and it adds no parameter-related information (there are none). The description's focus on return fields is appropriate, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and resource ('your own identity and capabilities'), and enumerates the exact fields returned (user id, username, join date, rating, capability flags). This distinguishes it from siblings like get_user (which presumably retrieves other users) and get_my_jobs (which focuses on jobs), so an agent can immediately tell it apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('your own' identity and capabilities) but does not explicitly contrast with alternatives such as get_user or get_my_jobs. It never says 'use this instead of X when you need self-info' or excludes cases like retrieving other users. The context is clear but not explicit, so it earns a baseline 3.
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 poster sees every conversation on that job (with every bidder they've messaged); a bidder sees only their own conversation with the poster, never another bidder's thread. Every message names its sender and its recipient, so a poster 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 or rating_submitted), and is null for a message a person wrote. A notice's sender is the person whose action produced 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 mark the operation readOnly, idempotent, and non-destructive, so the bar for additional value is high. The description adds meaningful behavioral depth: messages are returned oldest-first, platform-generated messages are identified by an event field with enumerated values (bid_submitted, bid_accepted, etc.), and event sender semantics are clarified. This goes well beyond annotation coverage.
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, then layers visibility rules, ordering, and event semantics. Each sentence adds necessary information, especially because there is no output schema. It is detailed but not repetitive or bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining what an agent will get. It covers the message list's ordering, the visibility differences between poster and bidder, sender/recipient presence, the event field's purpose, its possible values, and null semantics for human-written messages. This is sufficiently complete for correct invocation and interpretation.
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 only parameter, job_id, is fully documented in the schema with type, format, pattern, and a one-line description ('The job's UUID'). With 100% schema description coverage, the tool description does not need to add parameter detail; it exceeds the baseline? Actually it meets the baseline, adding no new parameter-specific meaning beyond clarifying the resource context.
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: 'Read the messages for a job.' It clearly distinguishes message retrieval from siblings like get_bids, send_message, and get_job by focusing on conversation data, and goes further to explain role-scoped visibility, which makes the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about when the tool is appropriate: a poster can retrieve all conversations, while a bidder only sees their own thread. This is practical selection guidance, though it does not explicitly mention alternative tools or when-not conditions relative to get_bids or other siblings.
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 poster'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. 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 freelancer'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 freelancer'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 freelancer'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 mark this as read-only, idempotent, closed-world, and non-destructive, but the description adds substantial behavioral context beyond them: account-level read-state shared across keys, website browsing not clearing flags, first-call default true behavior, has_new_bids being a poster-only signal, and payment-state nuances such as 'sent' not meaning bank payout completion. These details are not derivable from the annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, and the detailed sections are logically ordered. However, it is very long for a list tool, with repetition around has_new_messages/has_new_bids and payment states, and some sentences such as the historical note about older integrations may not earn their place for an agent invocation. It is adequately structured but not concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only basic annotations, the description carries the full burden of explaining returned fields and behavior. It covers row fields, payment semantics, read-state semantics, bid outcome, and cross-references to get_job for close fields, leaving little ambiguity for an agent calling 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%, so the input schema already documents role, limit, offset, and status. The description adds only the general note 'with pagination' and otherwise does not add syntax, format, or filtering details beyond the schema. A baseline 3 is appropriate when the schema carries the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence gives a specific verb and resource: 'List jobs you've posted and/or bid on, with pagination.' It also distinguishes the result set from get_user_jobs by noting that payment data is returned only for your own rows. An agent can identify the tool's purpose 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?
The description explicitly tells the agent to use this tool for polling by comparing last_message_at between calls, and it routes related concerns elsewhere: payouts to get_my_payments, close_requested_at and auto_released_at to get_job, and seen-state management to mark_job_seen. It also clarifies that get_user_jobs does not return the same payment data, helping select between siblings.
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 posted, with 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?
The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description goes far beyond that by explaining subtle behaviors: degraded reads instead of errors, empty lists having two possible meanings, the oldest-sync-time freshness semantics, null never meaning missing money, and reversed payouts that Stripe still reports as paid. This is exactly the behavioral 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?
The description is long, but every sentence carries load-bearing semantic information: null meanings, sync freshness, degradation flags, and payout grouping all require explanation. It is front-loaded with a clear identity statement and then organized into named sections (money_in, money_out, payouts, unavailable), making dense technical content navigable. Nothing feels padded or 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?
With no output schema, the description fully carries the burden of explaining return values, and it does so exhaustively: all four response parts, the meaning of every null case, the stripe_synced_at freshness caveat, payout reversal semantics, and the degradation booleans. An agent has everything needed to interpret results correctly and avoid the documented failure modes.
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 has zero properties, so there are no parameter semantics for the description to clarify. With 100% schema coverage and no parameters, the description cannot add parameter-level meaning, but it also does not need to. The baseline of 4 applies here because the absence of parameters makes this dimension moot rather than deficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it tells the caller exactly what this tool returns and why it matters, framing it as the same ledger the website's Payments page shows. It also explicitly distinguishes itself from get_my_jobs, which only reports that a transfer was created, whereas this tool reports spendability, payouts, and final arrival. This is unmistakable and well-differentiated.
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 explicitly contrasts this tool with get_my_jobs to settle when each should be used, and it tells callers to branch on status.kind rather than re-deriving state. It also gives concrete interpretive guidance: read stripe_synced_at before treating something as unconfirmed, and check the unavailable booleans before concluding an account has no payouts, has never synced, or has nothing wrong.
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.
| 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns individual ratings with score, comment, both usernames, date, and API-origin flag, and clarifies that job results only show averages. It doesn't mention pagination or ordering, but for a read tool with strong annotations this is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it opens with the core value proposition (individual ratings with review text, not just averages), then gives parameter usage in order of importance. Every sentence earns its place, and there is no repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema, the description covers what data is returned, how to select the target, and the mutual exclusivity constraint. It doesn't specify ordering or pagination, but the annotations cover safety and the parameter semantics are fully documented. The tool is simple enough that this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the semantic distinction between 'received' and 'given', clarifying that direction is only meaningful with username, and stating the exactly-one-required constraint. It doesn't add format details beyond the schema, but the schema is already rich.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads individual ratings including review text, not just averages. It distinguishes from the inline job results and names the two access modes (username or job_id). The title and description align, and the tool is easily differentiated from siblings like submit_rating and get_bids.
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 explicitly states when to use each parameter: pass username for all ratings a user received, add direction 'given' for ones they left, pass job_id for both ratings on a job. It also states the mutual exclusivity requirement and that exactly one of username or job_id is required. This is clear routing guidance with no ambiguity.
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 poster'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 mark this read-only/idempotent, and the description adds meaningful non-obvious behavior: no account required, public visibility, exact cancellation semantics ('cancellations this person performed -- either party to an in-progress job can cancel it'), and equivalence to browse_users counting. It clarifies a subtle trap (cancelled jobs include jobs they only bid on), which is beyond what annotations 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?
The description is front-loaded with the verb-resource sentence and then packs useful field detail and use-case into two trailing sentences. It is longer than necessary and could be bulleted, but every clause adds information (cancellation nuance, no-account access, relationship to inline ratings).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with no output schema, the description covers what the response contains, the access/authorization behavior (no account), and the intended decision context. Nothing an agent needs to choose or call this tool correctly is missing, and the annotation set reinforces safety.
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%: the only parameter username is already documented as a public username, not UUID, matched exactly including capitalization. The description only repeats 'by username' and adds 'public', so it adds little semantic value beyond the schema, which earns the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and direct object – 'Fetch a user's public profile by username' – then enumerates the contained fields (rating, completed/cancelled jobs, transacted total, activity counts), making it unmistakable what this tool returns. It also positions itself against related data: it is the website's public profile as opposed to inline rating snippets in job results.
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 an agent when to invoke it: 'use it to judge a counterparty before bidding on their job or accepting their bid'. It also notes that job results already inline rating average/count, so the agent knows when this tool adds the rest, though it does not name sibling tools like get_user_jobs or get_me as exclusions.
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 poster and the freelancer they HIRED -- the one thread the hire itself makes public. It appears only on a row whose owner is in that thread: on a poster 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?
Beyond the readOnly/idempotent/destructive annotations, the description discloses crucial runtime behavior: sealed bids are hidden for third-party viewers, my_bid.amount and message_count are null rather than zero, and message_count has a narrower meaning than in get_my_jobs. It also explains the outcome field lifecycle and the visibility constraints around hired threads, giving an agent a reliable model of what the response contains.
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, but every sentence carries load-bearing semantic detail about nulls, sealed bids, and message_count that directly affects how an agent interprets results. It is front-loaded with the one-sentence purpose, and the dense follow-up paragraphs are justified by the complexity of the returned data.
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 full responsibility for explaining return semantics, and it does so exhaustively: merged rows, role tags, pagination compatibility, is_accepted, sealed behavior, null rules, message_count scope, and outcome values. An agent has enough information to call the tool and correctly interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all five parameters with 100% coverage, so the description does not need to repeat parameter mechanics. It adds useful response-shape context (e.g., row role tags and sealed semantics) but does not materially deepen the meaning of the request parameters themselves, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb ('List') with a clear resource ('what one user has posted and bid on') and public scope, which distinguishes it from get_my_jobs and other sibling tools. It additionally specifies the result shape upfront, leaving no ambiguity about what the tool retrieves.
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 makes clear this is the public profile view of one user's activity and repeatedly contrasts its semantics with get_my_jobs, which gives strong context for when to use it. It does not explicitly state exclusions such as 'use get_my_jobs for your own account,' but the profile-page/anyone framing and sibling comparison imply the intended usage well.
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 poster, 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?
Beyond the annotations (idempotentHint=true, readOnlyHint=false), it adds account-level semantics, return format, authorization constraints, and the interplay with website sessions. No contradictions with 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?
Well-structured with core effect first, then usage, then edge-case behavior. A bit verbose for a 1-parameter tool, but every sentence serves the agent's correct invocation.
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?
Complete: explains side effects on other endpoints, return values, idempotency, account-scoped state, and permission restrictions. No output schema exists, so the return description compensates.
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 only parameter, job_id, is fully documented in the schema (UUID, pattern). The description does not add meaning beyond that, which is acceptable given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('record'/'clears') and resource (job's seen state), and precisely describes the effect on get_my_jobs. Distinguishes itself from sibling tools like get_job and get_my_jobs by explaining the state change.
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 instructs when to call: 'after reading a job's messages or bids.' Also explains the desired outcome, that the next get_my_jobs will show only what arrived since, leaving no ambiguity about the appropriate trigger.
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 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. | |
| 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 declare it is a non-read-only, destructive, non-idempotent operation, and the description adds material detail beyond that: the $2 fee is charged immediately and a saved payment method is required. It does not address what happens to a failed charge or whether the fee is refundable, but this is solid added context against an already-covered safety profile.
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 primary action stated first and the cost/permission constraint immediately after. 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 mutation tool with no output schema, the definition covers the action, the actor, the monetary side effect, and the payment prerequisite. It leaves unaddressed what the tool returns on success and the failure/refund path for the fee, but the rich schema covers inputs thoroughly and annotations cover safety.
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 six parameters are already well documented in the schema, including the nuanced enum semantics for 'category' and the idempotency_key retry rationale. The description adds no parameter-level meaning beyond the schema, which is the expected baseline when the schema carries the load.
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 (post) and resource (job listing) with an explicit actor ('as the authenticated user'), and anchors it to the website's 'Post a Job' form. Clearly distinguishable from read-side siblings like get_job, browse_jobs, and get_my_jobs.
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 the precondition that a saved payment method is required and that posting charges a fee, which is genuinely useful context. However, it never states when not to use this tool or names alternatives (e.g. cancel_job, get_my_jobs for managing existing posts), leaving usage implied.
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 poster to close an in-progress job, as the freelancer working on it. Use this after delivering, when the poster has gone quiet. It starts a 7-day clock: if the poster marks the job complete or cancels it, that resolves the job normally, and if the poster sends any message on the job the request is cleared and you can ask again later. Only the accepted freelancer 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?
The description adds substantial behavioral context beyond the annotations: the 7-day clock, message-clearing behavior, idempotent pending request semantics, hourly sweep timing, and the caution that releases_at is the earliest possible moment, not an appointment. This is exactly the kind of non-obvious behavior an agent needs to know, and it does not contradict 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?
The description is front-loaded with the core purpose and then proceeds through consequences, constraints, and edge cases in a logical order. Every sentence earns its place by conveying operational detail that would otherwise be invisible to the agent; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a side-effectful tool with one parameter and no output schema, the description is remarkably complete. It covers role restrictions, state requirements, idempotency, return fields, timing semantics, and potential misinterpretations of releases_at. An agent has enough information to call the tool correctly and interpret its 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?
The only parameter, job_id, is fully documented in the schema with type, format, pattern, and description, so the schema already carries the semantic load. The tool description adds no additional parameter-specific detail, but with 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Ask the poster to close an in-progress job, as the freelancer working on it.' It clearly identifies the role, the job state, and the fact that this is a request rather than a direct action, which distinguishes it from sibling tools like cancel_job and complete_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 gives explicit when-to-use guidance: 'Use this after delivering, when the poster has gone quiet,' and clear when-not-to-use conditions: 'Only the accepted freelancer on the job may call this, and only while the job is in progress.' It does not explicitly name alternative sibling tools, but the context and exclusions are otherwise quite clear.
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 poster, the recipient must be someone who has actually bid on the job. If you're a bidder, the recipient must be the poster.
| 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?
The description discloses recipient eligibility rules, which is useful behavioral context. However, annotations already indicate the tool is not read-only and is destructive, and the description does not add further behavioral details like rate limits or delivery semantics. It does not contradict 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 two sentences, front-loaded with the core action, and each sentence earns its place. The first sentence defines the operation; the second provides critical eligibility details. No redundancy or 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 3-parameter write tool without an output schema, the description covers the essential use case and the key constraints. It could mention that the message is added to the job's conversation, but that is implicit. Overall, it is sufficiently complete for correct invocation.
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%, providing baseline clarity for all three parameters. The description adds meaningful semantics by explaining the relationship between job_id and to, defining who can be a valid recipient based on the user's role (poster vs. bidder), which is not fully captured in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (send a message), the resource (a job), and the recipient (a specific other participant). The eligibility rules further clarify scope, making it distinct from read-only sibling get_messages.
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 on when to use the tool by specifying who can be messaged: the poster must message a bidder, and a bidder must message the poster. This is operational guidance, though it does not explicitly discuss alternatives or when not to use the tool.
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 poster 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 poster 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 poster |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive and non-idempotent, and the description substantially expands on that: the bid is irreversible, cannot be edited, cannot be repeated after withdrawal, pays out 90% on completion, and only the poster can trigger completion. This gives the agent an accurate model of the tool's real-world effects.
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?
Five dense but purposeful sentences. The core purpose comes first, followed by the highest-stakes constraints, prerequisites, and payout consequences. There is no filler or repetition that undermines the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, irreversible financial action with no output schema, this description covers eligibility, prerequisites, bid limits, withdrawal consequences, payout percentage, and who can complete the job. An agent has enough context to decide whether and how to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters at 100% coverage, so the baseline is 3. The description reinforces that amount refers to the bid amount and implies job_id targets an open job, but it does not add significant meaning beyond what the schema provides.
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?
Opens with 'Submit a bid on an open job, as the authenticated user' — a specific verb, resource, and actor scope. The added constraints about not bidding on your own job and one bid per job further distinguish it from related actions like accept_bid or withdraw_bid.
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 concrete preconditions: the job must be open, you must not be its creator, and you need a completed Stripe Connect payout account. It does not explicitly name sibling alternatives such as withdraw_bid or accept_bid, but the conditions for valid use are clear and actionable.
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 poster 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 poster if you're the accepted bidder, or the accepted bidder if you're the poster |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag the operation as non-read-only and destructive, so the description doesn't need to restate that. It adds valuable behavioral context: the job must be completed or cancelled, the rating is restricted to the two counterparties, and it can only be submitted once per job. These constraints go beyond the annotation 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?
Two compact sentences with no filler. The first states the core action and condition, and the second packs all eligibility constraints efficiently. The most important scoping information 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 write operation with strong annotation coverage and a fully described schema, the description covers when to use it, who is allowed, and how often. It doesn't describe the success/error response, but there is no output schema and the behavioral constraints are already well specified, so this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters at 100%, including the important counterparty mapping in rated_user_id and the 1–5 range for score. The description reinforces these rules but doesn't add parameter-level detail beyond what the schema provides. A baseline 3 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?
The description states a specific action ('Rate your counterparty') and a clear resource (a job that is completed or cancelled), with eligibility rules that distinguish it from read-only siblings like get_ratings. The title and description align, making the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells when to use the tool: only after a job is completed or cancelled, and only for the poster or accepted bidder. It also states exclusions: not a third party, not yourself, and only once per job. It doesn't explicitly name alternatives, but the context is sufficient to avoid confusion with get_ratings or report_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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
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."report_gapmark_job_seenHire 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.
Let your AI agent hire a human for tasks it can't do — first post free.
Add one secure layer between your agents and this server.
