Freelance Clearing

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

Fully discloses the side effects: moves job to in_progress, charges full bid into escrow, requires payment method and Stripe Connect account, validation checks. Annotations only give destructiveHint=true; the description goes far beyond by explaining the exact charge flow and prerequisites. No contradiction.

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

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

Three sentences, densely packed with purpose, role restrictions, and side effects, all front-loaded. No filler. Every clause carries meaningful information.

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

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

Given there is no output schema, the description explains the outcome (job moves to in_progress, escrow charge) well enough. It covers authorization, prerequisites, and state change. Slight deduction for not stating whether the bid amount is returned if the job later is cancelled or fails, but that's beyond the core call, so still strong.

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

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

Schema already covers 100% of parameters with a clear description ('The bid's UUID (not the job's)'). The description reinforces the meaning by explaining the tool's role relative to the bid, but adds no new parameter-specific detail beyond schema. Baseline 3, raised to 4 because the 'not the job's' caveat prevents a likely mistake, and the tool description aids semantic understanding.

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

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

States a specific verb+resource: 'Accept a specific bid on a job, as that job's poster.' It clearly distinguishes from siblings like submit_bid, withdraw_bid, and get_bids by focusing on the acceptance action. It is unambiguous about who can act and on what.

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 it applies ('as that job's poster'), what is rejected (bidder accepting their own bid, non-poster), and the conditions (saved payment method, bidder's completed Stripe Connect account). It also references a timing consideration relative to submit_bid, giving clear selection guidance.

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

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

The readOnlyHint annotation already indicates no side effects. The description adds transparency about pagination behavior and the presence of status_counts, giving the agent a clear picture of what the response contains without contradicting the annotation.

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 somewhat verbose, with the last sentence repeating the idea that the default view is open jobs only. It is structured logically but could be tightened to reduce redundancy while preserving key information.

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

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

The description provides essential context: the tool's role, default filters, pagination, and how to assess market activity via status_counts. It does not describe the full response format, but given the absence of an output schema and the tool's simple nature, this is adequate.

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?

All parameters are fully described in the input schema (100% coverage), so the baseline is 3. The tool description itself does not add extra parameter semantics beyond re-stating the default behavior, but it does not need to 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 clearly states the tool's purpose: listing jobs on Freelance Clearing, equivalent to the Browse page's Jobs tab. It differentiates from siblings by focusing on browsing all jobs with filters, distinct from user-specific or job-specific tools.

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

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

The description explains defaults (open status, pagination) and provides guidance on how to explore other statuses and interpret status_counts for market activity. It does not explicitly contrast with alternative browse tools, but the context is sufficient for typical usage.

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

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

ReadOnlyHint annotation already signals safety; the description adds useful behavioral context about verified accounts, api_active meaning, and that sorting/filtering are user decisions rather than platform rankings. No contradictions.

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 but every sentence carries relevant information: what is listed, special fields, verification, sorting philosophy, and use case. No redundant phrases.

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 enumerates returned fields and mentions pagination, giving enough context for an agent to understand what it will receive. Slightly more detail about response shape would push it higher.

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 parameters with descriptions; description adds valuable details like the website-default sort order, how unrated users sort, and how to use offset with the pagination block.

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?

Clearly states the tool lists people on Freelance Clearing, equivalent to the Browse users tab, and explains its purpose of finding someone to hire without a starting job. This distinguishes it from job-focused siblings like 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?

Explicitly says to use it when you need to find a hire without a job to start from, and notes that without it a counterparty is only reachable through a job they posted or bid on. It gives good context though it doesn't name sibling alternatives directly.

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

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

Beyond the destructiveHint=1 annotation, the description clearly discloses the consequences: 95/5 escrow refund on in-progress cancellations, free cancellation while open with non-refundable posting fee, and individual notification of all bidders. It also notes reason requirements. This is rich behavioral context added beyond the annotation.

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

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

Three dense sentences front-loaded with the core action, followed by permission conditions, then financial and notification consequences. Every sentence contributes unique information and there is no filler.

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

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

The description is complete for an operation with only two parameters. It covers state-based permissions, reason requirements, refund/fee outcomes, and notification behavior. Missing return value details are fine because there is no output schema and the operation is a mutation.

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 both parameters and both are straightforward. The tool description adds meaningful semantics by explaining when 'reason' is required (in-progress or open-with-bids) versus optional (open with no bids), and states the reason is shared with the other party. This extra conditional meaning merits a score above the high-coverage baseline of 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?

The description clearly identifies the operation ('Cancel a job') and an exact resource, plus the two relevant states (open vs. in progress) and the permissible actors in each state. It does not explicitly name sibling alternatives, but the role constraints and cancellation semantics make the purpose 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?

The description gives solid context on when cancellation is allowed, who may cancel, and when a reason is required vs optional. It does not explicitly tell the agent when to choose a sibling tool (e.g., withdraw_bid or complete_job), so it falls short of full explicit routing advice.

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

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

The description goes well beyond the destructiveHint annotation by detailing the exact state change, the financial effect (releases 90% of escrow), the authorization restriction, and a specific failure condition. It discloses the key behavioral consequences of this destructive action, which is exactly what an agent needs to understand the 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 two sentences, front-loading the core purpose and actor, then adding constraints and effects. Every clause contributes meaningful information without redundancy or filler, making it efficient and easy to parse.

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

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

Given the tool is a destructive, financial operation with a single parameter and no output schema, the description covers all essential aspects: authorization, state change, escrow release, failure conditions, and intent. An agent has enough information to decide when and how to invoke it safely.

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% for the single parameter job_id, whose description ('The job's UUID') already conveys its meaning. The tool description adds no additional semantic information about the parameter, so it meets the baseline of 3 but does not elevate itself further.

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 ('Mark a job as complete') and identifies the resource ('job'), and clearly distinguishes itself from siblings by specifying the actor ('as that job's poster') and the state transition (in_progress to completed). It explicitly differentiates from cancel_job, request_close, and other job actions, so an agent can select it unambiguously.

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 guidance on who can use it ('Only the poster can do this -- not even the accepted bidder can mark their own job complete') and states a prerequisite ('fails if they haven't finished Stripe Connect payout onboarding'). It implies this tool is for finalizing completed work, though it doesn't explicitly compare alternatives like cancel_job or request_close. The context is sufficient for correct invocation in most cases.

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

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

Annotations only provide readOnlyHint=true, but the description adds rich behavioral information: non-poster callers during an open job receive an error rather than an empty list, post-close visibility becomes public, and each bid includes the bidder's rating average and count. This goes well beyond the annotation and clarifies user-visible semantics.

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 information-dense: each sentence adds distinct value about scope, state-dependent visibility, error behavior, or return contents. While it is longer than a one-liner, the extra length is justified by genuinely useful rules about who can see what.

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 list tool with no output schema, the description covers what is needed to call it correctly: the job identifier, access restrictions, state transitions, error-versus-empty behavior, and the rating fields included in the response. Nothing essential is missing at this tier of complexity.

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

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

There is a single param, job_id, and the schema already covers it with type, format, and a clear description at 100% coverage. The description does not add parameter-level meaning beyond saying the bids are 'on a job,' so the baseline score of 3 applies.

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

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

The description starts with a specific verb and resource: 'List the bids on a job.' It makes the tool's scope clear by tying the resource to job_id, and the detailed visibility rules help distinguish it from broader browsing tools like browse_jobs or 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 description gives clear context for when calls succeed and fail: during an open job only the poster can see bids, and after closure the bid history is public. It also explains the error-versus-empty behavior. It stops short of naming explicit alternatives or saying 'use X instead,' so it is very strong but not a perfect 5.

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

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

Annotations already indicate readOnlyHint=true; the description adds that it returns full markdown and details the content of each document. It does not describe any side effects or error behavior, but for a read-only fetch this is adequate.

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 moderately long but well-structured: first sentence states function, second explains rationale, third and fourth elaborate on document contents. It is not overly verbose and reads naturally.

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 explains the return format (full markdown) and the content of each document, which is sufficient for most use cases. It does not mention error handling, but that is not critical for this simple read-only 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?

The schema already fully describes the parameter with enum and per-value descriptions. The tool description repeats these values and adds context about what each document contains, but does not add new semantic depth beyond the schema.

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

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

The description explicitly states the tool fetches published documents (terms, privacy, about) in markdown. It clearly distinguishes from sibling tools like get_job or get_user by focusing on document retrieval.

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 explains when to use the tool: whenever an agent needs the site's terms, privacy policy, or about information, avoiding web page fetches. It gives clear context and content details, making usage obvious.

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

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

The description goes well beyond the readOnlyHint annotation by explaining subtle behavioral semantics: the lifecycle of close_requested_at (cleared on any poster message), auto_released_at (only set after 7 unanswered days with automatic payment release), and the inference that a completed job with auto_released_at set was never marked complete by the poster. This is valuable interpretive context that an agent needs to correctly understand the returned data, and it adds significant value beyond the annotation.

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 in the first sentence, then uses two additional sentences to explain two non-obvious close-request fields. Every sentence earns its place; the field semantics are necessary for correct interpretation and are not present in the schema or annotations. It is appropriately sized for the information it conveys.

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 is remarkably complete. It covers the reach of the operation (any status), explains the two edge-case fields that would otherwise confuse an agent, and relies on the schema for the job_id format. Nothing essential for calling this tool correctly is missing.

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

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

Schema coverage is 100% for the single parameter job_id, including its description 'The job's UUID.' The tool description adds only the phrase 'by id,' which does not meaningfully improve on the schema. The baseline of 3 applies because the schema already documents the parameter fully.

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: 'Fetch full detail for a single job by id.' It also clarifies scope with 'regardless of its status (open, in progress, completed, or cancelled),' which clearly distinguishes it from list-oriented siblings like get_my_jobs or get_user_jobs. An agent immediately knows what the tool does and what it is not.

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 the appropriate use case: when you have a job id and need complete detail for that job, independent of its current status. It does not explicitly name alternatives or say 'use get_my_jobs to list your jobs,' but the 'by id' and 'regardless of status' phrasing provides clear situational context. The guidance is adequate though not explicitly exclusionary.

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

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

Although the readOnlyHint annotation already marks this as a safe read operation, the description enriches transparency by disclosing that it also reports capability checks ('whether you can currently post a job or place a bid') and even includes guidance ('with why not and where to fix it'). This goes beyond the schema and annotations, giving agents behavioral insight into what the response contains without contradicting the read-only nature.

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 entire description is a single, information-dense sentence. It front-loads the primary purpose, lists the key output fields in a natural list, and adds the capability-check nuance without a single wasted word. Every element earns its place, making it exemplary in conciseness and structure.

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

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

For a parameterless, read-only tool, the description covers all essential aspects: returns identity fields and capability status. While it doesn't detail the exact response schema (e.g., JSON structure or data types), the absence of parameters and the simplicity of the self-inspection use case mean the description is nearly complete. A minor enhancement would be noting the response is for the authenticated user, but that is implicitly obvious from 'your own identity.'

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 schema is trivially complete. The description indirectly reinforces that no arguments are needed by focusing entirely on the implicit context (the caller's identity), which aligns with the baseline score of 4 for parameterless tools. No additional parameter-level explanation is required.

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 ('Get'), a clear resource ('your own identity and capabilities'), and enumerates concrete data points (user id, username, join date, rating, posting/bidding eligibility). This clearly distinguishes it from sibling tools like 'get_user' by explicitly scoping to the caller's own record, leaving no ambiguity about what this tool does.

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 implies when to use this tool (to inspect your own identity and capabilities) versus siblings like 'get_user' for other users. While it doesn't explicitly name alternatives or state when *not* to use it, the self-referential framing makes the intended use unmistakable, providing clear context without exclusions.

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

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

Despite the readOnlyHint=true annotation, the description goes further by disclosing role-scoped visibility, oldest-first ordering, and that the results include automatically generated system messages. These are genuinely useful behavioral facts an agent could not infer from annotations or the schema.

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

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

Three focused sentences deliver purpose, role-based behavior, ordering, and message composition without redundancy. The key purpose is front-loaded, and every remaining sentence adds operational information.

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

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

For a simple one-parameter, read-only operation with no output schema, the description covers the essential facts an agent needs: what messages are returned, who can see what, ordering, and the presence of non-human-authored messages. Nothing necessary for correct invocation or interpretation 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%, since job_id is fully defined with its UUID constraints. The description does not add independent parameter-level meaning beyond 'for a job,' but at full 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 uses a specific verb and resource: 'Read the messages for a job.' It further disambiguates the tool by explaining that the poster sees all conversations while a bidder sees only their own thread, which distinguishes it from sibling read tools like get_bids and 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 intended use is clear: call this to read messages associated with a specific job, and the role-based visibility instructions tell callers what to expect depending on who is acting. There is no explicit exclusion or named alternative, but no near-identical sibling exists, so this level of context is sufficient.

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

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

The description adds significant behavioral context beyond the readOnlyHint annotation: it explains that unread/new-message flags are intentionally absent and the API cannot mark threads read, and it clarifies role-dependent output shape for posted jobs vs bid-on jobs. This is exactly the kind of nuance that protects an agent from assuming misleading affordances.

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 four dense, purposeful sentences that front-load the core purpose before adding behavioral and field-level context. Every sentence earns its place, and the pointer to get_job avoids duplicating detailed field explanations.

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 return semantics, and it does well by covering posted vs. bid jobs, acceptance signals, absent message flags, and the unusual close_requested_at/auto_released_at fields. It does not mention default ordering, which is relevant when paginating, so it is not fully 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 coverage is 100%, so the parameter descriptions already define role, limit, offset, and status. The tool description mentions "with pagination" and posted/bid relationship but adds no material parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: "List jobs you've posted and/or bid on." It clearly distinguishes the tool from siblings like browse_jobs and get_user_jobs by scoping it to the caller's own jobs and by role, and it even points to get_job for additional field semantics.

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 role filter and the phrase "jobs you've posted and/or bid on" make the intended use case clear. It also refers the agent to get_job for field meanings, but it does not explicitly say when to prefer browse_jobs, get_user_jobs, or get_job as alternatives.

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

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

The readOnlyHint annotation already signals the operation is non-mutating, and the description adds valuable context by explaining that return includes the written review text, not just the average, and enumerates the fields each rating carries. It also clarifies that direction 'given' changes the perspective from received to left ratings. The description does not mention pagination, ordering, or rate limits, but for a read-only tool with this clarity that 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 four sentences long and each one serves a distinct purpose: scope, how to query by username, how to query by job, and what the output contains. It is front-loaded with the read intent and the contrast to the average, then it gives operating instructions. No unnecessary words or repetition are present.

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 description fully explains the parameters, the mutual exclusivity, the default direction setting, and the output fields, which compensates for the absence of an output schema. It lacks explicit mention of ordering or pagination behavior for a user with many ratings, but these are not necessary for an agent to invoke the tool correctly in most cases. Overall, the description is sufficiently complete for a read-only three-parameter 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?

Even though the schema descriptions already cover 100% of the 3 parameters, the description adds meaning beyond them: it explains the default behavior of direction ('received'), defines exactly how username and job_id are mutually exclusive, and gives semantic context like 'the ones they left instead' and 'both ratings on a single job'. It also states that exactly one of username or job_id is required, which the schema alone does not enforce.

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 'Read individual ratings, including the written review text', which precisely names the verb and resource while distinguishing this from the inline average shown elsewhere. It also explicitly contrasts itself with the aggregated 'average that job results inline', making the tool's unique 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, explicit instructions for all modes: pass username for ratings received, add direction 'given' for ratings left, or pass job_id for both ratings on one job. It clearly states the mutual exclusivity requirement. However, it does not explicitly mention alternative sibling tools or conditions where a different tool should be chosen instead.

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

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

The readOnlyHint annotation already establishes the operation is safe, and the description adds the important behavioral detail that no account is required and the data is exactly what the public profile page shows. This clarifies authentication needs and scope beyond the annotation.

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 resource and output fields, then adds use-case and differentiation context. Every sentence carries information; the extra phrasing is minor and does not obscure the main point.

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 enumerates every returned field. This is a simple single-parameter read tool, and the description tells the agent what it will get, when to use it, and that no account is needed. Nothing essential is missing.

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

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

The schema provides 100% coverage for the single parameter, including that it is a 'public username, not their UUID.' The description merely restates that it is fetched 'by username' and does not add new meaning beyond the schema, 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 description opens with a specific verb and resource: "Fetch a user's public profile by username." It then lists the exact fields (description, join date, rating average/count, completed/cancelled jobs, total transacted), which distinguishes it immediately from account-level tools like get_me and browse-style tools like browse_users.

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

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

The description gives a concrete use case: judge a counterparty before bidding on a job or accepting a bid. It also provides scoping context by noting that job results already inline rating average/count and this tool provides 'the rest of it.' It falls short of a 5 because it doesn't explicitly name when-not-to-use or a specific sibling alternative.

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

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

Annotations only declare read-only status, so the description carries the behavioral load. It discloses that responses include a `is_accepted` field on bidder rows, that results are paginated in a specific way, and that open bids are sealed for other users. This goes well beyond the schema and helps an agent interpret returned data.

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, well-paced paragraph that leads with the core purpose and ends with a crucial caveat about sealed bids. Every clause adds value: the reference to get_my_jobs clarifies the shape, and the bid-sealing note prevents misinterpretation. It's informative without being 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?

For a filtered list endpoint with five parameters and no output schema, the description appropriately references get_my_jobs for the full response shape while highlighting the subtle is_accepted field and pagination behavior. It covers typical usage, edge cases (open bids), and points to a sibling for schema details. The only minor gap is not restating the complete field list, but that's available in the sibling's definition.

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?

Input schema already documents all five parameters with strings like 'Default both. Same values get_my_jobs takes.' and appropriate enums, so the baseline is 3. The description adds no new parameter-level detail; its discussion of role tags refers to response rows, not request parameters. Therefore the schema carries full semantic 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 opens with a specific verb and object ('List what one user has posted and bid on'), clearly identifying the resource as another user's activity. It distinguishes itself from the sibling get_my_jobs by referencing the same shape and highlighting the difference in bidder data visibility. This makes its purpose unambiguous relative to browse_jobs or 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?

The description explicitly names get_my_jobs as a comparison point and explains the key difference: sealed bids on open jobs are hidden for other users but visible for oneself. This tells the agent when to expect different results and implies this tool is appropriate for viewing another user's public job activity. It doesn't explicitly blacklist other alternatives, but the guidance is clear.

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

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

Beyond the destructiveHint annotation, the description discloses a $2 immediate charge and a saved-payment-method requirement, which are critical behavioral consequences. It also indicates the operation is performed as the authenticated user, implying auth expectations. This adds meaningful context beyond what the annotation provides.

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 fluff. The primary purpose is front-loaded, and the crucial fee/payment caveat is placed directly after. Every word adds value, and there is no redundant information repeating the schema or title.

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

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

For a tool with six parameters and no output schema, the description covers the operation at a sufficient level: it states the action, auth context, the fee, and the payment requirement. The schema handles parameter details. It could mention the idempotency key or return type, but those are either in the schema or not critical for successful 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?

The input schema has 100% coverage, with each parameter already described in detail (including the idempotency key's role in avoiding double charges). The description itself does not add parameter-specific semantics beyond the fee context, so the baseline of 3 applies as the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'post a new job listing, as the authenticated user.' It also anchors the action by referencing the website's 'Post a Job' form, so the intended operation is unmistakable. This clearly distinguishes it from the sibling tools, none of which create a 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 description provides clear context by specifying the tool is for posting a new job listing and that it requires authentication and a saved payment method. It doesn't explicitly name alternatives or exclusion conditions, but since no other sibling tool creates jobs, the intended use is self-evident and doesn't need a contrast.

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

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

The description explains the full side-effect model: the 7-day clock, how a poster message clears the request, that cancellation or completion resolves normally, and that repeated calls return the original request time. It even clarifies that releases_at is the earliest release moment due to hourly sweeping. This adds detail far beyond the single idempotentHint annotation and contains no contradiction.

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

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

The description is fairly long, but every sentence adds behavioral nuance critical to correct use, such as the idempotent behavior and the hourly sweep caveat. It is well-structured, starting with a clear summary, then usage context, preconditions, and important timing details, earning a high score despite the length.

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 enumerates the returned values, the precondition, the timeout mechanism, and an important edge case to avoid false alarms. It is thorough for a single-parameter tool, leaving no gaps for an agent to proceed.

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 the only parameter job_id with a description ('The job's UUID') and format, so the baseline is 3. The description does imply that the job must be in progress and accepted, but that is contextual rather than adding parameter-specific semantics. No new parameter guidance is needed beyond the schema, so 3 is appropriate.

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

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

The description clearly states a specific verb and resource: the freelancer asks the poster to close an in-progress job. It also specifies the role ('as the freelancer working on it') and differentiates it from cancel_job or complete_job, which are actions the poster or system takes rather than requests.

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 says to use this after delivering when the poster has gone quiet, and gives exact conditions: only the accepted freelancer, only while the job is in progress, and what happens if a request is already pending (do not call again). This clearly tells the agent when better to invoke it and when it is unnecessary.

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

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

No contradiction with the destructiveHint annotation. The description adds useful behavioral context about participant eligibility, which is not implied by the schema alone.

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

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

Two concise sentences with no filler. The key constraints are front-loaded and clearly written.

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?

Provides essential context about participant rules. While it doesn't describe response/error behavior, the tool's purpose and constraints are adequately covered for a message-sending operation.

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 all three parameters with descriptions, so baseline is 3. The description adds meaning to 'to' by clarifying it must be a participant tied to the job, and explains the role relationship between 'to' and 'job_id'.

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

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

States a specific verb ('send') with a clear resource ('a message on a job') and target ('a specific other participant'). Clearly distinguishes from get_messages and other job-related tools.

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

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

Explicitly defines when to use: the role-based constraints (poster can only message bidders, bidder can only message poster) provide clear usage conditions and prevent misuse.

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

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

Annotations are minimal (only destructiveHint=false), so the description carries most of the behavioral burden. It discloses the irreversible nature of the bid, the 90% payout, and the dependence on the poster for completion. It goes beyond the annotation by detailing the payment and editing restrictions, which is valuable. However, it doesn't specify what happens if the bid is rejected or if the job is not completed, so slightly imperfect.

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 well-structured paragraph, starting with the core action and then layering critical constraints. It is dense but not verbose, with each sentence adding essential information for the agent. Slightly long but justified given the number of constraints; no wasted words.

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

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

For a complex transactional tool with no output schema and minimal annotations, this description covers the major prerequisites, lifecycle rules, and payment implications. It misses some edge cases (e.g., error conditions, whether the bid can be seen by others), but overall it provides sufficient context for an agent to make an informed call.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds context like 'decide the amount before calling' and 'pitch to the job's poster', but these are supplementary to the schema. Baseline 3 is appropriate as the description adds some value but doesn't significantly extend meaning.

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 verb (submit) and resource (a bid on a job), and explicitly states the context of the authenticated user. It distinguishes itself from siblings like 'withdraw_bid' by describing the bid lifecycle and rules, ensuring an agent can identify its purpose.

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 provides explicit conditions for use: cannot bid on own job, one bid per job, requires Stripe Connect payout account, and warns about payment timing and amount. It effectively guides the agent on prerequisites and consequences, though it does not name alternative siblings explicitly, but the context makes the usage clear.

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

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

Annotations declare destructiveHint=true, so the agent knows this is a mutation. The description adds context about the restricted eligibility and one-time nature, which is beyond annotations. It does not mention irreversibility or whether ratings can be updated, but the annotation already signals 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?

The description is two sentences, front-loading the core action and then packing eligibility constraints into the second. No wasted words.

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

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

For a mutation tool with destructiveHint and no output schema, the description covers when and by whom it can be used, which are the critical constraints. It could mention that the rating is final or that comment is optional, but the schema already covers comment's optionality, and the constraints are the main thing an agent needs.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for 'rated_user_id' by explaining the relationship (poster/bidder), which clarifies a parameter that could be ambiguous. It also reinforces the score range implicitly, though the schema already documents it.

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 verb 'Rate' and the resource 'your counterparty on a finished job', and it distinguishes from siblings like complete_job and get_ratings. It specifies the exact condition (completed or cancelled job) and scope.

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 says when to use the tool: on a completed or cancelled job, and it lists exclusions: only the poster and accepted bidder can rate each other, not third parties or self, and only once per job. This clearly differentiates from siblings like get_ratings (viewing ratings) and complete_job (marking job done).

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

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

The description goes beyond the destructiveHint annotation by detailing the permanence of the action ('This is permanent and cannot be undone'), the consequence ('you cannot bid on that job again'), and the specific error case for re-bidding. This is rich behavioral context that the annotation alone does not provide.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value. It covers the action, constraints, permanence, and a critical warning without any fluff.

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 tool with a destructive annotation, the description is complete. It covers the action, conditions, consequences, and error handling. The output schema is absent, but the description doesn't need to explain return values for a simple withdrawal action.

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

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

The schema already provides 100% coverage with a clear description ('The bid's UUID') and format constraints. The description adds no additional parameter semantics beyond what the schema provides, 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 description clearly states the action ('Withdraw your own bid on a job'), the actor ('as the bidder who placed it'), and the resource ('a job'). It distinguishes from siblings like submit_bid and accept_bid by specifying the withdrawal context and constraints.

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 this tool is applicable ('Only possible while the job is still open and your bid hasn't been accepted') and provides a clear exclusion ('Do not withdraw in order to re-bid at a different amount -- the second bid will be rejected with already_bid'). This gives the agent strong guidance on when to use it and when not to.

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