← ./articles

MCP Tool Schema Not Updating? Verify tools/list Directly

mcpjson-rpcai-agentdebuggingapi-testing

You add a tool, rename an argument, or change inputSchema. The MCP server restarts cleanly, but the client still shows the old definition—or says the new tool does not exist.

That does not prove the server build is wrong. MCP clients discover tools through tools/list, and a client may keep the discovered definitions for the lifetime of a connection or conversation. Test the server response directly before repeatedly rebuilding or restarting components.

Recognize a stale schema instead of a broken connection

A schema-refresh problem usually has this shape:

  • the client can still call older tools from the same server
  • only a new tool or recently changed argument is missing
  • the server process starts without a transport error
  • restarting the server alone does not change the client-visible definition

If every tool disappeared, start with connection and configuration checks instead. See Claude Code MCP Server Not Loading?.

Ask the server for tools/list without the AI client

For a Streamable HTTP server, send a JSON-RPC request to its MCP endpoint. Replace the example URL with your local test endpoint:

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Some servers require the MCP initialization handshake and a session header before accepting tools/list. In that case, use MCP Inspector or a small SDK client rather than removing the server's session checks.

Inspect the returned tool entry, especially:

  • name
  • description
  • inputSchema.properties
  • inputSchema.required
  • outputSchema, when the tool declares one

The direct response is the server truth. If it is old, the problem is on the server side: wrong executable, stale build output, wrong endpoint, or registration code that never ran.

Call the changed tool directly

A correct list response proves registration, not runtime behavior. Call the tool with the new argument shape:

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_status","arguments":{"detail":"summary"}}}'

Use a harmless read-only tool for this check when possible. A valid schema can still point to a handler that throws, reads the wrong field, or returns an invalid result.

Decide which layer is stale

Use the two direct requests as a decision table:

  1. tools/list is old: verify the running PID, executable path, build timestamp, endpoint, and registration code.
  2. tools/list is new but tools/call fails: fix the handler or its result validation.
  3. Both direct calls work but the AI client is old: reconnect or restart the client so it discovers tools again.
  4. The server advertises listChanged: verify that it emits notifications/tools/list_changed and that the client supports refreshing from it.

Do not assume every client reacts to change notifications in the same way. A reconnect remains the portable final check.

Verify the complete refresh path

Record evidence from both sides:

Direct tools/list: new argument present
Direct tools/call: result returned
Client reconnect: new argument visible
Client tool call: result returned

This sequence prevents two common mistakes: changing working server code to fix a client cache, and restarting a client before proving that the server actually exposes the new schema.

References

Summary

When an MCP tool change is invisible, query tools/list first, then exercise the tool with tools/call. If the direct responses are correct, refresh the client. If they are not, investigate the running server artifact and handler instead of blaming the cache.