Designing MCP tools agents cannot misuse

MCP makes it easy to expose capabilities to agents. It also makes it easy to expose too much. A tool that accepts arbitrary SQL, unbounded dates, or silent side effects will be misused the first time a prompt is ambiguous. datahashi treats MCP tool design as safety engineering: small verbs, strict schemas, fail-closed validation.

Start from verbs, not tables

Agents need verbs that map to intent: discover, understand, query. That is why datahashi centers on list_catalog, describe_metric, and run_semantic_query. Each verb has one job. Discovery does not execute. Description does not return large result sets. Execution does not invent definitions.

If you expose “run anything” as a single tool, every prompt becomes a jailbreak contest. Split the workflow so the agent must learn the contract before it can spend compute.

Schemas that reject improvisation

Safe MCP tools use explicit parameters: metric name, time range, dimensions, filters, limit. Optional fields stay optional only when the metric definition allows it. Required grain and required dimensions come from describe_metric and are enforced again inside run_semantic_query.

Reject unknown fields. Reject empty time windows. Reject dimensions that are not on the metric. Agents recover from clear validation errors. They do not recover cleanly from silent coercion or “best effort” SQL rewriting that hides what actually ran.

Defaults as soft rails

Defaults are part of the API. A missing date range should not mean “all history.” A missing limit should not mean “warehouse max.” datahashi applies conservative defaults and documents them in tool descriptions so agents (and humans) see the rails before they hit hard errors.

Hard limits still matter. Caps on range length, result size, and concurrency protect shared warehouses when many agents run at once. Soft rails guide; hard caps stop.

No side-effect tools in the metrics path

Metrics MCP should be read-only. No write_metric, no mutate_definition, no “run this dbt model” hiding next to query tools. Side effects belong in separate servers with separate auth and human approval. Mixing them trains agents to treat production as a playground.

Read-only also simplifies incident response. If something looks wrong in the numbers, you audit query shapes and metric definitions, not a trail of accidental mutations.

Error messages that teach the next call

A good failure tells the agent what to fix: “date range exceeds maximum of 90 days,” “dimension channel is not allowed for metric activation_rate,” “call describe_metric before run_semantic_query for required filters.” Bad failures say “internal error” and invite retry storms.

Include enough structure for the agent to branch: retry with narrower range, pick another metric, or stop and ask the user. That reduces thrashing and keeps traces readable for humans.

Testing misuse, not just happy paths

Design reviews should include hostile prompts: “pull all revenue forever,” “join every table,” “ignore the catalog and query the base schema.” Confirm the tools refuse. Add regression tests for schema changes so a loosened parameter does not ship unnoticed.

Also test tool descriptions themselves. Overly vague descriptions invite creative misuse. Overly long ones get truncated in agent context. Aim for precise, short contracts.

Keep the surface stable

Agents memorize tool patterns. Renaming parameters weekly breaks workflows and encourages fragile prompt hacks. Version carefully. Prefer additive changes. When you must break a contract, leave a deprecation window and make the old shape fail with a migration hint.

Safe MCP tools are not the ones with the most power. They are the ones where the powerful path is impossible and the useful path is obvious. Design for that, and agents become reliable consumers of your semantic layer instead of unpredictable clients of your warehouse.