# 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. Last verified against MCP specification 2026-07-28: Tools on 2026-11-18.

## 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](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#stateful-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

```ts
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"
```

## 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.

## Related checks

- [Description says when to use the tool](https://isokron.ai/mcp-check/checks/design-use-when)
- [Create and send tools take a retry key](https://isokron.ai/mcp-check/checks/surface-retry-key)
- [No tool-level execution field from 2025-11-25](https://isokron.ai/mcp-check/checks/spec-execution-legacy)
- [MCP tool descriptions](https://isokron.ai/mcp-check/checks/descriptions)

Counts toward: Schema and description quality.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
