Skip to main content
Glama

Create a hosted interview

talkform.create_handoff
Idempotent

Stores a validated voice interview or text interview and returns a private respondent link plus shareText. config.fields[].promptTitle supplies each question; config.branding.fromName and branding.purpose identify the originating product. Omitted mode selects voice; text mode is available. Requires a project API key or scoped OAuth. Optional projectId selects an owned account project; required when the account has several projects. Matching idempotency keys replay the existing handoff.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "config": "<config>",
      "idempotencyKey": "<idempotencyKey>"
    },
    "name": "talkform.create_handoff"
  }
}

Input Schema

NameRequiredDescriptionDefault
configYes
projectIdNo
idempotencyKeyYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / projectId
      Added value: +{
      +  "format": "uuid",
      +  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      +  "type": "string"
      +}
  2. Changed7 schema fields changed
    • removedInput schema / properties / config / additionalProperties
      Removed value: -false
    • removedInput schema / properties / config / properties / fields / items / additionalProperties
      Removed value: -false
    • removedInput schema / properties / config / properties / fields / items / properties / options / items / additionalProperties
      Removed value: -false
    • removedInput schema / properties / config / properties / fields / items / properties / validation / additionalProperties
      Removed value: -false
    • removedInput schema / properties / config / properties / output / additionalProperties
      Removed value: -false
    • removedInput schema / properties / config / properties / realtime / additionalProperties
      Removed value: -false
    • removedInput schema / properties / config / properties / theme / additionalProperties
      Removed value: -false
  3. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Goes beyond the annotations by disclosing the auth requirement (project API key or scoped OAuth), the idempotent replay behavior (returns the existing handoff rather than creating a duplicate), and what the caller receives (private respondent link plus shareText). The annotations already cover readOnly=false, destructive=false, openWorld=true, so this is genuine added context rather than repetition.

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?

Four dense sentences, front-loaded with the core action and return values before moving to nested field meaning, defaults, and auth. Every sentence adds information; nothing is filler.

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 deep three-parameter create tool with no output schema, the description covers auth, return shape, idempotency, mode default, and project scoping — the items an agent most needs before calling. Gaps remain around webhook output configuration and the meaning of 'validated', but the essentials are present.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must carry the load. It explains the non-obvious nested semantics — config.fields[].promptTitle supplies question text and branding.fromName/purpose identify the originating product — plus the mode default, projectId scoping rule, and idempotencyKey replay. Large portions of the nested config (theme, output/webhookUrl, realtime, instructions, validation) remain unexplained.

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 — stores a validated voice/text interview and returns a private respondent link plus shareText — which distinguishes it from the read-oriented siblings like get_handoff and delete_handoff. It does not explicitly contrast with prepare_form or register_agent, but the create semantics are unambiguous.

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?

Provides conditional parameter guidance (omitted mode selects voice; projectId required when the account has several projects; matching idempotency keys replay an existing handoff). However, it never states when to choose this tool over alternatives such as prepare_form or get_template, so sibling routing is left to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.