Skip to main content
Glama

Human For AI

by dev.humanforai
OverviewDiscussionsAdmin

Submit a task to the human

submit_human_task

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
deadlineNoISO 8601 datetime, e.g. 2026-07-10T12:00:00+03:00
deliveryNoHow 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.
requesterNoYour agent or system identifier, e.g. my-agent/1.0
task_typeYesService 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
descriptionYesWhat to do, where, and what success looks like. Specific, self-contained tasks are accepted faster.
contact_emailNoWhere 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_formatNotext_report (default), text_report_with_photos, structured_json, annotated_screenshots, or video
location_detailNoCity, address, or area — required in practice when location_required is true
location_requiredNotrue if the task needs physical presence (coverage is confirmed at review)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / task_type / enum
      Previous 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"
+]
  2. Changed3 schema fields changed
    • changedInput schema / properties / contact_email / description
      Previous 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."
    • addedInput schema / properties / delivery
      Added 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"
+}
    • changedInput schema / required
      Previous value: -[
-  "task_type",
-  "description",
-  "contact_email"
-]New value: +[
+  "task_type",
+  "description"
+]
  3. Changed2 schema fields changed
    • changedInput schema / properties / contact_email / description
      Previous 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."
    • changedInput schema / required
      Previous value: -[
-  "task_type",
-  "description"
-]New value: +[
+  "task_type",
+  "description",
+  "contact_email"
+]
  4. Changed1 schema field changed
    • changedInput schema / properties / task_type / description
      Previous 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"
  5. First observed

TDQS

A4.6/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

All Human For AI toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources