← Research library

Tool design for agents: fewer, clearer, safer actions

AI-assisted research. This note was prepared with the assistance of AI tools. It may contain errors and is not professional advice. See our Legal Disclosures.

Marketing agents are gaining access to real systems: the CRM, the email platform, ad accounts, the content management system. Each connection is exposed to the agent as a tool, and the shape of those tools decides much of what the agent does well and badly.

When an agent misbehaves, the cause is often a tool rather than the model. The agent called a search tool when it should have looked up a record, or used a broad update when a narrow one would have done. Sometimes it misread an unclear description and passed the wrong parameter. Tools are the agent's hands, and poorly designed hands make clumsy work.

This post sets out the principles we follow when designing tools for marketing agents, a worked example, and how to test tools before an agent depends on them.

Fewer tools with narrow scopes

Every additional tool is another choice the agent must make correctly. A focused set leads to better decisions than a long menu. If two tools overlap, merge them or remove one. If a tool does many things depending on its parameters, consider splitting it.

Scope matters as much as count. Prefer specific actions over general ones, as these pairs show:

  • Contacts: "get contact by email" instead of "query database."
  • Email: "create draft email in campaign" instead of "send email."
  • Budgets: "adjust daily budget by up to 10%" instead of "update campaign settings."

Narrow tools are easier to permit, easier to log, and much harder to misuse. A narrow tool also makes permissions meaningful. You can grant an agent the right to draft without granting the right to send. That is the separation described in roles and permissions for a mixed human and agent team.

There is a tension here. Narrowing every action can multiply the tool count, which works against the first principle. We resolve it by asking which actions the agent's role needs, then building one narrow tool for each, and nothing for actions outside the role.

Descriptions written for the agent

Agents choose tools based on names and descriptions, so the description is part of the interface. A good description covers four things:

  • Purpose: what the tool does, in one sentence.
  • Fit: when to use it, and when to use something else.
  • Parameters: what each one means, with an example value.
  • Returns: what the tool gives back, including on failure.

The "when not to use it" line is the one most often missing. If you have both a search tool and a lookup tool, each description should name the other and say when it is the better choice. Vague descriptions are one of the most common causes of wrong tool choices we see in agent reviews.

Protocols that standardize how agents discover tools, such as Model Context Protocol, make descriptions more important, not less. The agent may see tools from several systems at once, and the description is all it has to tell them apart. See MCP for marketers for more on what these protocols change.

Safe defaults

Defaults decide what happens when nobody thought about a case. For marketing tools we recommend four:

  • Read-only first: grant write access only where the task requires it.
  • Drafts before publication: have tools create drafts that a person or a later step approves.
  • Small limits: cap any value the tool can change, such as budget, audience size, or send volume.
  • Confirmation for irreversible actions: require an explicit second step for anything that cannot be undone.

These limits should be enforced inside the tool. A rule in the prompt that says "never raise a budget by more than 10%" is a request. A tool that rejects larger changes is a control.

Helpful errors and usable results

When a tool fails, the error message becomes input to the agent. "Error 400" gives it nothing to work with. "No contact found with that email; check spelling or search by company name" lets it recover sensibly. Good errors reduce retries, loops, and guesses.

Structure the errors as well as wording them clearly. A category such as retryable, invalid input, or conflict tells the agent whether to try again, fix something, or stop. Our post on tool errors as marketing errors covers why this matters for customer-facing actions.

Successful results need the same care. Return only what the agent needs, in a consistent structure. Huge raw responses waste context and invite the agent to latch onto irrelevant details; we discuss this in context windows are a budget.

A worked example

Consider a hypothetical paid media agent that starts with one tool: "update campaign," which accepts any field and any value. In testing, the agent sometimes changes targeting when asked to change budget, because both are fields on the same object.

A redesign replaces it with three tools. "Get campaign summary" returns the name, status, daily budget, and spend to date, and nothing else. "Propose budget change" accepts a campaign ID and a new daily budget, rejects changes above 10%, and creates a pending change instead of applying it. "Get pending changes" lets the agent check what is already waiting for approval.

The agent can no longer touch targeting, because no tool exposes it. It cannot make a large budget change, because the tool refuses. Every change it proposes is visible and reversible before it takes effect.

Testing tools

Test each tool directly before giving it to an agent, then test how the agent uses it. We use a short sequence:

  1. Call the tool with realistic inputs and confirm the results are correct and compact.
  2. Call it with bad inputs and confirm the errors explain how to recover.
  3. Give the agent a set of tasks and log which tools it chooses for each.
  4. Review wrong choices and trace each one to a name, description, or scope problem.
  5. Fix the tool, then rerun the same tasks.

If the agent repeatedly misuses a tool, the fix is usually in the tool's design or description, not in more instructions. Keep the logs from step three; run histories make these patterns visible over time, as described in observability for marketing agents.

The question we are studying next is how tool sets should change as agents earn more autonomy. Adding write access one tool at a time is easy to reason about. Knowing when the evidence supports the next tool is harder, and we are working on criteria that make that decision repeatable.

How to apply this: list every tool your agent can call. For each one, check whether its scope is as narrow as the role allows, whether its description says when not to use it, whether limits are enforced in the tool, and whether its errors explain how to recover.

Related research

Put this research to work

Marketix turns these patterns into software: agents, automated workflows, and a hub that keeps people in control. Sign up for early access.