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

Annotations already declare readOnlyHint and openWorldHint, so the bar is lower; the description still adds 'no API key needed', the newest-first ordering, and the off-server application constraint, all of which affect how an agent acts on results. It does not state rate limits or what happens on empty results, but the important behavioral traits are covered.

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

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

Front-loads the core verb and resource, then layers usage and alternatives in descending priority. Four sentences with almost no waste, though the returned-fields sentence is dense and could be trimmed if an output schema existed.

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

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

With no output schema, the description carries the return-shape burden and does: ID, title, category, budget, short description. Combined with pagination limits, the read-only/off-server constraints, and sibling routing, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents limit, category and budget_type, including the enum and the 'only first page' caveat. The description adds only the returned-field list and reiterates the limit cap, so baseline 3 is appropriate rather than credit for new parameter 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?

States a specific verb and resource ('Browse public job posts on GoHireHumans that are accepting applications, newest first'), including scope and ordering. It is immediately distinguishable from search_services, search_workers, and get_job_status, all of which are named in the description.

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

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

Gives explicit when-to-use ('to find work to apply for or to see what buyers are asking for') plus a critical when-not: applications happen on gohirehumans.com, not through this server. It also routes to the correct siblings for hiring and for single-job status, with the selecting condition stated.

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?

Adds substantial context beyond annotations: immediate publication with status 'open', possible worker notifications, no hiring or charging, and an explicit statement that this server cannot edit or close a job. It also discloses the auth requirement (GOHIREHUMANS_AUTH_TOKEN or write-scoped API key), which annotations do not cover.

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 purpose, then prerequisites, side effects, and alternatives in a logical order. It is a dense paragraph with no filler, though slightly long for a single tool.

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 present, the description compensates by stating the return value ('the new job ID and status') and how to track it. Combined with the side-effect, auth, and limitation disclosures, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the enum constraint on budget_type and the whole-cents budget rule. The description adds only the approval prerequisite for title/description/budget rather than new per-parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Publish a new job post on GoHireHumans') plus the effect on workers ('that workers can apply to'). It also distinguishes itself from the sibling hire_worker by naming that alternative outright.

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

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

Explicitly states the prerequisite (owner approval of title, description and budget) and routes the agent to the right sibling for a different task ('To order an existing service listing instead, use hire_worker'). It also points to get_job_status for follow-up, leaving nothing to inference.

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 cover readOnlyHint=true and openWorldHint=true, so 'Read-only' is largely redundant; however 'no API key needed' adds an auth requirement not expressed in the annotations, and the sentence about grouping gives a useful hint at the response shape. It stops short of describing ordering, pagination, or stability of slugs, so it adds value but not richly.

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

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

Three short sentences, front-loaded with what is returned, followed by safety/auth notes and then routing. Every sentence carries distinct information with no padding.

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 no parameters, the description compensates by describing the return shape (grouped slugs with readable names) and the consumer workflow, which is everything an agent needs to call it correctly.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate, and the schema is fully covered at 100%.

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 service category slugs) plus the returned shape (grouped into human services and AI-agent services, each with a readable name). This is distinguishable from siblings like get_platform_info or get_service_details 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 names the trigger ('when you need a valid `category` value') and the four downstream tools it feeds (search_services, search_workers, browse_jobs, create_job), plus an explicit alternative for a different need (get_platform_info for platform overview). Nothing is left to inference.

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 readOnlyHint and openWorldHint; the description goes well beyond by naming the auth requirement (GOHIREHUMANS_AUTH_TOKEN or read-scoped API key) and spelling out per-mode visibility rules (employer/worker/admin for orders; public while accepting applications, then owner/applicants/hired worker/admin for jobs).

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?

Opens with the one-line purpose, then branches cleanly by parameter. Every sentence carries a distinct constraint (auth scope, visibility, ID source, collision warning, precedence) 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?

With no output schema, the description compensates by enumerating the returned fields for each mode (status, amount, worker/employer names, milestone amounts/statuses; job status, budget, application count). Auth, permissions and parameter disambiguation are all covered, so nothing needed 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 coverage is 100%, so baseline is 3, but the description adds real meaning: the provenance of each ID, the fact that the two ID spaces are independent, and the precedence rule when both are supplied. This is exactly the ambiguity a schema alone cannot resolve.

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 ('Check one order or one job post by ID') and immediately distinguishes the two lookup modes. An agent can tell this apart from sibling readers like get_pricing_info or get_service_details without opening a schema.

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

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

Explicitly routes the agent: order_id traverses from hire_worker, job_id from create_job or browse_jobs. It also resolves the ambiguity case ('if both are given, order_id is used') and warns that orders and jobs are numbered separately, so the same integer can refer to both.

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 cover readOnlyHint=true and openWorldHint=false, so safety is partly pre-declared; the description reinforces read-only and adds the genuinely new fact that no API key is needed, which annotations do not express. It also characterizes the returned content as narrative/overview rather than data records. It stops short of noting response size or shape, but clears the higher bar for an annotated tool.

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

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

Three short sentences, front-loaded with the core purpose, then the operational note, then the sibling routing. Every sentence carries information an agent needs and none is redundant.

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

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

For a zero-parameter, no-output-schema onboarding tool, the description supplies purpose, when-to-call, auth expectations, and where to go for adjacent questions — everything needed to call it correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-param tool is 4. The description correctly avoids inventing filtering or formatting options.

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 (get) and resource (platform overview of GoHireHumans) and enumerates the content covered: marketplace description, key facts, kinds of work, and the search-to-approval workflow. An agent can distinguish this from get_pricing_info and get_categories 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 tells the agent when to call it ('Call this first if you are new to GoHireHumans') and routes related questions to named alternatives for fees/payment (get_pricing_info) and category slugs (get_categories). Both the trigger condition and the exclusions are stated.

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 declare readOnlyHint=true, so "Read-only" adds little, though "no API key needed" is useful context. The description goes beyond annotations by disclosing the concrete fee model, the fee comparison scope, and the non-escrow caveat, which materially shapes interpretation of results.

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

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

Front-loads the core fee facts, then comparison scope, then the routing sentence. Dense but each clause carries information; the title duplication and "Read-only; no API key needed" are slightly redundant but not wasteful enough to penalize heavily.

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

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

With no output schema, the description carries the burden of describing returns and does so fully — fee structure, competitor comparison, and payment/approval explanation. Combined with explicit routing, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description makes clear which cost concepts the call covers, which is the only relevant semantic guidance for a no-arg call.

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 (get fees and payment terms) with concrete detail — 1% platform fee, 3% processing charge, free joining/listing — so the agent knows exactly what this returns. It also distinguishes itself from get_platform_info by naming that sibling and its domain.

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

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

Gives explicit when-to-use ("cost questions or before quoting a total to the account owner") and names the alternative (get_platform_info) with its selecting condition ("what the platform is and how it works"). Routing is unambiguous.

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 readOnlyHint and openWorldHint; the description goes well beyond by disclosing the ranking signals (rating, review count, price under $100, 2-day delivery for high/urgent), the keyword-guessing and first-words search mechanics, and the fallback to best-rated listings when nothing matches. It even warns to verify relevance. This is unusually rich behavioral disclosure.

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

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

Front-loads the purpose, then behaviors, then routing in a compact run of sentences with no filler. Slightly dense and repeats a couple of schema facts (urgency boost), keeping it just short of ideal.

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, yet the description covers the return shape (up to `limit` listings) and how results are consumed (service IDs for get_service_details and hire_worker), plus the fallback caveat. Nothing essential 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?

Schema coverage is already 100%, so the baseline is 3, but the description adds ranking semantics not in the schema (e.g., sub-$100 listings score slightly higher, urgency boosting applies to high/urgent only) and frames the output count. Most parameter meaning is still schema-borne, so not a 5.

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

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

States a specific verb and resource ('Rank service listings') plus the input modality ('task described in plain language'). It also implicitly distinguishes itself from search_services by framing the ranking as fuzzy/keyword-based rather than filter-based.

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

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

Explicitly names the condition for use ('when you have a task but no precise search terms') and the alternative for the opposite case ('use search_services for exact keyword and price filters'). Routing is unambiguous.

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 readOnlyHint and openWorldHint; the description adds real behavioral context on top: no API key required, an error is returned for nonexistent/removed listings, and a paused listing is still viewable but not orderable. That paused-vs-orderable distinction is a non-obvious state rule an agent could not infer from annotations.

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

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

Front-loaded with purpose and the returned field list, then prerequisites, then error/state behavior. It is fairly dense in a single paragraph, but nearly every clause (error case, paused state, custom-price caveat) carries distinct operational value.

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

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

With no output schema, the description compensates by enumerating the returned fields, and it covers the failure mode, the paused-listing edge case, and prerequisites. Nothing an agent needs to call this 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 the single service_id parameter is fully documented in the schema, including its origin. The description restates it as a 'numeric ID' but adds no format, bounds, or edge-case detail beyond the schema, so 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 ('Get the full public details of one service listing by its numeric ID') and enumerates exactly what is returned (title, category, price, provider, rating, description, delivery time, listing link). It is clearly distinguishable from siblings like search_services or get_pricing_info.

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

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

Names both sources of IDs ('from search_services or get_recommended') and the precise moment to call it ('just before hire_worker'). It even routes custom-priced listings to a separate agreement step with the provider first, giving explicit when-to-use sequencing.

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/idempotentHint/openWorldHint, but the description goes further than they can: auth requirements (GOHIREHUMANS_AUTH_TOKEN or read+write scopes plus a saved payment method), immediate charge timing, the 1% platform fee and 3% processing charge, that the charge tracks the current price rather than an earlier quote, and that the worker is only paid via release_payment. It correctly explains the idempotency_key retry semantics that back the idempotentHint.

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

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

Purpose, precondition, credentials, cost model, payment timing, irreversibility and retry safety are ordered by the sequence an agent would need them, and every sentence carries a distinct operational fact with no filler.

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

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

There is no output schema and the description compensates by naming the return payload (order ID, amount, status) and the tool that consumes it. With auth, fees, charge timing, payout gating and cancel policy all covered, an agent has everything needed to invoke this 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 description coverage is 100%, so the schema already documents all four parameters including the budget_amount non-cap nuance and the key format. The description restates retry behavior for idempotency_key but adds no syntax or format detail beyond it, so 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?

"Order one service listing: hires its provider and pays for the work" gives a specific verb, resource and the money-moving consequence in one line, and the closing sentence names the resulting artifact (order ID) routed to get_job_status. It does not explicitly say why an agent would pick this over the closest sibling create_job, so it falls short of full sibling differentiation.

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

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

It states a hard precondition ("Call only after the account owner has explicitly approved the listing, price and requirements") and names the sibling to consult first ("re-check get_service_details just before ordering"). It also flags the when-not case: a funded order has no self-serve cancel option, so the agent knows this is irreversible at order time.

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 flag destructive=true and idempotent=false, but the description adds substantial non-structured context: the action is irreversible, it requires GOHIREHUMANS_AUTH_TOKEN while the API key must be unset because API-key auth is rejected, Stripe releases the payout where checkout is configured, and the saved card is charged for a following milestone. This is far beyond what the 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?

Front-loads the core action and its irreversible nature, then layers auth, status, and milestone mechanics. It is dense and multi-clause, but every sentence carries operational value; the auth-requirement sentence is the longest and slightly heavy.

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, non-idempotent payment tool with no output schema, the description covers irreversibility, auth requirements, preconditions, downstream effects on milestones/Stripe, and what to do after the final milestone. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100% and the schema itself explains that rating and milestone_id are ignored/legacy. The description adds no per-parameter detail, but with 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?

States a specific verb pair (approve + release payout) on a specific resource (the worker's submitted work on an order). An agent can distinguish this from siblings like get_job_status or submit_review without opening any schema.

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

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

Gives explicit preconditions (only after the owner has reviewed and approved), required order status ('submitted'), the alternative to check status (get_job_status), and the follow-up tool for rating (submit_review). Routing and when-not-to-call are both covered.

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 carry readOnlyHint and openWorldHint, so the description's 'read-only' restatement is redundant, but 'no API key needed' adds auth context the annotations do not cover. It also discloses ordering (highest rating first), result shape, and the pagination limit ('only the first page of matches is returned'), which are genuine behavioral facts beyond structured fields.

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

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

Four sentences, all front-loaded with the action and scope before the routing advice. The return-field enumeration is slightly long but justified because there is no output schema. Every sentence does work; nothing is 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?

With no output schema, the description compensates by describing return fields, result count, sort order and page-limited behavior. Combined with annotations and a fully documented schema, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds interpretation by mapping the three filter facets and clarifying that price can be a fixed price, hourly rate or custom — which matters for how min_price/max_price are read. It does not document limit or default behavior beyond what the schema already states, so it is a moderate rather than large lift.

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 ('Search individual service listings'), pins the granularity ('one result per listing'), and names the exact facets (keyword, category, price). It is immediately distinguishable from search_workers, get_recommended and get_service_details, which it names explicitly.

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 selection rule ('use this when you know what kind of work you need and want listing IDs to act on') and then routes three sibling tools by condition: search_workers to compare providers, get_recommended for plain-language ranking, get_service_details for a single full listing. Nothing is left to inference.

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 declare readOnlyHint and openWorldHint, but the description adds real context beyond them: no API key is required, results are grouped by provider, ordering follows the highest-rated matching listing, and the displayed rating may come from the provider profile and thus disagree with the sort order. It does not cover pagination behavior when limit is raised, but the disclosure is well above the annotation baseline.

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

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

Front-loads the core definition and the per-provider grouping before moving to filters, return shape, and sibling routing. Dense but every sentence carries information; slightly long as a single unbroken 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?

With no output schema, the description compensates by describing the return shape (provider name, rating, price range, up to three service titles) and the ordering caveat. Combined with the sibling routing and auth note, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the min_rating local-filter nuance. The description only summarizes the filter dimensions ('skills, category, price and minimum rating') without adding syntax or format detail 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 ('Find workers (people or agents offering services)') plus the key aggregation behavior ('one result per provider instead of one per listing'). It explicitly distinguishes itself from siblings search_services and get_recommended, so an agent can route correctly without opening schemas.

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

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

Gives an explicit when-to-use ('Use this to compare providers') and names the two alternatives with the conditions that select them ('search_services when you need listing IDs to hire', 'get_recommended to rank options for a task description'). Nothing is left to inference.

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 cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description goes well beyond them: reviews cannot be edited or deleted via API, one per participant per order, auth scope requirements, and a hidden-until-both-reviewed-or-14-days visibility rule. This is unusually rich operational context and it is consistent with (not contradicting) 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?

A single dense paragraph that front-loads what the tool does before layering conditions. Every clause (auth, completion, once-only, immutability, visibility delay) carries distinct information, though the sentence count could be trimmed slightly.

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

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

For a 6-param mutation with no output schema, the description supplies everything an agent needs: preconditions, auth requirements, cardinality limits, immutability, and post-submission visibility behavior. Nothing material 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%, so all six parameters including the odd 'accepted but not stored' sub-ratings are already documented in the schema. The description restates the 1-5 rating and written review but adds only the visibility timing, so 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 (submit/leave) and resource (a 1-5 star rating and written review) on a clearly bounded target (a completed order, other party). It even clarifies the two directions (employer reviews worker, worker reviews employer), so an agent knows exactly what this produces.

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

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

Gives explicit preconditions: auth token or write-scoped API key, account must be part of the order, order must be completed, and each participant may review once. No sibling tool overlaps this function, so the absence of named alternatives is not a real gap.

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