Limits, defaults, and agent-safe query shapes

Agents that query metrics tend to ask for everything. Without guardrails they scan wide date ranges, pull every dimension, and treat the warehouse like a scratchpad. That is expensive and it produces answers nobody can trust. datahashi ships agent-safe defaults so the first query an agent runs is already bounded, typed, and reviewable.

Why defaults beat policy essays

You can document “do not scan years of data” forever. Agents still invent wide windows when a prompt is vague. Safer practice is to encode limits in the tools themselves. When run_semantic_query rejects an unbounded range or a missing grain, the agent has to narrow the request. That feedback loop is faster than hoping a system prompt holds under pressure.

datahashi also keeps the tool surface small. Agents discover what exists with list_catalog, inspect a metric with describe_metric, then execute with run_semantic_query. Three steps. No free-form SQL path for agents. The shape of the call is the policy.

Limits that matter in practice

Date range caps are the first line of defense. A default lookback (for example thirty or ninety days) stops accidental full-history scans. Teams can raise the cap per environment, but the default stays tight. Row and result-size limits sit next to that. Agents get a sample they can reason over, not a dump that floods context windows.

Grain and filter requirements close another gap. If a metric is defined at daily grain for a product or region, the agent must declare that grain and any required dimensions. describe_metric returns those constraints before run_semantic_query runs, so the agent can assemble a valid call instead of guessing.

Timeouts and concurrency limits round out the set. One runaway agent should not starve interactive users. datahashi applies these at the semantic layer so warehouse roles stay simple: read-only access plus tool-enforced bounds.

Query shapes agents should prefer

Safe shapes are boring on purpose:

• Named metric plus explicit time window
• A small set of dimensions the metric already allows
• Filters that map to governed attributes, not ad hoc expressions
• One question per call, then compose results in the agent

Avoid shapes that invite misuse: open-ended “give me everything about revenue,” multi-year windows with no business need, or stacking every available dimension “just in case.” Those patterns burn credits and invent false precision.

How discovery keeps agents honest

list_catalog answers “what can I ask?” without exposing raw tables. describe_metric answers “how is this defined, what filters apply, what grain is legal?” Only then should run_semantic_query run. That order turns exploration into a checklist instead of a fishing expedition.

When an agent skips describe and jumps straight to run, the tool still validates. Invalid grain, unknown filters, and oversize ranges fail closed with a clear error. The agent can recover. Humans reviewing traces can see the failure and fix prompts or permissions.

What teams should configure first

Start with conservative date defaults and result caps. Wire list_catalog and describe_metric into every agent path before enabling run_semantic_query in production. Review a week of agent traces for wide ranges and repeated invalid calls. Tighten where agents keep probing the edges.

Agent-safe query shapes are not about making agents less capable. They are about making the capable path the only easy path. Limits and defaults do that work so your semantic layer stays trustworthy when the caller is a model, not a person.