Hire a real human for real-world verification, product testing, AI output review, and errands.
Scored across 6 tools
Tools cover distinct parts of a human-in-the-loop workflow: manifest lookup, task submission, status checks, free-form messaging, and thread replies/reads. check_message_thread and reply_in_message_thread both operate on threads and require message_id+access_token, which could cause some confusion about when to read versus write, but their read/write purposes are otherwise clear.
Mostly follows a consistent verb_noun or resource_action pattern (check_message_thread, check_task_status, get_human_services, message_human_operator, reply_in_message_thread, submit_human_task). Minor variance in verb style (message vs reply vs submit) is readable and domain-appropriate.
Six tools are well-scoped for a human-task marketplace: discovery, submission, status, messaging, and thread operations. No redundant tools and no obvious missing surface area.
Covers the full lifecycle from service discovery through submission, status tracking, and communication. One minor gap: no tool to list or manage previously submitted tasks/messages, so agents must retain task_ids and tokens themselves.
Read the thread for a message you sent: the original text, every reply oldest-first, and whether the operator has answered. Needs the message_id and the access_token from the submission response. An empty replies list means no answer yet — the operator works at human speed, so poll occasionally rather than in a loop.
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | The message id from message_human_operator, e.g. MSG-2026-1A2B3C4D | |
| access_token | Yes | The access_token returned once at submission — the only key to the thread. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reinforces the readOnlyHint annotation by explicitly stating it reads a thread and explains that an empty replies list means no answer yet. It goes beyond the annotation by describing the expected state of the output based on operator behavior, though it does not detail side effects (which is fine for a read operation).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the primary purpose. It uses only a few sentences to convey the output, parameter source, and polling guidance, with no redundant or vague phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of sibling tools, the description is complete enough: it explains the output, the meaning of an empty reply list, and the expected polling behavior. It lacks an explicit output schema, but the described output contents are sufficient for an agent to use the result. Minor edge cases (e.g., errors) are not covered but are not critical for this read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes both parameters with examples, and the description adds the context that these come from the submission response, clarifying their origin. This extra context helps the agent know where to obtain the values, going slightly beyond the schema alone.
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 reads a message thread, listing the exact output contents (original text, replies oldest-first, answer status). It distinguishes itself from sibling tools like reply_in_message_thread or submit_human_task by focusing on reading rather than sending or submitting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use the tool: after receiving a submission response, and it advises polling occasionally instead of in a loop due to human-speed responses. It does not explicitly mention alternatives or when not to use it, but the read-only nature is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a submitted task by its task_id. Returns current status (submitted → accepted → delivered, or rejected), status history with timestamps, seen_by_operator_at (the moment a human actually saw the task — usually well before the first status change), eta (operator-set delivery estimate, once accepted), and any operator notes. Once delivered, the response also carries receipt (a signed JWS binding the deliverable's sha256 to the lifecycle timestamps) and deliverable_sha256 — verify offline against https://humanforai.dev/.well-known/jwks.json. In hosts that support MCP Apps the result also renders as a task status card (timeline, seen-by-human moment, ETA, operator notes, receipt) with a Refresh button; the JSON result carries the same data.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | Task ID returned by submit_human_task, e.g. HFAI-2026-A1B2C3D4E5F60718 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint and openWorldHint; the description goes far beyond that, spelling out the full status lifecycle (submitted → accepted → delivered, or rejected), the meaning of seen_by_operator_at, when eta appears, and that a signed JWS receipt plus deliverable_sha256 become available on delivery. The offline verification instruction with the JWKS URL is exactly the kind of behavioral detail an agent cannot infer from 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?
The purpose is front-loaded in the first sentence and the remaining clauses each carry distinct payload (returned fields, verification, rendering). It is dense and slightly long, but nothing reads as 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, so the description must carry the full return-value burden, and it does: it enumerates status, history, seen_by_operator_at, eta, notes, receipt, and deliverable_sha256, plus the UI rendering path. Nothing an agent needs to call or interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the sole parameter already carries a concrete example format (HFAI-2026-...), so the schema does the heavy lifting. The description only restates 'by its task_id' and adds no syntax or format guidance beyond it, making the baseline 3 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 ('Look up a submitted task by its task_id') and immediately scopes it to tasks submitted elsewhere, which cleanly separates it from the submit/message siblings. An agent can distinguish it from submit_human_task or check_message_thread 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?
The phrase 'a submitted task' plus the schema's note that task_id comes from submit_human_task makes the post-submission retrieval context clear. However, it never explicitly states when not to use it (e.g. polling cadence, or that message threads use check_message_thread instead), so there are no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the Human For AI manifest: available services, operator profile (location, languages, working hours), response times, accepted and rejected task types, and trust & safety policy. Call this first to decide whether and how to hire the human. The catalog is examples, not limits — unlisted needs are welcome as custom_human_in_the_loop.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description uses 'Fetch' and 'Call this first,' which imply a read-only, informational operation consistent with the readOnlyHint annotation. It also aligns with openWorldHint by stating the catalog is examples, not limits. The description adds context about the manifest contents beyond the annotations, providing transparent expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the first sentence listing the manifest contents and the second providing a clear usage directive. The open-world note is brief and adds value without bloat. The structure is front-loaded with the core purpose and then actionable guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for its simple, parameterless, read-only nature. It explains what information will be returned (services, profile, policies, etc.), how to use the information (decide whether and how to hire), and how to handle catalog gaps. No output schema is present, but the description sufficiently covers expected content.
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 description coverage is 100% (empty schema). There is nothing to explain about parameters; the description correctly omits any parameter discussion. The baseline for high schema coverage applies, and no additional compensation is 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?
The description clearly states the tool fetches the Human For AI manifest and enumerates its contents (services, operator profile, response times, task types, trust & safety). It also explicitly says 'Call this first to decide whether and how to hire the human,' which distinguishes its purpose from the sibling tools that submit or check tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit timing guidance: 'Call this first to decide whether and how to hire the human.' This tells the agent when to use this tool relative to the alternatives (e.g., before submit_human_task or message_human_operator). The note that unlisted needs are welcome as custom_human_in_the_loop also clarifies how to handle catalog gaps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a free-form message to the human operator — questions, scoping, custom or recurring projects, anything that is not yet a ready-made task. reply_to is REQUIRED: an email a human can read (MX-checked), or an https URL to receive the reply as a signed webhook push. The response also carries thread_url + access_token — every message is a pollable thread, so you can read the reply with check_message_thread even without a mailbox. Keep the token: it is shown only once.
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | Your agent or system identifier | |
| message | Yes | The message. Plain language, English. | |
| subject | No | Short subject line | |
| reply_to | Yes | REQUIRED. Email address for the reply (real, reachable, MX-checked) — or an https webhook URL for a signed push. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, open-world operation. The description adds valuable context: reply_to is required and can be an MX-checked email or a signed webhook URL; the response includes thread_url and access_token; every message becomes a pollable thread; and the token is shown only once. These specifics go beyond the annotation flags and clarify the reply mechanism, though it does not detail the exact response schema (which is absent).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph of four sentences, front-loaded with the purpose, then the required parameter, the reply mechanism, and the token caveat. It is efficient with no filler, though it packs several details into a dense structure that could be slightly more scannable with line breaks. Still, it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters (two required) and no output schema, the description covers the essential operational details: how to specify the reply destination, how to read the response, and the security caveat about the token. It doesn't mention error conditions or immediate side effects, but those are not critical given the open-world hint and the clear mechanism for obtaining the reply.
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 each parameter is documented in the schema. The description goes further by explaining the dual nature of reply_to (email vs. webhook) and the one-time token behavior, which adds meaning beyond the schema's simple descriptions. This justifies a score above the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (send), the resource (human operator), and the scope (free-form messages, questions, scoping, custom/recurring projects, anything not a ready-made task). This explicitly differentiates it from submit_human_task, which handles ready-made tasks, so an agent can easily distinguish purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'anything that is not yet a ready-made task,' which tells the agent when to use this tool instead of submit_human_task. It also names check_message_thread as the way to read replies, providing a clear alternative for follow-up. No ambiguity remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a follow-up to a thread you opened — answer a question the operator asked, add detail, correct yourself, or withdraw the request. Prefer this over sending a brand-new message about the same subject. Needs the message_id and access_token from the submission response.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | The follow-up text | |
| message_id | Yes | The message id from message_human_operator | |
| access_token | Yes | The access_token returned once at submission |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, non-idempotent, non-destructive; description adds context that it modifies an existing thread and can withdraw a request, making side effects clear. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences; no redundancy; clear structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple 3-param tool; includes purpose, guidance, and source of required values; no output schema needed.
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 descriptions for all three params are clear and the description reiterates where message_id and access_token come from.
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 specific verb 'Add a follow-up' to a thread, lists concrete use cases (answer question, add detail, correct, withdraw), and explicitly distinguishes from sending a brand-new message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Prefer this over sending a brand-new message about the same subject' and notes required inputs from submission response. Could further contrast with message_human_operator for new threads, but current guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a task for the human operator to perform in the real world. Returns a task_id immediately; the human reviews every task before accepting it (this is not instant execution). The operator is push-notified on submission; check_task_status shows seen_by_operator_at once a human has seen the task. Free during the pilot. contact_email must be a real mailbox (MX-checked) — it is how the deliverable reaches you. No mailbox? Set delivery to 'status_poll' instead: the deliverable arrives as text in operator_notes via check_task_status (limited to 1 such task per client per day). In hosts that support MCP Apps the result also renders as a task status card with a Refresh button; the JSON result carries the same data.
| Name | Required | Description | Default |
|---|---|---|---|
| deadline | No | ISO 8601 datetime, e.g. 2026-07-10T12:00:00+03:00 | |
| delivery | No | How the deliverable reaches you. 'email' (default) needs contact_email. 'status_poll' is the no-mailbox path for autonomous agents: the result arrives as text in operator_notes via check_task_status — keep the task_id, it is your only key. Budget: 1 status_poll task per client per day. | |
| requester | No | Your agent or system identifier, e.g. my-agent/1.0 | |
| task_type | Yes | Service category — see get_human_services for descriptions. The list is not exhaustive: use custom_human_in_the_loop for anything that fits no other category | |
| description | Yes | What to do, where, and what success looks like. Specific, self-contained tasks are accepted faster. | |
| contact_email | No | Where the deliverable and clarifying questions are sent. Required unless delivery is 'status_poll'. Must be a real, reachable mailbox — placeholder domains are rejected and the domain is MX-checked. | |
| output_format | No | text_report (default), text_report_with_photos, structured_json, annotated_screenshots, or video | |
| location_detail | No | City, address, or area — required in practice when location_required is true | |
| location_required | No | true if the task needs physical presence (coverage is confirmed at review) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: the human reviews every submission before acceptance, the operator is push-notified, submission is free during the pilot, contact_email is MX-checked, status_poll is capped at one task per client per day, and MCP Apps hosts render a status card. This is exactly the kind of context annotations (readOnly=false, openWorld=true, idempotent=false, destructive=false) cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the async/review caveat, then the delivery mechanics, then the host-rendering note. Dense but every clause carries operational information; the MCP Apps card sentence is the only mildly expendable part.
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 correctly carries the return contract (a task_id returned immediately, retrieval via check_task_status), the delivery paths, and the daily status_poll limit. An agent has everything needed to call this correctly and to know what to expect afterward.
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 genuine meaning: contact_email must be a real MX-checked mailbox because it is the delivery channel, delivery='status_poll' is framed as the no-mailbox path with a keep-the-task_id constraint, and the JSON/card equivalence is explained. That is more than restating 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 and resource (submit a task for the human operator to perform in the real world) and immediately frames the async, human-reviewed nature of the operation, which separates it from instant-execution siblings. An agent can identify what this tool does 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?
Gives real usage context: tasks are reviewed, not executed instantly; results are retrieved via check_task_status; status_poll is the fallback path when no mailbox exists, with a stated budget. It does not explicitly contrast against siblings like message_human_operator, so it falls short of a full when/when-not routing statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
check_message_threadmessage_human_operator1 field changedInput schema / properties / reply_to / descriptionPrevious value: -"REQUIRED. Email address for the reply — must be a real, reachable mailbox (MX-checked)."New value: +"REQUIRED. Email address for the reply (real, reachable, MX-checked) — or an https webhook URL for a signed push."reply_in_message_threadsubmit_human_task1 field changedInput schema / properties / task_type / enumPrevious value: -[
- "real_world_verification",
- "product_or_app_testing",
- "human_judgment_and_feedback",
- "data_collection",
- "local_physical_task",
- "ai_output_review",
- "prompt_and_workflow_testing",
- "simulation_and_automation_testing",
- "accessibility_and_usability_check",
- "custom_human_in_the_loop"
-]New value: +[
+ "real_world_verification",
+ "product_or_app_testing",
+ "human_judgment_and_feedback",
+ "data_collection",
+ "local_physical_task",
+ "ai_output_review",
+ "prompt_and_workflow_testing",
+ "simulation_and_automation_testing",
+ "accessibility_and_usability_check",
+ "decision_escalation",
+ "custom_human_in_the_loop"
+]check_task_status1 field changedInput schema / properties / task_id / descriptionPrevious value: -"Task ID returned by submit_human_task, e.g. HFAI-2026-A1B2C3D4"New value: +"Task ID returned by submit_human_task, e.g. HFAI-2026-A1B2C3D4E5F60718"submit_human_task3 fields changedInput schema / properties / contact_email / descriptionPrevious value: -"REQUIRED. Where the deliverable and clarifying questions are sent. Must be a real, reachable mailbox — placeholder domains are rejected and the domain is MX-checked."New value: +"Where the deliverable and clarifying questions are sent. Required unless delivery is 'status_poll'. Must be a real, reachable mailbox — placeholder domains are rejected and the domain is MX-checked."Input schema / properties / deliveryAdded value: +{
+ "description": "How the deliverable reaches you. 'email' (default) needs contact_email. 'status_poll' is the no-mailbox path for autonomous agents: the result arrives as text in operator_notes via check_task_status — keep the task_id, it is your only key. Budget: 1 status_poll task per client per day.",
+ "enum": [
+ "email",
+ "status_poll"
+ ],
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "task_type",
- "description",
- "contact_email"
-]New value: +[
+ "task_type",
+ "description"
+]message_human_operator2 fields changedInput schema / properties / reply_to / descriptionPrevious value: -"Email address for the reply — strongly recommended"New value: +"REQUIRED. Email address for the reply — must be a real, reachable mailbox (MX-checked)."Input schema / requiredPrevious value: -[
- "message"
-]New value: +[
+ "message",
+ "reply_to"
+]submit_human_task2 fields changedInput schema / properties / contact_email / descriptionPrevious value: -"Where the deliverable and clarifying questions are sent. Strongly recommended."New value: +"REQUIRED. Where the deliverable and clarifying questions are sent. Must be a real, reachable mailbox — placeholder domains are rejected and the domain is MX-checked."Input schema / requiredPrevious value: -[
- "task_type",
- "description"
-]New value: +[
+ "task_type",
+ "description",
+ "contact_email"
+]submit_human_task1 field changedInput schema / properties / task_type / descriptionPrevious value: -"Service category — see get_human_services for descriptions"New value: +"Service category — see get_human_services for descriptions. The list is not exhaustive: use custom_human_in_the_loop for anything that fits no other category"check_task_statusget_human_servicesmessage_human_operatorsubmit_human_taskHire humans for tasks agents cannot do: errands, calls, photos, verification. Escrowed, verified.
Pay people nearby for physical work: find out if something is true, or have it done.
AI agents hire a human to observe, log or film on site. Typed results, feasibility before payment.
AI agents hire a human to observe, log or film on site. Typed results, feasibility before payment.
Add one secure layer between your agents and this server.
