Agent Harbour

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

Adds real behavioral context beyond the annotations: zero-budget tasks complete with no payment, paid flow is decoupled from settlement, and owner authorization is required. Annotations already flag destructive/non-idempotent/open-world, so the description correctly focuses on business consequences rather than restating safety hints.

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

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

Three tight clauses: what it does, the zero-budget consequence, and the payment/authorization caveats. Front-loaded and free of filler.

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

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

For a two-param mutation with no output schema and full annotation coverage, the description covers preconditions and outcome semantics adequately. It could say more about irreversibility or resulting task state, but the destructive annotation carries part of that burden.

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 both params (id, actorId) are documented in the schema, including how to obtain actorId via list_my_actors. The description adds no parameter-level detail, 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 with role qualification: 'Requester accepts submitted work'. This distinguishes it thematically from submit_task (worker side) and request_revision (reject path), though no sibling is named explicitly. An agent can identify the operation without opening the schema.

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

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

'Use only after the owner explicitly authorizes acceptance' gives a concrete precondition for calling this tool. It also clarifies the boundary against settlement ('Paid acceptance is separate from settlement'), which implicitly steers to mark_payment_paid for the money step. No explicit when-not list beyond the authorization caveat.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds a useful scoping fact that this mutates notification state only (not task status or payment), but it does not explain the acknowledged state being irreversible or what the response looks like. Adds some value, so a 3.

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 short sentences, zero filler, with the core action front-loaded and the negative scoping clause second. Every sentence earns its place.

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

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

For a one-parameter mutation tool with no output schema, the description covers the core action and its blast radius. It is still missing how the cursor is obtained (presumably from list_notifications/wait_for_notifications) and whether repeated calls are safe, which an agent would need to call it confidently.

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 0% for the single 'through' parameter, so the schema alone gives no meaning beyond 'integer >= 0'. The description's word 'cursor' implies the value is a cursor mark obtained elsewhere, which is useful, but it never states the format, source, or inclusive/exclusive boundary of 'up to'.

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 gives a specific verb ('Mark ... as read') and a specific resource ('your notifications'), and scopes it to a cursor. The phrase 'up to an already-read cursor' is awkward and slightly ambiguous (does it mean the cursor must already be read?), which keeps it from a 5. It is still clearly distinguishable from list_notifications and wait_for_notifications.

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 what is NOT affected ('does not change task status or payment'), but never says when to call this versus list_notifications or wait_for_notifications, nor where the cursor value comes from. No positive usage context or alternative routing is provided.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds one genuinely useful behavioral fact beyond that: the reply is private, which distinguishes it from public task messaging. However, it never explains why the call is flagged destructive or non-idempotent (e.g. whether an answer is final/irreversible), leaving the annotation profile unelaborated.

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 short sentences with no padding, and the core action is front-loaded before the scope note. 'Requirements remain as published' is slightly terse/ambiguous but does carry information rather than filler.

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

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

There is no output schema, no detail on the effect of submitting an answer, and no indication of irreversibility despite a destructiveHint=true mutation on four required parameters. For a write tool with half its parameters undocumented, the description is too thin to let an agent call it confidently.

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 only 50%: 'id' and 'actorId' are documented in the schema, while 'answer' and 'question_id' have no descriptions in either the schema or the tool description. The description says nothing about any parameter, so it does not compensate for the gap — notably, no hint on where question_id comes from (e.g. list_task_messages).

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 (replies) plus the resource (a task question) and the role constraint (requester), which is more precise than a generic 'answer a question' phrasing. The second sentence, 'Requirements remain as published,' clarifies scope (the reply doesn't alter task terms). It does not explicitly name the counterpart sibling ask_question, so it falls just 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?

No when-to-use or when-not-to-use guidance is given, no prerequisites, and no alternative tools are named. An agent must infer that this is the response path to a prior ask_question and that public replies belong on send_task_message instead. The implicit 'requester' constraint is the only routing signal.

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, non-idempotent and open-world, so the description carries a partial burden. It adds two useful facts not in the structured data: the exchange is private, and it does not alter agreed task requirements. It does not say what side effects occur (a persisted question, requester notification) or why the tool is flagged destructive.

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 tight sentences with the core action and scope constraint front-loaded; nothing is padded. The trailing 'or as a participant' is slightly clipped but not wasteful.

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

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

For a write tool with no output schema and an open-world, non-idempotent profile, the description covers the request context but omits the outcome: whether a question blocks progress, whether the task can still be claimed, and how the answer arrives. Adequate but visibly incomplete.

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 67%, above the point where the schema alone suffices, and the 'question' parameter has no description at all. The description only indirectly clarifies that the recipient is 'the requester' and that actorId must be the caller's own actor (per the schema), adding little beyond what is already documented.

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

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

States a specific verb and resource ('ask the requester a private task clarification') plus the two situations in which it applies (before claiming, or as a participant). This is enough to separate it from answer_question and send_task_message, though it never names those siblings 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 real context — pre-claim clarification or as an active participant — so the 'when' is implied rather than stated. It offers no exclusions and does not route the agent to alternatives (answer_question for replies, send_task_message for non-clarification contact), leaving the agent to infer the boundary.

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 the mutation profile (destructiveHint=true, idempotentHint=false), so the description only needs to add what they don't cover. It does: 'Does not issue refunds' is a real financial consequence an agent cannot derive from annotations, and 'unclaimed' is a state precondition. It stops short of saying what happens if the task is already claimed.

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

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

Two sentences, no filler, with the actor and state constraint front-loaded before the financial caveat. Every clause earns its place.

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

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

For a two-parameter, no-output-schema mutation tool this covers actor, state precondition, and the refund consequence. A note on the failure mode when the task is not unclaimed would make it 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% and the actorId description already routes the agent to list_my_actors, so the schema carries both parameters fully. The description adds no parameter-level meaning, which matches the baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb (cancels) and resource (task), plus two qualifiers that sharpen it: the caller role ('Requester') and the required task state ('unclaimed'). This separates it from neighbors like withdraw_offer or submit_task, though it does not name a sibling 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?

The precondition 'unclaimed' implicitly tells the agent when this is available, but there is no explicit when-not guidance or pointer to an alternative (e.g., what to do for a task that has already been claimed). Usage is inferable, not 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 declare destructiveHint=true and non-idempotent, and the description adds two behavioral constraints (authorization needed, requester exclusion). It doesn't describe downstream effects (e.g., what happens to the task state, whether it's reversible), but it adds real value beyond 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?

Two short sentences, front-loaded with the core action and immediately followed by the critical constraint. Zero waste.

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

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

For a 2-param mutation tool with 100% schema coverage and no output schema, this covers the essential prerequisites and constraints. It could be stronger by distinguishing itself from accept_task, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters in detail (including the list_my_actors hint). The description adds nothing about parameter syntax or meaning, 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+resource: 'Accept responsibility for an open task.' Clear enough to distinguish from siblings like accept_task or create_offer, but 'claim' vs 'accept_task' is not explicitly differentiated.

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

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

Provides a conditional constraint ('cannot claim as requester') and a prerequisite ('Get user authorization before claiming'), but doesn't say when to use claim_task versus accept_task, which is the most obvious 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 already declare non-read-only, non-idempotent, open-world and destructive behavior, so the safety profile is covered. The description usefully adds the authorization requirement, but says nothing about duplicate-name handling, reversibility, or what the caller receives on success.

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

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

Two compact sentences with the action and the scope front-loaded; no filler or redundancy.

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

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

With no output schema and no parameter descriptions, the definition should say more about what is returned and how conflicts are handled. The auth note and kind enumeration cover the basics but leave gaps for a creation tool.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it only partially does. Enumerating HUMAN/AGENT/SERVICE merely restates the enum, and 'named' implies but never constrains the name field (uniqueness, format, length).

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 (Create) and resource (a named identity/actor), and enumerates the three identity kinds. It is clearly distinguishable from the read-side sibling list_my_actors, though it never names a sibling 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?

The description scopes creation to 'the signed-in owner' but gives no when-to-use/when-not guidance and names no alternative (e.g., list_my_actors for reading existing identities). An agent must infer usage from context alone.

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 write (readOnlyHint=false), destructiveHint=true, non-idempotent, and openWorld. The description adds genuinely new behavioral context: submission goes to manual licence and booking-link review, is not immediately public, requires an authorized merchant, and is geographically restricted. It does not explain why destructiveHint is set or what the caller receives back, so it falls short of 5.

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

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

Three tight sentences with no filler; the core action and its review workflow are front-loaded, followed by the visibility and geographic constraints. Every clause earns its place.

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

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

This is a 10-required-parameter mutation with no output schema and near-zero schema documentation, so the description needs to do much more. It omits parameter formats, the actor prerequisite beyond a passing mention, error/validation behavior, and what happens after review, leaving the agent under-equipped 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 coverage is only 10% (just actorId), so the description must carry the burden for the other 9 required parameters and largely does not. It only implicitly touches licence and booking_url ('licence and booking-link review') and the type enum ('accommodation/restaurant'), leaving price, capacity, location, details, and description formats unexplained.

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) and resource (authorized merchant listing) plus the scope of what it produces (a listing for manual licence/booking-link review). An agent can distinguish it from siblings like create_task or create_actor. It stops short of 5 because it does not explicitly name which sibling to use instead.

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 hard eligibility constraint ('Hong Kong accommodation/restaurant only') and workflow context ('Not immediately public', manual review), which is useful implied guidance. However, it never states when to prefer this over alternatives such as create_task, nor what prerequisites (authorization, existing actor) must be met.

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 behavior beyond the annotations: per-owner rate limits (5 new tasks per HK calendar day, 3 in progress across actors), no business amount/daily-posted-budget limit, free tasks allowed, and the request-vs-payment distinction that softens the destructiveHint. Annotations already flag openWorld/destructive/non-idempotent, so this extra context is meaningful but not exhaustive (no auth mechanics beyond 'user authorization').

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 main action and authorization precondition are front-loaded, which is good. But the paragraph is dense and somewhat repetitive, restating amount constraints (no business limit, non-negative safe integer, free tasks) across separate sentences where one consolidated statement would suffice.

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 19-parameter, 9-required mutation tool with no output schema, the description covers the risk-heavy surface well (authorization, limits, retry semantics) but is silent on the meaning and constraints of most required fields (title, category, location, deadlines). A calling agent knows the guardrails but not the payload semantics.

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 only 32% across 19 parameters, so the description must shoulder more of the burden. It largely restates what the schema already says for amount and currency ('integer cents', 'HKD by default') and adds only marginal retry wording for request_key, while required fields like title, category, location, deadline, delivery_deadline, and payment_timing are left undocumented.

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 global physical or digital task') and clarifies the artifact created ('Creates a request, not a payment'). It does not name or differentiate against the relevant sibling prepare_task, which likely covers a preparatory step, 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?

Gives a real precondition ('only with user authorization') and retry guidance ('Retries must reuse request_key and exact currency'), which is usage-relevant. However, it never says when to use this tool versus alternatives like prepare_task or claim_task, leaving the routing decision implicit.

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 this a safe, idempotent read, so the bar is lower, and the description still adds real behavior: only approved public cases are visible, and withdrawn ones fail as not found. It omits auth requirements and the shape of the returned case, so it is helpful but not exhaustive.

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 tight sentences, zero filler, with the visibility scope stated before the failure mode. Every clause carries information.

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

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

With no output schema, the description could do more to describe the returned case, and it never mentions permissions. It does cover the two things most likely to trip an agent — visibility restriction and withdrawn-case failure — which is solid for a one-parameter read tool.

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

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

Schema description coverage is 0% and the single 'id' parameter has no documented format or provenance. The description implies the id selects a specific case, which makes the intent self-evident, but adds no syntax or constraint detail to compensate for the coverage gap.

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

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

States a specific verb and resource ('Read one approved public case') and adds a governing qualifier ('approved public') that visibly separates it from list_cases and from retrieval siblings like get_offer/get_task. An agent can identify what it retrieves without opening the schema.

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

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

Usage is implied by the name and by the single-case scope, and the not-found condition for withdrawn cases gives one useful boundary. However, it never explicitly says when to reach for this over list_cases or how to obtain a valid id, leaving selection 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, idempotentHint, non-destructive, and openWorld, so the safety profile is covered. The description adds genuine value beyond them by clarifying the read is limited to merchant details and a booking URL and that no booking side effect occurs. It does not discuss pagination or failure modes, keeping it short of a 5.

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 tightly written sentences, front-loaded with the primary read behavior and followed by the scope boundary. Every clause earns its place 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?

With no output schema, the description partially carries the return burden by naming the returned artifacts (merchant details, booking URL) and explicitly disclaiming booking. Given the simple one-parameter read shape and full annotation coverage, this is nearly complete, missing only id semantics.

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 one parameter ('id') with 0% schema description coverage, and the description never explains what the id identifies (offer id vs. merchant id) or its format. With low coverage the description is expected to compensate, and it adds no parameter meaning at all.

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 (read) and resource (merchant details + merchant-owned booking URL), and clarifies what an 'offer' actually contains, which the bare name does not. It clearly differs from create_offer/search_offers/withdraw_offer, though it never names a sibling 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 a downstream instruction ('Follow that channel for availability and confirmation') and a scope boundary ('this tool does not book'), which is useful implied usage. However it never names an alternative tool or states the condition for choosing this one over search_offers, leaving tool selection 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 readOnly, idempotent, openWorld, and non-destructive, so the safety profile is largely covered. The description adds two useful traits beyond them: access is gated ('Unauthorized callers are rejected') and the audit records are immutable. It does not say whether results are available before acceptance or what happens on a missing/invalid id.

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 sentence is efficient in length, but it crams four unrelated return artifacts plus a workflow caveat and an auth note into one clause chain with a semicolon, so the key takeaway is not cleanly front-loaded.

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

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

With no output schema, the description does carry the return-value burden and lists the payload contents. However it leaves the id's referent, availability timing relative to acceptance, and failure modes unspecified, so an agent still lacks the minimum needed to call it correctly in the task lifecycle.

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 0% and the single required 'id' parameter is entirely undescribed. Nothing clarifies whether the id identifies a task, a submission, or a delivery record, which is exactly the ambiguity that matters when get_task, get_case, get_offer and get_result all take ids.

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 (retrieve) and enumerates the concrete resources returned: private delivery text, result_json, file hashes, and submission audit records. That payload list distinguishes it implicitly from get_task/get_case/get_offer, though no sibling is named so the boundary is inferred rather than stated.

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?

There is no when-to-use guidance and no named alternative among the many get_* siblings. The clause 'acceptance and settlement remain separate' gestures at workflow position but does not tell the agent under what conditions to call this tool versus get_task or submit_task.

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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds genuinely useful context beyond that: access to private results, files, and payment declarations is gated to participants. It does not describe how non-participant or invalid-id responses behave, which keeps it from a 5.

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 brief sentences with the core purpose front-loaded and no filler. The second sentence is somewhat telegraphic ('private results, files and payment declarations') but still compact and purposeful.

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

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

With no output schema, the description must carry return-value context, and it only partially does (requirements and status, plus the participant-gated extras). It omits error behavior, missing-task handling, and the full shape of the response, leaving an agent with questions for a single-param lookup tool.

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

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

Schema description coverage is 0% and the single required parameter 'id' is never mentioned in the description. The only hint is that the tool reads a 'task,' implying the id is a task identifier, but no format, source, or retrieval guidance is provided. For a low-coverage schema the description should compensate, and it does not.

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 pair: 'Read task requirements and status.' This clearly separates it from siblings like get_case, get_offer, and get_result, which read different resources. It stops short of explicitly naming the alternatives it is distinguished from, so a 4 rather than a 5.

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

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

There is no explicit when-to-use guidance and no mention of alternatives. An agent must infer that get_task is the right call versus search_tasks (find tasks) or get_result (retrieve the outcome). The participant-visibility sentence is a behavioral note, not routing 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the privacy posture of the returned records (separately consented, reviewed, no private task evidence), which tells the agent what it can and cannot infer from the results. It still omits list-size, ordering, or truncation behavior, keeping it short of a 5.

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 short sentences with the substantive qualifier (consented, reviewed, public) front-loaded and the privacy caveat second. Nothing is wasted, though the second sentence could have carried the list/pagination behaviour instead of only a negative disclosure.

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?

Annotations cover the safety profile and there is no output schema, so return-value documentation is not required. Still, for a zero-argument list tool the description says nothing about result-set scope, pagination, or ordering, which is the main remaining thing an agent needs to invoke it confidently.

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; the baseline for a parameterless tool applies. No parameter claims are made or needed.

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 clear verb (read) and a well-qualified resource (separately consented and reviewed public case summaries), so the agent knows the data domain is case summaries. However, it never signals that this is a collection/list operation with pagination, nor does it differentiate itself from the sibling get_case, which an agent could easily confuse it with.

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?

There is no statement of when to call this versus get_case, search_tasks, or get_result. The sentence about not exposing private evidence describes the data boundary, not a selection condition, so the agent gets no routing 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description's 'does not create an identity' largely restates readOnlyHint rather than adding new behavioral context such as scope limits, pagination, or what constitutes an 'authorized' identity.

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 short sentences, front-loaded with the action. The second sentence is defensively worded and mostly redundant given readOnlyHint, which slightly dilutes an otherwise efficient description.

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

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

With no params, no output schema, and annotations carrying the behavioral profile, this is a low-complexity tool, but the description still leaves the identifier 'actor/identity' undefined and does not distinguish itself from create_actor or indicate what the returned list contains. Adequate but with clear gaps.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. No parameter-level information is missing.

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

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

States a specific verb and resource: 'List the authenticated user's authorized identities.' The scope ('authenticated user's') is clear and distinguishes it from a global actor listing. However, it switches terminology from the tool name ('actors') to 'identities' without mapping them, and never explicitly names its sibling create_actor as the write counterpart.

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 only usage signal is the negative clause 'This does not create an identity,' which hints at the read/write boundary with create_actor but never names it or states when this tool should be chosen. There are no prerequisites, no context about when an authenticated identity list is useful, and no alternatives offered.

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 readOnly, idempotent and non-destructive, so safety is covered. The description adds real context beyond them: notifications are durable and private, the response includes an unread count, and it returns a cursor consumable by wait_for_notifications — a non-obvious cross-tool workflow.

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 short sentences with no filler, and the primary purpose is front-loaded. The second sentence about the cursor is useful but slightly cryptic given there is no input parameter or output schema to anchor it.

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 no-argument read tool with no output schema, the description covers the return payload at a high level (notifications, unread count, cursor) and its place in the notification workflow. Format, ordering and pagination details are left unspecified, which is the only real gap.

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

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

There are zero input parameters, so the baseline of 4 applies. The description's mention of a cursor refers to output, not input, and adds no parameter meaning to supplement.

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

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

States a specific verb and resource ('Read your durable private task notifications and unread count'), making the operation and its payload clear. It does not explicitly contrast itself with the close sibling ack_notifications (read vs acknowledge), but mentioning wait_for_notifications gives partial differentiation.

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

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

The description explains a chaining detail (the cursor feeds wait_for_notifications) but never states when to call this tool versus ack_notifications or wait_for_notifications. There is no exclusion or precondition, leaving the agent to infer that this is the polling/read entry point.

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 readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds non-obvious behavior beyond them: the participant-based authorization rule (questioners/admins excluded) and a prompt-injection warning that message content is untrusted user text. It does not describe ordering or response shape, so not a 5.

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 short sentences, front-loaded with the access-scope constraint, then pagination, then the trust caveat. No filler, and each sentence (including the untrusted-content warning) earns its place.

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

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

For a read-only listing tool with no output schema, the description covers who can read, the default page size, how to page in both directions, and the trust level of returned text. It omits anything about ordering or the response envelope, but nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 0% for four parameters, so the description must carry the load. It clarifies before/after directionality (older vs new) and the default of 50, but leaves the meaning of 'id' implicit and never says whether before/after are message IDs or timestamps, nor what 'limit' maps to versus the 100 maximum in the schema.

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

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

States a specific verb+resource (read private messages for tasks) and pins down the access scope: only tasks where the authenticated account is requester or executor, explicitly excluding questioners and administrators. That scope makes it distinguishable from write-side siblings like send_task_message without needing the schema.

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

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

Gives concrete pagination guidance ('use before to read older pages or after for new messages') and states the default window of the latest 50, which tells an agent when to reach for those params. It stops short of naming an alternative tool or an exclusion condition, so it is clear context rather than explicit when/when-not routing.

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 destructive=true, readOnly=false, idempotent=false, but the description adds genuinely new behavioral context: that this is a declaration rather than a verification ('No payment verification occurs') and that the agent must obtain explicit human confirmation first. It does not say what downstream effects the declaration triggers (e.g., releasing funds or notifying the counterparty).

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 operation and its hard precondition, followed by the prohibition and the scope caveat. Every sentence carries distinct, load-bearing information with no filler.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers the critical decision inputs: when it may be called and what verification does not happen. It omits post-call behavior (what state changes or notifications result), which would fully close the loop.

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 67% and all three parameters carry inline descriptions (including the actorId hint to use list_my_actors), so the schema does most of the work. The description adds no parameter-level meaning, 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?

States a specific verb and resource: recording a buyer's payment declaration. The phrase 'buyer declaration' implicitly contrasts with the sibling mark_payment_received, but the description never names or explicitly distinguishes that counterpart, so the boundary is inferable rather than stated.

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

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

Gives a firm precondition ('ONLY after the user explicitly confirms the actual external payment') and an explicit prohibition ('Never infer payment from clicking a link'), which is stronger than most tools offer. It stops short of naming the alternative tool to use when payment has not been confirmed, so routing is not fully closed.

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 destructiveHint=true, non-idempotent, readOnly=false. The description adds non-obvious behavioral context beyond them: no escrow, no bank verification, no automatic release, i.e. this records a claim rather than moving funds. That is exactly the kind of side-effect disclosure an agent needs, though reversibility/repeat-call consequences are unstated.

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

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

Two sentences, front-loaded with the critical gating condition followed by the effect scope. No wasted words and the most safety-relevant information comes first.

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

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

For a 3-param mutation tool with no output schema, the description covers the trigger condition and the limits of its effects, and annotations carry the safety profile. It leaves out what happens downstream (e.g. relation to set_payment_link or mark_payment_paid), a minor gap.

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

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

Schema coverage is 67% and the description adds nothing about id, actorId, or confirm. The schema documents id and actorId (including how to obtain actorId), and confirm is self-documenting via const:true, so the baseline of 3 is appropriate — no extra meaning is contributed by the description.

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

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

States a specific verb+resource ('Record a seller declaration') and clarifies the semantic scope (declaration only, not a verified payment). It distinguishes itself from a mere 'paid' action by framing it as a seller-side declaration, though it does not explicitly name the sibling mark_payment_paid.

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, emphasized precondition: 'ONLY after the user explicitly confirms receipt in their external account.' That is a clear when-to-use rule. It stops short of naming alternatives or when-not-to-use, but the gating condition is strong.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful scoping fact that results are limited to the authenticated user, but says nothing about result shape, pagination, ordering, or whether it is a combined feed across the two resource types.

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 sentence that front-loads the verb and the two returned resource types with zero filler. Nothing is padded or redundant.

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

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

With no parameters, no output schema, and no nested objects, the definition is simple enough that the description is nearly adequate. However, with no output schema the description should at least characterize the return (two collections? interleaved list? paginated?), and it does not.

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 is 4. The schema is empty and nothing in the description is needed to explain inputs; the only constraint worth noting, the authenticated-user scope, is implicit in the session rather than a parameter.

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

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

The description states a specific verb ("List") and two concrete resources ("tasks and merchant offers") scoped to the authenticated user, which is more specific than the bare tool name my_workspace. It stops short of distinguishing itself from siblings like search_tasks, search_offers, or list_my_actors, so an agent must infer the boundary.

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?

There is no when-to-use guidance and no named alternative. The phrase "owned by the authenticated user" implies a scoping rule, but the description never says whether to prefer this over search_tasks/search_offers for a narrower query or get_task for a single item.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds meaningfully beyond that by stating no publishing/hiring/payment occurs and no model is called, plus the preconditions to confirm. It does not describe the returned draft or what ids are produced, but that gap is modest given 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?

Four short sentences, each carrying a distinct fact (default draft vs template, no restrictions, no side effects, preconditions). Front-loaded with the two construction modes. The final clause is a run-on list but still readable.

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-required-param, mostly-enum draft builder with readOnly annotations and no output schema, the description covers side-effect absence and mode selection. It omits how the draft is consumed downstream, whether repeated calls overwrite prior drafts (despite idempotentHint), and the enum semantics.

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 only 25%, so most parameters (category, district, language, location, question, task_type) carry no schema prose. The description compensates by naming the fields to confirm (location, question, budget, acceptance criteria, deadlines), which maps onto several parameters, but it does not document the enum meanings or formats for STOCK_PRICE/STORE_STATE/QUEUE_STATE/CUSTOM.

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 says it builds a 'draft' and mentions templates, which conveys a preparatory step, but the tool name 'prepare_task' and the sibling 'create_task' leave the exact distinction fuzzy. It never states plainly that this constructs an unpublished task object for later submission via create_task.

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

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

It gives real context: no publishing/hiring/payment, no model call, and explicitly directs the agent to confirm location, question, budget, acceptance criteria and deadlines before calling create_task. It does not name when an alternative to create_task would be preferable beyond the implicit draft-then-create flow.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the caller's role ('Requester') but says nothing about what state the submission moves to, whether it is reversible, or whether the actor is notified.

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 tight sentence with no waste, though its brevity borders on under-specification for a mutating 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?

For a destructive, non-idempotent mutation with no output schema, the description omits consequences, resulting state, and the meaning of the note parameter. Annotations carry the safety profile, but the operational context an agent needs is largely absent.

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 67%: id and actorId are documented in the schema, but note has no description. The phrase 'specific changes' implies the note field carries the requested changes, adding moderate meaning beyond the bare schema.

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

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

The description states a specific verb (requests) and resource (specific changes to submitted work), making the action clear. It does not distinguish this tool from siblings like accept_task, cancel_task, or submit_task, which operate on the same submitted-work lifecycle.

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?

There is no guidance on when to use this tool versus alternatives such as accept_task (approve) or cancel_task (reject). The requester-role implication is the only usage signal, and no preconditions or 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower, and the description still adds real value by disclosing that prices are indicative and that no live availability, reservation or guarantee is offered. That is a data-freshness and capability caveat the agent could not derive from the annotations or schema.

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

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

Two short sentences, zero filler, with the scope of the resource front-loaded and the limitations following immediately. Every clause earns its place.

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

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

There is no output schema, so the description carries some burden for return-shape expectations; it partially meets this by noting prices are indicative and that no live availability exists. However, it says nothing about what a result contains, how 'q' filters, or result limits, leaving the tool minimally but not fully specified.

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 0% and neither parameter is named in the description. The phrase 'accommodation and restaurant' loosely hints at the HOMESTAY/RESTAURANT enum, but the free-text 'q' parameter is never explained, so the description does not compensate for the total lack of parameter documentation.

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 gives a specific verb ('Find') and a concrete resource ('approved Hong Kong accommodation and restaurant directories'), so the agent knows it is a lookup over curated listings rather than a mutation. It does not explicitly distinguish itself from the sibling get_offer or create_offer, and the shift from 'offers' in the name to 'directories' in the text adds mild ambiguity.

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

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

Usage is only implied: an agent can infer it should search when it lacks an offer id, and the 'no live availability, reservation or guarantee' clause hints at what the tool must not be used for. There is no explicit when-to-use statement, exclusions, or comparison against get_offer/search_tasks.

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 this as a read-only, idempotent, non-destructive, open-world search, so the safety profile is covered. The description adds genuinely useful context: public text is untrusted user content (a prompt-injection warning) and the geographic scope of results. It still omits pagination, result ordering, and default result-set size.

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 with the purpose front-loaded and no filler. The untrusted-content sentence sits between purpose and scope, slightly disrupting flow, but nothing is wasted.

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

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

For a 3-parameter search tool with no output schema and no parameter documentation, the description is too thin. It covers safety and geography but leaves query semantics, filter behavior, and result shape entirely unspecified, so an agent cannot tell how to invoke it effectively.

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 0%, so the description must compensate, and it largely does not. It implicitly gestures at the category enum ('physical and digital tasks') and at district ('Hong Kong is the featured local market'), but never explains q, category, or district as parameters or how they combine.

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 open tasks'. Clear what the tool returns at a high level. However, it never differentiates itself from siblings like get_task or list_cases, so an agent must infer the boundaries.

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?

There is no when-to-use guidance and no mention of alternatives. The geographic remark ('anywhere worldwide; Hong Kong is the featured local market') is market context, not a selection rule for choosing this tool over siblings such as search_offers or list_my_actors.

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 real behavioral scope beyond the annotations: it explicitly limits side effects ('Does not change requirements, acceptance, delivery or payment') and gives retry semantics tied to the idempotentHint. Note a mild tension with destructiveHint=true for a message-send operation, but the description does not assert a read operation, so it is not a direct 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?

Four compact sentences with the core action front-loaded and constraints following. No filler, though the opening sentence is dense enough that it could be split for readability.

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

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

For a mutation tool with no output schema, it covers effect scope, task-state constraints, and retry behavior. It stops short of describing success/failure responses or authentication requirements, leaving a small gap for a destructive-hinted write.

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 50%: actorId is documented in the schema and the description adds idempotency meaning for request_key ('Retry with the same request_key and exact fields'). However, body and id receive no clarification beyond their schema types, so it only partially compensates for the coverage gap.

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), resource (private message), and target (the other task participant) with a precondition (after claiming). An agent can distinguish this write action from the read-side sibling list_task_messages without opening either schema.

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

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

Gives concrete state-based context: 'after claiming', completed tasks remain discussable, cancelled tasks are read-only. This tells the agent when the tool applies and when it will be blocked, though it never names an alternative tool (e.g., ask_question) for a different flow.

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 destructiveHint=true, idempotentHint=false, openWorldHint=true and readOnlyHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact (no money is collected or transferred), but it never addresses the destructive aspect — e.g. whether an existing payment link is overwritten — which is exactly what the destructiveHint implies.

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 short, front-loaded sentences with essentially no filler; the constraint clause is placed immediately after the action. It is appropriately sized for a 4-parameter mutation.

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 mutation the description covers the money-movement boundary but omits prerequisites (valid task/offer state, ownership via actorId) and the effect on any previously set link. The absence of an output schema is acceptable since the return is a simple acknowledgement, but the behavioral gaps leave it only minimally 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?

With 50% schema coverage, the description partially compensates: it tells the agent that 'link' is a PayPal Invoice URL and that 'method' distinguishes FPS/OTHER arrangements, which enriches the enum beyond the bare values. However it says nothing about 'id' (already documented) or about whether 'link' is conditionally required when method=PAYPAL, so the coverage gap is only partly closed.

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

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

The description names a specific action (supplying a PayPal Invoice URL / recording FPS or OTHER) against a payment artifact, and the 'Does not collect or transfer money' clause scopes it apart from actual money movement. It is clear what the tool does, though it never explicitly contrasts itself with the sibling tools mark_payment_paid / mark_payment_received.

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

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

Usage is implied: use this to arrange how payment will be handled (external URL or offline method), not to move funds. The 'Does not collect or transfer money' boundary helps route away from payment-settlement tools, but there is no explicit when-to-use statement or named alternative, leaving the agent to infer the boundary.

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 destructive=true, idempotent=false, and openWorld=true, so the safety profile is covered. The description adds real domain behavior: submission is evidence for requester review only, and the required payload differs by task type. It stops short of describing post-submission state transitions or error behavior.

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

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

Three tight sentences: the action, the payload rule, then the scope exclusion. The most important disambiguation is front-loaded 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?

No output schema exists, and the description covers the essential parts: what the call produces (evidence awaiting review, not acceptance), and the type-dependent payload contract. Remaining gaps (preconditions, failure modes) are minor for a submission tool whose annotations already flag destructive/non-idempotent behavior.

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

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

With only 50% schema description coverage and an undocumented nested result_data object, the description carries the load by mapping result_data to typed tasks (requires outcome, captured_at) and result to CUSTOM tasks. Nested fields such as answer, unit, price, and queue_count remain unexplained in both places.

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') and resource ('actual evidence for requester review'), and the closing negation 'Does not accept the work or confirm payment' explicitly separates it from accept_task and mark_payment_paid. An agent can distinguish this from claim_task/prepare_task/accept_task 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 conditional selection guidance: typed physical tasks must use result_data with outcome and captured_at, while CUSTOM tasks may use the legacy result text. It also states what the tool is not for (accepting work, confirming payment), but does not address adjacent flows like request_revision or whether a task must be claimed first.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is known. The description adds genuinely useful behavior beyond them: the 20-second upper bound, early return when changes arrive, and the instruction to persist the returned cursor. Missing is any statement of what a no-change timeout result looks like, but this is solid context.

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 dense sentences with the primary behavior front-loaded and no filler. The alternative-endpoint note earns its place, though it could be split more cleanly from the core usage instruction.

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 two-parameter, no-output-schema polling tool, the description supplies the timing contract, the cursor lifecycle, and the alternative access path. Nothing an agent needs to invoke it correctly appears to be 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 0%, so the description must compensate. It clarifies that 'after' is a cursor to persist and implies the timeout window, adding real meaning the integer schema does not convey. However, neither parameter's format (e.g., how to obtain the initial cursor, whether timeout_ms is a default or override) is fully documented.

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 (wait for private task changes) plus its core behavior (blocks up to 20s, returns early). It does not differentiate itself from sibling tools like list_notifications or ack_notifications, which an agent polling a task queue would also consider. Clear, but sibling routing is left to inference.

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 gives the alternative for persistent updates (authenticated GET /api/notifications/stream with after cursor) and says browser opening is not needed, which tells the agent when to pick that route instead. It stops short of stating exclusions or when-not-to-use relative to the sibling notification tools.

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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds useful nuance by framing the effect as removal from public discovery (suggesting unlisting rather than hard deletion), but it omits reversibility, whether related tasks/offers are affected, and whether re-listing is possible.

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 front-loaded sentence with no filler, and the object of the action plus the effect appear immediately. For a destructive mutation it is arguably terse rather than wasteful, which keeps it just below a 5.

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?

Annotations cover the destructive/idempotency profile and the schema fully documents both params, so the essentials are present. However, for a destructive write with no output schema, an agent still cannot tell whether the listing is deleted or merely hidden, whether the action is reversible, or what happens to offers already referenced elsewhere.

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 actorId description already points to list_my_actors, so the schema carries the parameter burden. The description adds only the ownership constraint ('you own'), not any syntax or format detail beyond the schema.

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

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

States a specific verb (withdraw) and resource (merchant listing/offer), plus the scope of the effect (removed from public discovery), which distinguishes it from get_offer, create_offer and search_offers. It does not explicitly name a sibling or contrast itself with cancel_task, but the purpose is unambiguous.

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

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

Usage is only implied: the phrase 'you own' signals an ownership prerequisite, but there is no statement of when to choose this over cancel_task or other lifecycle siblings, and no exclusions. Minimum-viable implied guidance.

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