You can predict most of how an agent will behave by reading its tool definitions and never seeing the prompt at all.

This is not a rhetorical flourish. Given a list of actions with their names, parameters, and return shapes, an experienced reviewer can usually say where the agent will hesitate, where it will overreach, and which action it will reach for when it should have declined. The prompt adjusts the margins.

Tool names are instructions

An action called run_update tells the model almost nothing about when to use it. It is a verb and a noun with no preconditions, so the model infers preconditions from context, which is another way of saying it guesses.

An action called update_opportunity_stage_after_confirmation tells it when, on what, and under what precondition. It does so in the one place the model always reads carefully, and it cannot be skimmed past the way a paragraph of instructions can.

Naming is not documentation here. It is control flow.

• Put the object in the name, so the model cannot apply it to the wrong one.

• Put the precondition in the name when one exists.

• Avoid generic verbs like process, handle, and manage. They mean nothing.

• Name for the caller's intent, not for the implementation underneath.

Return shapes decide whether hallucination is possible

A tool that returns a raw blob invites the model to interpret, and interpretation is where invention enters.

A tool that returns a typed object with an explicit status, a reason, and a small set of named fields leaves nothing to invent. When we see an agent making things up, the cause is usually a tool that returned something ambiguous and left the model to fill the gap. The model is not being creative. It is completing a pattern because nothing told it not to.

The most valuable field in any return shape is the one that says nothing was found. An empty array and a missing key look similar to a model and mean different things, and an explicit not_found status removes the ambiguity entirely.

• Always return a status, even on success.

• Distinguish empty from failed from not permitted.

• Return a reason string the agent can quote to the user.

• Keep the field count low. Every extra field is a chance to reason about the wrong one.

Granularity beats flexibility

Ten narrow tools beat one flexible tool with a mode parameter, every time.

The flexible version looks elegant to an engineer. It is one implementation, one test suite, one thing to maintain. To a model it is a decision tree with no signposting, and the mode parameter is exactly where the wrong choice gets made.

Narrow tools are easier to permission, because you can grant one and withhold another. They are easier to log, because the action name already tells you what was attempted. And they are easier to debug, because a failure is isolated to a named action rather than buried inside a branch of something generic.

The cost is more definitions to maintain. That cost is real and it is smaller than it looks, because narrow tools change less often.

Permissions belong in the tool

A guardrail expressed in the prompt is a suggestion. A guardrail expressed in the tool is a property.

If an action must not run without confirmation, the action should require a confirmation token and fail without it. If a user may not see a record, the tool should not return it, rather than the prompt instructing the model to be careful. Anything enforced by language can be talked around by other language.

This is also what makes the system testable. You can write a test that calls the action without the token and asserts it fails. You cannot write that test against a paragraph of instructions.

The short version

Spend the afternoon on the tool surface: names that state preconditions, return shapes with explicit statuses, narrow actions instead of flexible ones, and enforcement in code rather than in prose.

The prompt gets shorter on its own, and it stays short through the next model release, which is more than can be said for instructions written to compensate for a vague tool.