Mundane

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

Beyond the annotations, the description discloses allowed extensions, file size cap, per-task file count, timing restrictions, and filename override behavior. This is meaningful behavioral context that annotations do not provide, and there is no contradiction with the annotation hints.

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

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

The description is front-loaded with purpose and examples, then packs constraints into compact, dense sentences. Every clause adds useful information, and there is no filler or repetition of annotation data.

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

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

The description covers operational constraints thoroughly and gives enough detail for an agent to invoke the tool correctly. It omits explicit return/error behavior and auth prerequisites, but the input semantics and lifecycle rules are well specified, so the remaining gap is minor.

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 each parameter already has a description, so the baseline is 3. The description adds value by explaining that filename overrides the worker-facing name and by attaching file-level constraints (extensions, size caps) that make file_path's role clearer.

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 ('Attach a working file from local disk to an owned task'), gives concrete examples (STL/STEP, PDF, image), and clearly scopes the resource. It is easily distinguishable from siblings like list_task_attachments and update_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?

The description gives clear context for when attaching is allowed and its lifecycle constraints (uploads allowed until proof is submitted, deletion before acceptance). It does not explicitly name alternative tools or when not to use this one, but the context is strong enough for an agent to infer appropriate use.

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

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

The description adds meaningful behavior beyond the readOnlyHint annotations: it defines exactly when `changed` is true, what is monitored, what a false result means, and caps the wait at 55 seconds. This gives the agent a clear model of the tool's behavior without relying only on annotations.

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

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

The description is compact, front-loaded with the core wait-and-return behavior, and every sentence earns its place: wait semantics, changed-flag meaning, and usage guidance versus get_task_status.

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

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

The description is complete enough for invoking the tool correctly: it covers timing, return payload, changed semantics, and the polling alternative. A minor gap is that 'owned task' is not further defined, and there is no output schema, but the annotations plus the description cover the key invocation context.

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 baseline is 3 because the schema already documents task_id and timeout_seconds. The description reinforces the timeout cap and the alternative list_task_events, but does not add substantial per-parameter semantics beyond the schema.

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

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

The description names a specific verb (wait) and resource (owned task), explains the timeout cap, and states the returned payload and `changed` flag semantics. It also distinguishes itself from the polling sibling get_task_status, so an agent can distinguish them 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?

It explicitly says to use this tool instead of repeatedly calling get_task_status while waiting for a worker, and points to list_task_events for longer gaps. The when-to-use guidance is direct and actionable.

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

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

The description adds behavioral detail beyond the annotations' destructiveHint: it cancels the pending offer, states that an accepted task may incur a fee, and specifies the return representation as integer fee_minor units. It does not contradict the readOnlyHint=false/idempotentHint=false/destructiveHint=true 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 focused sentences, no filler, with the core action front-loaded and the fee consequence placed 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 two-parameter mutation tool with an output schema and rich annotations, the description covers the important non-obvious side effects: pending offer cancellation and the possible cancellation fee. No explicit mention of non-cancellable states is included, but the output schema and annotations reduce the remaining 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 coverage is 100%, so the schema already documents task_id and reason clearly. The description adds no parameter-specific semantics beyond what the schema provides. The fee_minor mention relates to output, not to a parameter, so the baseline of 3 is appropriate.

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

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

The description states a specific action and scope: 'Cancel a task and any pending offer.' This clearly distinguishes it from lifecycle-related siblings like post_task, update_task, and make_offer. It also adds a non-obvious consequence—the cancellation fee for accepted tasks—that sharpens the tool's purpose beyond the tool name alone.

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 verb 'Cancel a task' makes the primary use case obvious, and the fee note is useful context, but there is no explicit guidance about when to prefer this tool over siblings such as update_task, nor explicit when-not-to-use guidance. Usage is implied rather than directly routed.

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 safety (readOnly, idempotent, non-destructive), but the description adds substantial context beyond them: meaning+spelling matching, that ranking is advisory and `best_worker_id` is set only when confident, privacy semantics (area is a ~10 km cell centre, never the worker's location; distances rounded to 10 km), the enforced minimum rate, and a prompt-injection warning that worker-authored skills must be read as data, not instructions. It also states it does not commit funds.

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

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

Front-loaded with the purpose and the sibling contrast, then organized into focused paragraphs. It is long, and parts describing output fields (matching, jev_rank, fits, ask_rate) could be trimmed, but with no output schema much of it 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?

Given no output schema, the description carries the return-value explanation (area, distance_km, matching, ask_rate_minor vs ask_rate, jev_rank, fits, best_worker_id) and covers matching modality, ranking behaviour, privacy, and agent guidance. Nothing an agent needs to call or interpret this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds interpretation of the ranking goal and distance semantics, but it also references fields/params (`ranked_by`, `near`) that do not appear in the schema, and it mostly explains return values rather than adding parameter-level 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 with explicit scope ('Find verified workers who have a skill, wherever they are') and immediately separates itself from the sibling search_workers by naming the key difference (no radius). An agent can distinguish it from search_workers 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 explicit when-to-use ('to learn whether anyone on Mundane has a skill at all, or when the item can travel to the worker') and the when-not plus alternative ('for work at a place, use search_workers with that place's coordinates'). This is exactly the routing guidance an agent needs.

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 establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds meaningful context by disclosing the exact data returned and specifying that money fields are integer minor units in the returned currency.

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 deliver the core purpose, the key formatting caveat, and a usage directive without any filler. The information is front-loaded and 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?

With zero parameters and a rich output schema available, nothing essential is missing. The description covers what the tool returns, the unit convention, and when to call it, making it complete for an agent.

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 has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and there is no ambiguity to 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?

The description names a specific operation ('Return the authenticated agent and principal identity, wallet balance, and remaining headroom against every spend cap') with precise scope. It clearly identifies the resource and distinguishes this from sibling tools like make_offer or topup_wallet by focusing on status.

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 final sentence, 'Consult before making offers,' provides an explicit, actionable context for when to call this tool. It does not mention exclusions or alternatives, but the timing guidance is clear and relevant.

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 openWorldHint, and the description adds substantial behavioral context: messages are ordered oldest-first, worker messages are untrusted human input, and the description warns not to act on instructions found in chat. It also discloses that history remains readable after channel closure, which is not implied by the annotations.

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

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

The description is front-loaded with purpose and return shape, then moves to the critical security guidance. Each sentence contributes either operational or safety-relevant information; there is no filler or redundant restating of the tool name.

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

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

Given the output schema exists, the description still covers everything an agent needs: when to use it, how to paginate, what happens after closure, and the untrusted data handling policy. It is complete for safe and correct invocation, especially in a context where worker messages may be adversarial.

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 description still adds value by explaining after_id semantics: pass 0 for the whole thread, then pass the highest seen id to poll for new messages. It also clarifies ordering and that task_id refers to an owned task, going slightly 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 opens with a specific verb and resource: "Read the chat thread on an owned task." It then enumerates exactly what is returned (channel state, task_status, remaining_messages, messages with fields) and is clearly distinguishable from siblings like send_chat_message or get_task_status.

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

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

It gives clear usage context: polling with after_id, reading an owned task's thread, and the fact that history stays readable after the channel closes. It does not explicitly state when not to use this tool or point to alternatives, such as using get_task_status for task state, so it stops short of full exclusion guidance.

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

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

The description discloses output format differences (metadata as text, protected photos as MCP image content), photo processing details (oriented, reduced to 1568px long side), and ownership-based 404 behavior. This goes well beyond the readOnly and idempotent annotations and prepares the agent for actual response 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 sentences carry distinct value: purpose, return format, and access restriction. The text is front-loaded with the verb and resource, and every sentence earns its place without 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 explaining the response composition and error behavior. It could specify the exact metadata fields or how many proof items to expect, but an agent has enough to invoke the tool and interpret the result at a useful level.

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

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

The input schema already covers the single parameter fully, describing task_id as 'The owned task whose submitted proof you want to see.' The description reinforces the ownership constraint but does not add meaningful semantic detail beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb ('View') and resource ('submitted completion proof') and adds lifecycle context ('before accepting or rejecting it') that distinguishes it from status/attachment siblings. An agent can tell this is the pre-review proof tool without opening any other definitions.

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

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

The description clearly frames when to use the tool: when reviewing submitted completion proof before making an accept/reject decision. It does not explicitly name alternatives such as list_task_attachments or submit_completion_review, but the usage context 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 already declare readOnly, idempotent, open-world, and non-destructive, so the safety profile is covered. The description adds useful behavioral detail: integer minor units for offers, ISO 8601 timestamps, screened:<outcome> timeline entries, and possible statuses including disputed or completed.

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 compact sentences, each carrying distinct information: what is returned, the value formats, and special timeline/status semantics. No filler or repetition of schema fields.

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

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

For a single-parameter read-only tool with an output schema, this is complete. It covers data formats and domain-specific values that would otherwise be a surprise, and there are no missing prerequisites or alternatives that need mentioning.

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%: task_id is described as 'The owned task to inspect.' The description adds no extra parameter semantics, which is acceptable because the schema already documents the sole 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?

States a specific verb ('Get') and enumerates the distinct resources returned: lifecycle state, active offer, assigned worker, completion proof, and timeline. This makes it distinguishable from sibling tools like get_task_chat, get_task_proof, and get_spend_status based on content alone.

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 guidance is given about when to choose this tool over siblings such as get_task_chat or get_task_proof. The description simply restates the response contents, so an agent must infer the appropriate use case.

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 mark this as read-only, idempotent, and non-destructive, so the description's extra context focuses on edge cases: null installed_version from source checkout, null latest_version with error reason when PyPI is unreachable, and update_available null when incomparable. It also discloses an install_hint and directs the agent not to perform the upgrade itself. This meaningfully exceeds the annotations and leaves no hidden side effects.

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

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

The description is four sentences, each covering a distinct need: purpose, edge case semantics, operator-action warning, and invocation constraints. It is front-loaded with the headline behavior, and the longer field explanations are warranted by null-state complexity. No filler or repetition.

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

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

For a zero-argument, self-describing version check with an output schema, the description covers all necessary context: what is returned, when values can be null, what the agent should do with an update hint, and network behavior. The agent can invoke it correctly and interpret results without any external knowledge.

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 has zero parameters and the schema has no properties, and the description explicitly confirms 'Requires no arguments.' With no parameters to document, there is nothing missing; the baseline 4 applies because the description states the absence clearly.

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?

Description uses a specific verb ('Report') and concrete resource: the running mundane-mcp server version and whether a newer PyPI release exists. It goes beyond the title by naming the exact fields returned and the PyPI source, making it distinguishable from task/worker/spend siblings. No ambiguity about what the tool does.

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

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

The description explicitly states invocation context: no arguments and no Mundane API contact, which tells the agent it's a cheap, safe version check. It also gives an exclusion for upgrades, saying upgrading is an operator action and not something for the agent to attempt. No explicit alternative tool is named, but no sibling offers version functionality, so the guidance is sufficient.

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

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

Annotations already declare the operation safe and read-only, and the description adds significant behavioral nuance: it explains that ask_rate_minor is enforced, rate_card entries are advisory, and live_now/live_until describe temporary presence. This goes well beyond the annotations and gives agents precise rules for interpreting the response.

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

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

The description is front-loaded with the primary purpose, then efficiently clarifies the most error-prone semantic distinctions (enforced vs. advisory rates, live presence fields). Every sentence adds necessary operational detail; 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?

With a single well-documented parameter, strong safety annotations, an output schema present, and no nested objects, the description is complete for safe invocation. The added rate-card and live-status semantics fill the gaps that would otherwise be ambiguous, making the tool fully usable.

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

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

The input schema fully documents the single parameter worker_id, including where to obtain it ('as returned by search_workers'). The description adds no additional meaning for this parameter itself, so the schema carries the full burden. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: returning one worker's public profile and reputation. It uses a specific verb ('return') with a specific resource ('one worker's public profile'), and the term 'one' differentiates it from list/search tools like search_workers and get_worker_location.

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

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

The description implies usage context: it returns a single worker's profile, and the parameter description notes worker_id comes from search_workers, which suggests a search-then-fetch workflow. However, it does not explicitly name alternatives or state when not to use this tool versus a sibling such as get_worker_location.

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 idempotentHint, but the description adds substantial behavioral specifics beyond them: coordinates exist only while the task is active, sharing cuts off at proof submission/cancellation, only a single current point is stored, and no history is retained. This exceeds what annotations alone convey.

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

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

The description is structured into two useful paragraphs: the first defines the sharing states, the second the privacy contract. It is front-loaded with the main purpose and every sentence contributes. Slightly verbose due to the detailed state enumeration, but justified for the tool's complexity.

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 full sharing state machine and all relevant fields (lat, lng, accuracy_m, updated_at, age_seconds). It also includes staleness guidance and privacy constraints, making it self-sufficient for correct invocation and interpretation.

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

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

Schema coverage is 100%, and the schema already describes task_id as an owned task with request_live_location and worker consent. The description adds context about the sharing state machine and privacy, but it doesn't introduce new meaning for the parameter itself beyond the schema's own 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 (get), resource (worker location), and prerequisite (owned task posted with request_live_location). Distinguishes from sibling tools like get_worker, get_task_status, and get_task_proof by focusing on the live-location use case.

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 clear context: the tool is for owned tasks with request_live_location and worker consent. The staleness guidance (check age_seconds) and the privacy contract tell the agent how to interpret results. However, it never explicitly names alternative tools or states 'use X instead,' so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond annotations by revealing what the result contains (constraints and proof types) and when it should be invoked relative to task posting.

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. The main action and returned content are front-loaded, and the usage guidance is placed in the second sentence, making it quick for an agent to parse.

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

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

For a parameterless, read-only, idempotent tool with an output schema, the description fully covers what an agent needs: what is returned, why it matters, and when to call it. Nothing essential is missing.

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

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

There are zero parameters and the schema description coverage is 100%, so the description does not need to explain parameters. The baseline of 4 for a parameterless tool applies.

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

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

The description states a specific action ('List'), a clear resource ('task capabilities this agent may dispatch'), and the content ('per-capability constraints and required proof types'). It clearly differentiates this from sibling tools like post_task or get_task_status by focusing on capability discovery rather than task operations.

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

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

The description explicitly instructs 'Call before posting a task,' giving a direct and actionable when-to-use signal in the agent's workflow. It does not mention exclusions or name alternative tools, but the timing guidance is sufficient to select this tool correctly.

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 read-only, idempotent, non-destructive, and open-world hints, so the description adds beyond that by stating it returns only metadata and never the bytes. It also adds the ownership constraint ('owned task's attachments'), which is useful behavioral 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?

The description is two sentences with no filler: it front-loads the action, lists the fields, clarifies the exclusions, and gives the intended use case. Every part 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 simple one-parameter listing tool with rich annotations and an output schema, the description is complete. It tells the agent what it will get, what it will not get, and how to use the result. Nothing essential is missing.

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

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

Schema coverage is 100%, and the task_id parameter already has a clear description. The tool description reinforces that the task must be owned but adds no new parameter syntax or format details beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List an owned task's attachments,' and enumerates the exact fields returned (id, filename, content_type, byte_size, created_at). The explicit 'never the bytes' qualifier also distinguishes this listing tool from download/proof-related siblings.

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 clear use case: 'Use to confirm what the worker can currently download.' It does not explicitly name alternative tools or when not to use it, but the purpose is specific enough that an agent can select it correctly.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description explains the continuation mechanism (next_since_id), that offer events are included, and that each event contains task_id, action, states, actor, and timestamp. This adds meaningful behavioral context without contradicting any annotation.

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

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

The description is detailed but every sentence earns its place: value proposition, sibling contrast, usage pattern, event shape, and follow-up actions. It is front-loaded with the core purpose and avoids 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?

Given the rich output schema and annotations, the description is complete enough for an agent to call the tool correctly. It covers start state, continuation, polling cadence, response field expectations, and downstream alternatives.

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. The description adds valuable semantic detail for since_id, including how to initialize and advance it via next_since_id. The limit parameter is left to the schema, so the description improves on but does not fully replace the schema's role.

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

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

The description clearly states the tool's purpose: catch up on all task events that happened since a previous call. It explicitly distinguishes itself from the sibling await_task_update, so an agent knows exactly what this tool does and how it is different.

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 explicit when-to-use guidance: use it when you weren't actively watching, pass next_since_id, start with since_id=0, and poll at startup and periodically. It also contrasts with await_task_update and provides a concrete workflow for following up with other 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?

The description discloses the consequential side-effects: the platform fee is added to amount_minor, the all-in total is held in escrow on success, and structured errors cover budget, worker eligibility/ask-rate, wallet, or spend-cap failures. This goes well beyond the sparse annotation hints and tells an agent what to expect externally.

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

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

Three sentences with no filler. The purpose is front-loaded, and the parameter explanations are compact and woven into the behavioral context. 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?

With a full schema, annotations, output schema present, and a description that covers side-effects and failure modes, an agent has everything needed to select and invoke this tool correctly. The only minor gap is explicit usage routing, but it is not essential.

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

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

The input schema already covers all parameters with descriptions, so the baseline is 3. The description restates the key semantics for amount_minor and expires_in_seconds, but it does not add information that is not already present 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?

Description opens with 'Offer a task to a worker' – a specific verb and resource that clearly distinguishes this from sibling tools like post_task and search_workers. It is immediately obvious what action this tool performs without needing to inspect 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: this is the step after a task exists and a worker is selectedaiman. The schema hints at prerequisites by saying task_id comes from post_task and worker_id from search_workers, but the description itself does not explicitly say when to use this tool or when to prefer a sibling.

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

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

The description goes far beyond the annotations, detailing the screening cascade (policy_gate, shape_match, LLM classifier, human_review), environmental dependencies (ANTHROPIC_API_KEY vs SCREENING_LLM_FALLBACK), proof requirement unions and non-waivable floors, and the consent semantics of live location. No annotation contradiction exists.

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

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

The description is long but densely informative, and each sentence earns its place in clarifying a complex 13-parameter operation. It is front-loaded with the core behavior before diving into proof and live-location specifics. Slightly more structural separation could improve scannability, but there is no 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?

Given the tool's complexity and the presence of an output schema, the description covers the important operational details: screening outcomes, proof union semantics, budget cap references, and live location consent. It even points to get_spend_status and list_capabilities where relevant, making the call contextually complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds critical meaning: budget_max_minor is an all-in ceiling, deadline must include a timezone, proof_requirement_opt_outs waives defaults but never floors, and request_live_location cannot be added post-hoc. These nuances materially change how an agent should populate the parameters.

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

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

The description opens with a specific verb and resource: 'Create a real-world task and run the full screening cascade.' It clearly explains what the tool does, including resulting statuses. It does not explicitly differentiate from siblings like update_task or cancel_task by name, so it stops short of 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?

The context is clear: use this to post a new task, with screening and proof implications spelled out. It also gives a when-not warning by noting request_live_location cannot be added later. It does not explicitly list alternatives like update_task for later edits, but the usage context 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 already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds material context beyond them: no funds are committed, distance_km is measured to the ~2 km grid cell centre rather than the worker for privacy, live presence is explicit and self-expiring with a ranking lift, and rate_card is advisory only. This is exactly the kind of behavior annotations cannot express.

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 is front-loaded and the paragraphs are organized by concern (pricing, distance/privacy, live_now, skill). It is on the long side with some restatement of field names, but nearly every sentence carries information an agent needs.

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

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

Given 10 parameters, an output schema, and rich annotations, the description covers the decisive nuance: pricing basis, privacy-preserving distance, live availability, and skill-matching fallbacks. It also previews key result fields (live_now, live_until, match_score, skills) which the output schema documents, so nothing an agent needs to call it correctly is missing.

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

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

Although schema coverage is 100%, the description still adds meaning the schema lacks: ask_rate_minor is an enforced minimum per-task price in minor units, max_rate_minor filters on that same per_task basis, rate_card is advisory, and skill is fuzzy case-insensitive open-vocabulary matching with optional semantic synonym bridging that lifts match_score. These go well beyond the schema's one-line field descriptions.

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

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

The opening sentence gives a specific verb, resource and scope: 'Find verified workers near a point matching capability, rating, and price filters, ranked for selection.' It also clarifies the tool is non-committal ('Does not commit funds'). It does not explicitly distinguish itself from the sibling find_workers_by_skill, leaving that routing to inference, so it stops short of 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?

It gives actionable conditions: set live_now=true only for immediate-execution tasks, leave it off otherwise; try the worker's own wording or drop skill when results look sparse. However it never names find_workers_by_skill as the alternative for pure skill lookup, so the when-not/alternative guidance is incomplete.

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=false, idempotentHint=false, destructiveHint=false. The description adds meaningful behavioral context: the channel lifecycle (opens on acceptance, closes on proof/cancellation), hard rate limits (500 chars, 50 messages, 10/min), and structured 409 error variants. It doesn't fully describe all failure modes or side effects, but it goes well 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?

The description is dense but every sentence earns its place: purpose, channel lifecycle, hard caps, return value, and error semantics. It is front-loaded with the core purpose and examples, then constraints, then return/error info. No fluff.

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

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

For a 2-param tool with no output schema, the description covers the key behavioral context: when the channel is available, limits, return value, and error cases. It doesn't explicitly describe the success response shape beyond 'message id and remaining_messages budget', but that is stated. Minor gap: no mention of what happens if the task is not owned or if the worker is not assigned, but the 409s cover the main failure modes.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds context about the body's purpose ('short coordination message', examples) and the task_id's scope ('owned task'), but doesn't add new syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Send'), a specific resource ('a short coordination message to the worker assigned to an owned task'), and gives concrete examples. It is clearly distinguished from siblings like get_task_chat (retrieval) and make_offer/post_task (task creation/offers).

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

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

The description explicitly explains when the channel is open (worker accepted the offer) and when it closes (task leaves accepted/in_progress), and gives hard caps. It also implies when not to use it (only for logistics that matter, not general chatter). This is strong contextual 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses real side effects: accept publishes the escrow.release outbox event and creates worker_payouts; reject creates a disputes row; request_changes reopens the task, archives superseded proof, extends the deadline, and keeps escrow held. It also surfaces the `change_request_limit_reached` error. No annotation contradiction exists.

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

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

The description is dense but not bloated: it front-loads the core purpose, then organizes each branch by decision type, and ends with the limit/error behavior. Every sentence carries operational information useful for correct invocation, with no filler or redundant restatement of the schema.

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

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

For a mutation tool with no output schema, the description covers the essential operational context: side effects of each decision, when each branch should be selected, the retry limit, the deadline extension, and the error response. An agent has enough information to invoke the tool correctly and anticipate outcomes.

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. The description adds meaningful behavior beyond the schema by explaining what each `decision` value actually triggers (payouts, dispute, resubmission) and why `reason` is necessary ('read by a person'). It does not add much for `task_id`, but the extra `decision` semantics justify a 4.

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

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

The description opens with a specific action and resource: 'Review submitted proof' and immediately enumerates the three possible decisions (`accept`, `reject`, `request_changes`). This clearly differentiates the tool from review-adjacent siblings like `submit_rating` and `submit_experience_feedback`, and matches the annotation title 'Review completion proof'.

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 explicit when-to-use guidance: request_changes is for 'incomplete or ambiguous' proof 'rather than wrong', and is called 'the right call far more often than rejecting'. It also provides a hard when-not boundary: a task may be sent back at most twice before accept/reject is mandatory, with the resulting 409 error. This is concrete decision-rule guidance.

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

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

The description adds important behavioral context beyond the annotations: all submitted text is stored as untrusted data and is not interpreted as instructions or used to change the active task. This reassures the agent that the tool is non-destructive and safe to call. It does not contradict the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and it fills a gap left by those annotations.

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

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

The description is three sentences with no waste: the purpose is front-loaded, the second sentence covers the essential phrasing and optional fields, and the third provides a critical safety note. Every sentence earns its place, and the structure is easy to scan.

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 feedback submission tool with no output schema, the description is complete: it defines the purpose, gives a phrasing convention, lists the optional parameters, and clarifies that the submission does not alter the active task. Nothing an agent needs to call the tool correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds value by prescribing a specific phrasing template for gap_text ('If I'd had a way to ..., I could have ...'), which goes beyond the schema's generic description. It also groups the optional parameters (tags, task_id, free_text) but adds no new meaning for them; the extra guidance for gap_text justifies a 4.

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

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

The description states a specific action ('explicitly submit post-task experience feedback') and a clear resource ('to Mundane'), which immediately distinguishes it from siblings like submit_rating or submit_completion_review. It also provides a concrete phrasing template for the core field, making the tool's purpose unambiguous.

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

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

The description gives clear context for when to use the tool: post-task experience feedback about gaps. It does not explicitly compare to alternatives like submit_rating or submit_completion_review, but the phrasing guidance and the emphasis on 'post-task' make the intended use evident. It stops short of naming specific sibling exclusions, so a 4 is appropriate.

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

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

The description discloses the non-obvious side effect that the rating is recorded and the worker's Bayesian aggregate is recomputed with explicit prior_mean=4.2 and prior_weight=10, and that worker_new_aggregate_rating is the new aggregate. This goes beyond the annotations, which only mark readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The 'once' constraint also reinforces the immutability/idempotency 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?

The description is two sentences: the first front-loads the core action and constraints, the second explains the side effect and resulting aggregate field. There is no filler or repetition of schema content.

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

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

For a simple three-parameter mutation with full schema coverage, the description covers the action, the one-time constraint, the scoring range, the required description, and the key side effect and new aggregate field. It does not enumerate full return values or error behavior, but the explicit worker_new_aggregate_rating line keeps it largely complete for selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents all three required parameters and their constraints. The description's mention of an integer score from 1 to 5 and a written description only restates schema facts; it does not add new parameter-level meaning.

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

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

The description clearly states the verb-resource pair: 'Rate a completed task once' with an integer score from 1 to 5 and a written description. It also includes the distinctive worker Bayesian aggregate recomputation, which helps separate it from generic rating tools. However, it does not explicitly contrast it with sibling tools like submit_completion_review or submit_experience_feedback.

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

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

It gives clear context: use this for a completed task, only once, with a numeric score and written description. It does not, however, state when not to use it or name alternative sibling tools, so the when-not guidance is absent.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds valuable behavioral context: the agent never handles card details, the wallet credits automatically after payment, and the checkout link is handed to a human. It also clarifies the idempotency behavior implicitly by mentioning retries reuse the existing checkout. This goes beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded: the core action and return value are in the first sentence, followed by the human-in-the-loop flow, then parameter clarifications. Every sentence earns its place, and there is no redundant restating of the title or schema.

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

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

Given the tool's complexity (5 params, 1 required, output schema present), the description covers the essential workflow: what it returns, who pays, how the wallet credits, and how to confirm. The output schema exists, so return values need not be detailed. The only minor gap is not explaining what happens on payment failure, but the cancel_url parameter and the overall flow make this sufficient.

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 parameters. The description adds extra meaning by explaining the amount_minor unit with a concrete example (500 = $5.00) and emphasizing 'never a float', which is critical for correct invocation. It also reinforces that currency must match the principal's wallet currency, which is not in the schema. This adds value beyond the schema.

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

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

The description states a specific verb ('Create a Stripe Checkout link'), a clear resource (the principal's wallet), and the exact outcome (adds funds). It also distinguishes itself from siblings like get_spend_status by explaining the wallet credits automatically and how to confirm. This is a clear, specific purpose that an agent can act on.

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

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

The description explicitly tells the agent when to use this tool: to create a checkout link for a human to pay, and explicitly says the agent never touches card details. It also names the sibling get_spend_status as the way to confirm the credit, providing a clear workflow. This is strong usage guidance.

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

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

The description goes far beyond the annotations, disclosing material side effects: the full screening cascade, possible rejection, pending-offer withdrawal, automatic escrow refund, and immutability of certain task states. These behavioral traits are not visible in the annotations, which only include generic read-only/destructive/idempotent flags. No contradiction with annotations.

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

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

The description is dense but well-structured, front-loading the core purpose, then layer-by-layer constraints, side effects, and error conditions. Every sentence contributes new information without redundancy or filler.

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

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

For a complex mutation tool, the description covers the critical behavioral nuances an agent needs: the re-screening cascade, offer/escrow implications, when changes are skipped, and immutable states. With an output schema present, return-value details are not required, and the provided description is fully adequate for safe invocation.

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

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

The schema already has 100% parameter coverage, so the baseline is 3. The description adds value beyond the schema by grouping parameters into material (title, instructions, location, capabilities, proof requirements) versus budget/deadline-only, and clarifies the 'at least one field required' constraint that the schema's required list implies but does not state.

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

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

The description opens with a specific verb and resource: 'Amend an unassigned task,' immediately distinguishing it from cancel/post operations. It states the precise operational scope (unassigned tasks only) and the action it performs, so an agent knows exactly what invoking this tool does.

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

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

Explicitly tells when to use this tool instead of cancel-and-repost, and details when it is refused ('409') or when different behavior applies (material changes re-screening vs budget/deadline-only changes). This is model usage guidance with clear exclusions.

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