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.
How to fix it
Add the lifetime, for example "Sessions expire after 30 minutes without a call."
- Find tools that return a handle used by later calls (session_id, cart_id, context_id).
- Add the retention policy to the creating tool’s description.
- Return a clear error when an expired handle is used.
TypeScript SDK
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
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.
Related checks
- Description says when to use the tool
- Create and send tools take a retry key
- No tool-level execution field from 2025-11-25
- All checks in MCP tool descriptions
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