complete_jobMark 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. Releases 90% of the escrowed amount to the freelancer; 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 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.
Add one secure layer between your agents and this server.
Each tool targets a distinct resource and action: job lifecycle, bidding, messaging, ratings, users, and documents all have clear boundaries. Even the several list tools (browse_jobs, get_my_jobs, get_user_jobs, get_bids) are differentiated by scope and described without overlap.
All tool names follow a consistent snake_case verb_noun pattern, e.g. accept_bid, cancel_job, submit_rating, withdraw_bid. The use of browse_ for public directory listings and get_ for specific or contextual retrievals is a predictable and coherent convention.
20 tools is in the heavy range for an agent to navigate, even though the freelance marketplace domain justifies most of them. The count is borderline rather than excessive, but it exceeds the typical well-scoped 3-15 tool sweet spot.
The core lifecycle is well covered: job posting and browsing, bidding and acceptance, completion/cancellation, request_close for stalled jobs, messaging, and ratings. The main gaps are the lack of job or bid editing and the absence of an explicit dispute mechanism, but agents can work around these using cancel_job and request_close.