Sess

Ask a person through Sess

sess_request

Create a hosted form to request a person's approval, decision, or missing details, returning a private link and handle for collecting their answer.

Instructions

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. It is the full form, with approve and reject buttons if you need them; sess_ask is shorter for a plain question. Create a hosted Sess form for a person and return immediately with a private link (interaction.humanUrl) and a handle. Give the link only to the intended person in this private conversation; anyone holding it can answer. A receipt records what was shown and chosen, not who answered. Then call sess_response with the handle and revision. Do not call sess_request again for the same question. Keep it short: a title of about 40 characters (at most 80), button labels a verb of 1-3 words (at most 24), field labels at most 60, help one hint (at most 160). 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.

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": {
      "interaction": "<interaction>"
    },
    "name": "sess_request"
  }
}

Input Schema

Name	Required	Description	Default
`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.
`interaction`	Yes	A Sess form: a title, components shown in order and 1-5 buttons. Keep it short: a person reads it on a phone. 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.

Output Schema

Name	Required	Description	Default
`interaction`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Nov 10, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the annotations (which only mark it non-read-only, open-world, non-idempotent), the description discloses that it returns immediately with a private link and handle, that anyone holding the link can answer, that the receipt records what was shown and chosen but not who answered, and that the next step is sess_response with the handle and revision. It also tells the agent not to re-call for the same question, which is consistent with idempotentHint=false.

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?

It is front-loaded sensibly: when to use, when not, what it does, workflow, then constraints. The constraint sentence largely restates schema limits and adds length, but it earns most of its place by explaining the refusal behavior; overall it is dense but not padded.

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 complex tool with a deeply nested schema and an existing output schema, the description supplies everything an agent needs to call it correctly: purpose, exclusions, return values (humanUrl and handle), the follow-up call (sess_response), and error-handling behavior, without redundantly explaining output fields.

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% and the nested schema already documents most limits, so this is above the baseline. The description adds operational meaning by recapping the practical limits (title ~40/max 80, button labels 1-3 words/max 24, field labels 60, help 160) and, importantly, describing the INVALID_ARGUMENTS error shape naming the JSON pointer, limit, length and fix with no truncation, which is not evident from the schema alone.

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?

The description states a specific action (create a hosted Sess form for a person) and its return (a private link at interaction.humanUrl plus a handle), and explicitly distinguishes it from the sibling sess_ask ('shorter for a plain question'). An agent can choose between them without opening either schema.

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 gives explicit when-to-use criteria ('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'), an explicit when-not ('not for clarifying what they just asked, or anything you can work out yourself'), and names the alternative tool for the simpler case.

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

Deploy Server