Sess

Read the person’s Sess answer

sess_response

Read-onlyIdempotent

Waits for a verified answer to a specific form revision, returning answered, waiting, or expired so agents can continue or ask the person to resume.

Instructions

Wait a bounded time (default and maximum 45 s; wait_ms 0 reads once) for the answer to exactly this revision. state "answered" means the answer passed full Sess receipt verification. state "expired" means the link closed with no answer: it is final; create a new form if you still need one. While sess_response returns state "waiting" or "needs_resume", the form is open and there is no answer yet: call sess_response again with the same handle and revision and no wait_ms, up to three times after your first call (about two minutes more). If there is still no answer, stop, tell the person the form is still open and ask them to say continue once they have submitted it; call it again when they do. Do not poll beyond that, and do not ask the same question again. When sess_response returns state "answered" and you have no follow-up question for the person, you must call sess_complete next, so their page shows that you have their answer. Call sess_publish instead only to show them a follow-up. For a handle from sess_ask with respondents (an Ask), it reads once, without waiting, and returns interaction.ask: whether it is open, the counts and each person’s verified answer so far. Read it again later for more answers; state "closed" means no more answers will come. Do not call sess_publish or sess_complete for an Ask: each person’s page completes on its own.

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": {
      "handle": "<handle>",
      "revision": "<revision>"
    },
    "name": "sess_response"
  }
}

Input Schema

Name	Required	Description
`handle`	Yes	Opaque handle from sess_request.
`wait_ms`	No
`revision`	Yes

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?

Annotations already cover readOnly/idempotent/non-destructive, but the description adds a great deal: default and maximum wait of 45 s, wait_ms 0 as a single read, the meaning of each state (answered, expired, waiting, needs_resume, closed), the finality of "expired", and the polling ceiling. That is behavior an agent could not infer from the structured fields.

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?

Front-loaded with the wait semantics and state meanings, and nearly every sentence carries procedural information. It is dense and runs long with some repetition around polling limits, but the length is largely justified by the multi-branch protocol it encodes.

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 polling read tool with an output schema, this covers timing, state semantics, retry budget, escalation to the person, and the required next tool. The only minor gap is that "needs_resume" is not defined, but the surrounding instructions still tell the agent what to do.

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 only 33% (only handle is documented), so the description must compensate, and it largely does: it explains wait_ms default/max and the special 0 value, and defines revision as the exact revision being answered. It does not restate the handle's pattern, but that is covered in the schema.

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?

States a specific verb and resource: waits a bounded time for the answer to exactly the given handle and revision, and returns a state. It also distinguishes itself from siblings by naming sess_complete, sess_publish, sess_ask, and by describing the Ask variant's different read-once behavior.

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?

Explicit when-to-use rules: poll with the same handle and revision and no wait_ms up to three times after the first call, then stop and ask the person to say continue. It names the alternatives (sess_complete vs sess_publish) and the condition that selects each, and explicitly says not to call sess_publish/sess_complete for an Ask.

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

Deploy Server