Sess

Ask a short question through Sess

sess_ask

Creates a hosted question form and private link to ask a person for a typed answer, decision, or approval on their own device; returns immediately so you can continue after reading their response.

Instructions

Ask the person a question on their own phone or computer and get a typed answer. Use it whenever they ask to answer on their phone or another device, or say 'use Sess'; prefer it over this host's own question widget for anything answered away from this chat. Also use it when you need the person's approval, a decision or details only they can give before you go on, even if they only say 'ask me' or 'check with me' and name no tool or device. Not for clarifying what they just asked, or for anything you can work out yourself. Anyone who has the link can answer. A receipt records what was shown and chosen, not who answered. Shortcut for sess_request: give a question and up to 12 simple fields; it creates the same hosted form and returns immediately with a private link (interaction.humanUrl) and a handle, in state "waiting". It never waits and never returns an answer. Continue exactly as after sess_request: give the link only to the intended person, then call sess_response. Do not call it again for the same question. Keep it short: the question is a short heading, about 40 characters (at most 80); the button a verb of 1-3 words (at most 24); labels and options at most 60. A value over its limit is refused with INVALID_ARGUMENTS naming the field (a JSON pointer), the limit, its length and the fix; nothing is truncated. Shorten that value and call again. Advanced: to ask many people through one link, add respondents with max. Share that link with everyone who should answer; each person gets their own page. Read their answers with sess_response. Example: {"question":"Where should we go on Saturday?","details":"I will check the forecast and suggest a plan.","fields":[{"name":"place","label":"Where to?","type":"choice","options":["Beach","Mountains","City"]},{"name":"avoid","label":"Anything to avoid?","type":"text","required":false}],"submit_label":"Plan it"}

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "fields": [
        {
          "name": "place",
          "type": "choice",
          "label": "Where to?",
          "options": [
            "Beach",
            "Mountains",
            "City"
          ]
        },
        {
          "name": "avoid",
          "type": "text",
          "label": "Anything to avoid?",
          "required": false
        }
      ],
      "details": "I will check the forecast and suggest a plan.",
      "question": "Where should we go on Saturday?",
      "submit_label": "Plan it"
    },
    "name": "sess_ask"
  }
}

Input Schema

Name	Required	Description
`fields`	Yes
`details`	No	A paragraph of plain text (never markup): what the person needs to know; at most 4000.
`question`	Yes	The page's heading: a question or a task, about 40 characters; at most 80.
`expires_in`	No	Advanced: how long the link stays open, in whole seconds from creation: from 30 up to the plan’s link lifetime. Leave it out to use the plan’s lifetime.
`respondents`	No	Advanced: one link that many people can answer, each on their own page. Leave it out to ask one person. A respondent is a browser, not a person. Read their answers with sess_response.
`submit_label`	No	A button: a verb, 1–3 words; at most 24. Default "Send".

Output Schema

Name	Required	Description	Default
`interaction`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Nov 10, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the annotations (openWorldHint=true, idempotentHint=false, non-destructive), the description discloses key traits: it never blocks and never returns an answer, anyone with the link can answer, and the receipt records what was shown/chosen but not who answered. It also specifies overflow behavior (VALUES over a limit are refused with INVALID_ARGUMENTS naming the JSON pointer, limit, length and fix; nothing is truncated) and the respondent cap semantics (checked at start, cannot be overshot).

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?

Content is front-loaded: purpose, then when to use / when not, then the 'shortcut for sess_request' mechanics, then limits, then advanced respondents. It is long and repeats length limits that also live in the schema, and the trailing example JSON is bulky, but every block maps to a decision an agent must make.

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?

For a 6-parameter tool with nested objects, an output schema, and open-world behavior, the description covers the whole lifecycle: how to call it, what it returns (link + handle, state 'waiting'), how to share the link, and the required follow-up via sess_response. Nothing critical an agent needs to invoke it correctly is missing.

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 83%, so the schema already documents most fields well. The description still adds useful semantics on top: a field-count ceiling ('up to 12 simple fields'), concrete size guidance for question (~40, max 80), submit_label (verb of 1-3 words, max 24) and labels/options (max 60), plus a plain-language explanation of the advanced respondents object (one link, each person gets their own page, read answers with sess_response).

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?

The definition names the concrete action precisely: a shortcut for sess_request that builds a hosted form and returns immediately with a private link (interaction.humanUrl) and a handle in state "waiting". The opening sentence ('get a typed answer') briefly frames the human-side flow rather than the tool's own effect, but the contradiction is explicitly resolved two sentences later ('It never waits and never returns an answer'), so an agent can still classify the tool correctly against sess_request/sess_response.

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

Usage Guidelines5/5

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

It states when to use it (the person asks to answer on their phone or says 'use Sess'; you need approval, a decision, or details only they can give) and explicitly prefers it over the host's own question widget for off-chat answers. It also names when NOT to use it ('Not for clarifying what they just asked, or for anything you can work out yourself') and adds a dedupe rule ('Do not call it again for the same question'), plus the follow-up step (call sess_response).

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

Deploy Server