Skip to main content
Glama

Invoke Human Tool

by com.invokehumantool
OverviewDiscussionsAdmin

Send a structured form

send_ui_handoff
Destructive

Create one HUI 0.1 form. The person answers with native controls or the signed link. No HTML, CSS, or JavaScript. Call validate_ui first. HUI 0.1 is a JSON document. No HTML, CSS, or JavaScript. kinds: markdown, heading, callout, text, number, choice, multichoice, approval, rating, slider, toggle, date, time, section, group, disclosure, columns. inputs need id matching ^[a-z][a-z0-9_]{0,40}$. visibleIf and requiredIf use == != < > in && || ! plus field ids, strings, numbers, true, false, null, and lists. options may be an array of {value, label} or {"$bind":"/pointer"} into data. Do not send colors, fonts, or pixel sizes. tone is default, accent, or warning. emphasis is true or false. A flat children array is allowed. steps is the other layout, at most 6. Call validate_ui before send_ui_handoff when you are unsure. The result is answers keyed by field id, plus summary_text. This sends something to a person and cannot be silently undone. Sending again creates a second handoff. An agent key does not receive answer_url.

Input Schema

NameRequiredDescriptionDefault
uiYesHUI 0.1 document: { hui: "0.1", steps or children }.
dueNoYYYY-MM-DD or an ISO timestamp.
tagsNo
titleYes
sourceNoOptional session context stored with the handoff and shown on the iPad.
lenientNoWhen true, unknown properties are warnings and are dropped. Defaults to false, which rejects them.
routingNoSame as send_handoff. A UI answer completes the handoff.
from_agentYesName of the agent sending the handoff.
recipientsNoPeople who should receive this handoff, besides the signed-in account. Same shape as send_handoff.
await_answerNoSet true to wait for the human's answer. When this client declares the MCP Tasks extension, the call returns a task and the client delivers the same JSON as get_handoff_result once they submit. Omit it, or pass false, to get the handoff id immediately and keep working. Clients that do not declare Tasks ignore this flag and return the handoff id, same as today.
callback_urlNoPublic https URL notified when the handoff is submitted. The body includes answers, summary_text, and answered_by.
instructionsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / await_answer
      Added value: +{
+  "description": "Set true to wait for the human's answer. When this client declares the MCP Tasks extension, the call returns a task and the client delivers the same JSON as get_handoff_result once they submit. Omit it, or pass false, to get the handoff id immediately and keep working. Clients that do not declare Tasks ignore this flag and return the handoff id, same as today.",
+  "type": "boolean"
+}
  2. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description goes beyond them by explaining the consequence: the send cannot be silently undone, re-sending creates a second handoff, and an agent key does not receive answer_url. Those are exactly the warnings an agent needs before calling a non-idempotent mutation. It stops short of stating auth or rate-limit behavior.

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

Conciseness3/5

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

The first sentence is well front-loaded and the irreversibility warning lands early. But 'No HTML, CSS, or JavaScript' is stated twice and the validate_ui instruction is repeated in two separate sentences, so a meaningful fraction of the text is redundant. The mid-section reads as a dense dump of constraints rather than ordered guidance.

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

Completeness4/5

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

For a 12-parameter, nested-object, no-output-schema tool, the description covers the hard parts: document format, validation prerequisite, idempotency risk, and what the answer looks like ('answers keyed by field id, plus summary_text'). Remaining gaps — recipients/permission defaults, await_answer semantics, routing — are handled adequately by schema descriptions.

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 75%, so the schema already carries much of the load. The description nonetheless adds substantial meaning for the opaque `ui` object — the list of allowed kinds, the id regex, the visibleIf/requiredIf operator grammar, the options array vs $bind form, tone/emphasis values, and the 6-step cap — all of which is absent from the schema. It also states the return shape that the 'ui' answers will produce.

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

Purpose4/5

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

Opens with a specific verb and resource ('Create one HUI 0.1 form') and clarifies the interaction model (the person answers with native controls or a signed link). The repeated 'No HTML, CSS, or JavaScript' hints at a contrast with send_html_handoff without ever naming that sibling, so differentiation from the handoff family is only implied.

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

Usage Guidelines3/5

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

Gives a concrete prerequisite ('Call validate_ui first') and repeats it for the unsure case, which is real guidance. However, it never states when to pick this over send_handoff, send_html_handoff, or delegate_handoff — the closest it comes is the negative framing about HTML. Sibling routing is left to the schema's 'Same as send_handoff' note.

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

All Invoke Human Tool 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