Skip to content
IsoKron

Tools that create state say how long it lasts

A tool that creates a session, cart, context or other handle should say in its description how long the handle lasts, because handles outlive any single connection and the model decides whether to create one.

Check design-handle-lifetime · Schema and description quality · default severity: advice · rubric 2.1.0

What fails

The tool creates a session, cart, context or similar handle, but its description does not say when it expires.

The rule

Because handles outlive any single connection, the server's retention policy should be stated in the creation tool's description (e.g., "baskets expire after 24 hours of inactivity") so the model can see it when deciding to create state.

Source: MCP specification 2026-07-28: Tools

How to fix it

Add the lifetime, for example "Sessions expire after 30 minutes without a call."

  1. Find tools that return a handle used by later calls (session_id, cart_id, context_id).
  2. Add the retention policy to the creating tool’s description.
  3. Return a clear error when an expired handle is used.

TypeScript SDK

TypeScript
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';

const server = new McpServer({ name: 'issues', version: '1.0.0' });

server.registerTool(
  'create_cart',
  {
    title: 'Create cart',
    description: 'Create an empty shopping cart and return its cart_id. Carts expire after 24 hours without changes. Use when the user starts a new order.',
    inputSchema: z.strictObject({
      store_id: z.string().describe('Store ID, for example ST-3'),
    }),
    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
  },
  async ({ store_id }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);

Python SDK

Python
from typing import Annotated

from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations

server = MCPServer("issues")

@server.tool(
    title="Create cart",
    annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=False),
)
def create_cart(
    store_id: Annotated[str, Field(description="Store ID, for example ST-3")],
) -> str:
    """Create an empty shopping cart and return its cart_id. Carts expire after 24 hours without changes. Use when the user starts a new order."""
    return "Done"

Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.

Questions

Why put the lifetime in the description?

The model reads it when deciding to create state, and can tell the user or reuse a handle instead of creating another.

What if handles never expire?

Say that too ("carts are kept until deleted"), and offer a delete tool.

How this check is graded

It counts toward: Schema and description quality. See the rubric.

Last verified against MCP specification 2026-07-28: Tools on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.

Check your tool list: paste your tools/list, nothing is sent anywhere