Design a small MCP tool schema that can be tested

A tool named run_query with an unrestricted string hides meaning and expands risk. A narrow get_metric(metric, start, end) contract is easier to authorize, validate and evaluate.

Execute the schema boundary

The MCP contract lab validates two authored inputs.

from mcp_cases import tool_schema_case

result = tool_schema_case()
assert result["valid_passes"] is True
assert result["invalid_passes"] is False
assert result["external_call"] is False
assert result["schema"]["metric_enum"] == ["orders", "revenue"]

An approved metric and ISO range pass. Unknown profit, today and an extra debug field fail.

Design for one responsibility

Use a clear verb/noun name and a description of what the tool does and does not do. Specify required fields, enums, formats, limits and additional-property policy. Prefer stable IDs over free text. Separate read and write tools so permissions remain clear.

Add domain validation outside the schema: start before end, maximum range, tenant scope and source readiness. Return a typed result with unit, source version and structured errors.

Build table-driven tests

Cover valid, missing, extra, wrong type, boundary length, invalid date, unauthorized ID and injected content. Confirm invalid calls never reach the adapter. Version breaking changes and keep callers from treating unknown outputs as success.

The Generative & Agentic AI course uses small schemas as the basis for MCP contract and agent argument tests.

Exercise

Replace one broad tool with two narrow contracts. Write 20 table-driven cases and demonstrate that descriptions contain no secrets or hidden authorization assumptions.

Continue learning

This article is part of the MCP and integration contracts sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in MCP tools, resources and prompts: assign the right responsibility.
• Continue with Build a read-only business-metrics tool contract.

Reference: MCP tools specification.