Invoke Human Tool

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description's 'The default is destructive' largely restates that. It does add genuine context the annotations cannot convey — that the default release drops the caller's own duty to view — but it never addresses the await_answer/Tasks path, which changes the call from fire-and-forget to blocking.

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

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

Four short sentences, no filler, with the release behavior placed early. The trailing 'The default is destructive' is a slightly clumsy afterthought that duplicates the annotation rather than informing.

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?

Incorrect for five parameters including a nested recipients array and a Tasks-extension flag. With no output schema and a mutation that reassigns ownership, the description should describe what the caller gets back and how await_answer changes the invocation shape; neither is covered.

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 60%, so the schema already documents id, release, and most recipient sub-fields. The description explains the consequence of release=true (duty drops to view), which is real added meaning, but it says nothing about the recipients targeting rules or the await_answer flag that governs whether the call returns a task or an id immediately.

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 ('Forward a handoff') plus the effect of reassigning and inviting new recipients, which distinguishes it from send_handoff/share_handoff by implication. It never names a sibling explicitly, so an agent must infer which of the nine siblings this replaces.

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

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

There is no statement of when to forward versus send_handoff, share_handoff, or wait_for_handoff. The only conditional given ('Set release to false to keep that duty') is a parameter behavior, not a task-selection guideline.

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 read-only, idempotent, non-destructive, so the description correctly spends its words elsewhere: it discloses that pending is a success state and not an error (a genuine pitfall), that payload format depends on handoff type, and that the call does not mutate the handoff. Missing only failure behavior for an unknown or malformed id.

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

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

Four short front-loaded sentences, each carrying distinct information: the primary action, the format variants, the pending edge case, and the non-mutating guarantee. Nothing is repeated from the annotations 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?

With no output schema, the description takes on the burden of describing returns and does so adequately — named payload shapes plus the pending state. Safety is covered by annotations and the unaffected-by-call note closes the mutation question.

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 single id parameter is fully documented as 'Handoff id, hnd_...'. The description adds only that the id scopes to one handoff on this account, so baseline 3 is appropriate.

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

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

States a specific verb (read) and resource (the completed answer for one handoff), and further specifies the return shape per handoff type: PDF paths plus recognized handwriting, or JSON answers for HTML/HUI. An agent can tell this apart from get_handoff_status without opening a 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 context is implied rather than stated: you call this when you want the submitted answer, and the pending note tells you what happens before submission. It never names get_handoff_status or wait_for_handoff as the alternative, so the agent must infer the routing from sibling names alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful error behavior by stating that another account's id is not found, though "This does not change the handoff" largely repeats the non-destructive 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 short and front-loads the primary purpose and return fields. The final sentence is slightly redundant with the readOnly/destructive annotations, but overall the structure is efficient.

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 read tool with full schema coverage and annotations covering safety, the description is complete enough: it names the returned fields, status values, account scoping, and not-found behavior. No output schema is needed given the field enumeration.

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 id parameter is already documented as a handoff id in hnd_... format. The description still adds semantic value by clarifying that the id is scoped to this account and that foreign-account ids will not be found.

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 uses a specific verb and resource: "Read one handoff on this account." It then names the exact fields returned (type, title, status, source, file paths) and the possible status values, making the tool clearly distinguishable from sibling write/share/delegate handoff tools.

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 this is the tool for reading a single handoff, but it does not explicitly route the agent against alternatives such as get_handoff_result or wait_for_handoff. The account-scoping note is useful context, but there is no direct when-to-use versus when-not-to-use guidance.

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

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

Annotations already declare destructive, openWorld, and non-idempotent, but the description reinforces these with concrete consequences: 'cannot be silently undone' and 'sending again creates a second handoff'. It also discloses the async nature ('does not wait'), which is operationally critical given the await_answer flag. Does not mention recipient acceptance or permission requirements for the send.

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 artifact types, then operational warnings. Five short sentences, each carrying information; the PDF outcome and the undo warning both earn their place. Slightly scattered — the source hint could be grouped with other parameter 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?

For a 17-parameter, nested, mutation tool with no output schema, the description covers the what and the key pitfalls but omits the recipient acceptance flow, routing modes, and how await_answer interacts with the async default. Those are documented in the schema, so the agent can recover, but the description alone is not 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 65%, so the schema does much of the work. The description adds value only for the source parameter ('so the device can show which session sent it'), which explains intent beyond the schema's 'Optional session context...' note. Key params like recipients, routing, fields, and await_answer are left entirely to 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 ('Create') and enumerates the exact artifact types (worksheet, form, approval, review, sketch), plus the round-trip outcome ('You get a filled PDF later'). It does not name the sibling tools (send_html_handoff, send_ui_handoff) that handle the other types, so a sibling distinction must be inferred from the enum.

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 does not wait' and 'sending again creates a second handoff' clearly steer the agent away from using this for synchronous waits or retries, implicitly pointing at wait_for_handoff. The 'Pass source so...' line gives a positive usage instruction. Missing an explicit pointer to send_html_handoff/send_ui_handoff for tap-and-type or HUI documents.

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?

Goes beyond the annotations with concrete behavior: scripts/iframes/handlers are stripped, the send 'cannot be silently undone', resending creates a duplicate, and 'An agent key does not receive answer_url'. The last point is genuinely non-obvious output behavior that an agent needs. It stops short of describing delivery timing or recipient permission 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?

Eight short front-loaded sentences, with the purpose first and the destructive/duplicate warning placed after the construction rule. The field-type enumeration is the one sentence that duplicates structured data and could be cut.

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 13-parameter, nested-object, no-output-schema tool, the description covers the answer format (JSON answers keyed by field id), the sanitization guarantee, and the destructive/duplicate semantics. Routing modes and the await_answer/Tasks behavior are covered only by schema descriptions, so it is not fully self-contained.

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 69%, and the description adds one real constraint not in the schema: that html, fields, or both must be supplied even though neither is required. The enumeration of field types (text, choice, checkbox, rating, approval, file) merely restates the schema enum and earns little.

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

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

States a specific verb+resource ('Create one HTML handoff') plus the answering mode (tap or type) and the return form ('JSON answers, not handwriting'), which meaningfully separates it from the handwriting/UI variants. It never names send_handoff or send_ui_handoff, so the sibling differentiation is left implicit rather than explicit.

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?

'Pass html, fields, or both' gives the construction rule, and 'Sending again creates a second handoff' warns about repeat calls. But nothing says when to pick this over send_handoff or send_ui_handoff, which is the main routing decision an agent faces among these siblings.

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 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.

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.

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.

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.

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.

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.

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

Goes well beyond the annotations by clarifying that the invite cannot be silently undone, that it does not delete the handoff or remove the owner's duty to answer, that recipients must accept before reading pages, and that repeated calls send another invite. This adds meaningful nuance around the destructive and non-idempotent hints, helping the agent understand the real consequences of the mutation.

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-loads the core action and then adds behavioral context in short, clear sentences. A few sentences are slightly repetitive (the non-undoable and repeat-invite points overlap), but nearly every sentence contributes useful information with no significant waste.

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

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

For a mutation tool with annotations covering destructive, non-idempotent, and open-world behavior, the description supplies the key missing context: recipient acceptance, irreversibility, non-deletion semantics, and repeat-call behavior. It does not cover invite expiry, revocation, or what happens when a recipient already has access, but those are secondary for an invite operation, and the schema covers the permission parameter.

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

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

Schema coverage is 50%, so the schema already documents recipient target fields and the permission enum with its meaning. The description adds a useful summary of the allowed recipient types, but does not explain the permission field, defaults, or edge cases beyond what the schema already provides. Baseline 3 is appropriate because the schema carries most of the parameter semantics.

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: invite people to a handoff you own. It is clearly an invite/grant operation, but it does not explicitly differentiate itself from sibling tools like delegate_handoff or send_handoff. An agent can still tell what this tool does, though it must infer the boundary from the name and description 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?

Provides an implied precondition ('a handoff you own') and notes that repeat calls send another invite, which helps avoid accidental duplicate invites. However, it offers no explicit when-to-use versus when-not-to-use guidance and never names an alternative sibling such as delegate_handoff or send_handoff. Adequate but with a clear gap in routing guidance.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive, closed-world), the description discloses the two side effects that are not performed (no handoff created, no person contacted) and, critically, explains that 'ok false is a successful tool call' so an agent will not treat validation failure as a transport error. It also documents the return shape and the meaning of diagnostics entries, which annotations alone 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?

Three short sentences, front-loaded with the verb and resource, then the side-effect exemption, then the return contract. No sentence is redundant and the most decision-relevant fact (ok false is still a successful call) is stated plainly.

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, and the description compensates by naming the four return keys and explaining how to interpret diagnostics for correction. Combined with the no-side-effect guarantee on a nested-object input, an agent has everything needed to call this correctly and to reason about the result.

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

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

Schema description coverage is 100% and both parameters are already documented, including the top-level-fields shortcut for 'ui' and the error-to-warning behavior of 'lenient'. The description adds no parameter-level meaning beyond that, so this sits at the baseline for fully documented schemas.

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 ('Check a HUI 0.1 document') and implicitly separates it from the handoff-creation siblings by saying it does so 'without creating a handoff and without contacting the person'. The verb 'check' is slightly softer than 'validate' and the title ('Check a form') uses different vocabulary than the description ('HUI 0.1 document'), which costs a bit of precision, but the operation is still 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 'without creating a handoff and without contacting the person' clause gives a clear dry-run framing that tells an agent to use this before the send_* handoff tools. It stops short of naming a sibling or stating an explicit 'use this instead of X when Y' routing rule, so the agent must infer the workflow placement.

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 readOnly and idempotent annotations, the description explains the waiting behavior, the 25-second wait cap, the meaning of a pending return, and that pending is success. It also explicitly states that the call does not change the handoff, which is valuable 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 short and front-loaded with the core wait behavior. Every sentence adds useful operational detail: return semantics, pending success, retry behavior, non-mutation, and when to prefer the Tasks extension.

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 read-only tool with no output schema, the description covers the important return semantics and retry behavior. It also explains when to use it versus the Tasks-based approach, leaving no major operational gap.

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

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

Schema description coverage is 100%, so the id and timeout_ms parameters are already documented in the input schema. The description mentions the 25-second wait window but adds little parameter-specific guidance beyond the schema's range and default for timeout_ms.

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: wait up to 25 seconds for one handoff on this account. It clarifies that it returns the completed result or a pending status, which distinguishes it from simple status/result retrieval. However, it does not explicitly name get_handoff_result or get_handoff_status as alternatives, so sibling differentiation is implied rather than fully explicit.

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 an explicit usage condition: use it when the client does not declare the MCP Tasks extension. It also names the alternative behavior with Tasks: pass await_answer on send instead, and explains that repeated calls are needed to keep waiting.

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