Skip to content
be-human.ai
← Back to the journal

Tools & integrations

Tool Schemas for Superintelligent Agents: Naming and Types That Work

Naming and typing rules for agent tool schemas: verb-first names, narrow argument types, enums and clear descriptions so models pick the right function.

Be Human typographic cover with the title: Tool Schemas for Superintelligent Agents: Naming and Types That Work
Conceptual illustration created with AI · Be Human

A tool schema tells a model what a function is called, what it does, and what arguments it accepts. Models pick the right tool and fill its arguments reliably when each tool has a verb-first name tied to one business action, a description that says when to use it and when not to, and narrow, typed parameters with explicit allowed values. Get those three things right before you add more tools.

Key takeaways

  • Name each tool after one business action with a verb and an object, such as list_open_orders or draft_email_reply, never a vague name like process or handle.
  • Give every argument a precise type, a short description, and an allowed range or enum, so the model cannot invent values your system will reject.
  • Split read, draft and write actions into separate tools, so permission boundaries live in the schema and not only in a prompt.
  • Test schemas with realistic requests, log wrong tool choices and wrong arguments, and fix the schema before you rewrite the prompt.

Why the schema matters more than the prompt

When an agent decides to call a tool, it reads the tool name, the description and the parameter definitions, then chooses. Most failures trace back to ambiguity: two tools with similar names, a free-text field where a record ID was required, a date with no stated format, or a parameter that sounds optional but is actually needed. A longer system prompt rarely fixes these problems. A clearer schema usually does.

This matters more as an agent gets more tools. Each new function adds another choice the model must make correctly, and each overlap between two functions adds a chance of a wrong call. Tool design is therefore an operations decision, not only a developer detail. The person who owns the business process should be able to read the tool list and understand what the agent can do.

Naming rules that help a model choose

Good names are predictable. A model should be able to guess the right tool from the request alone, and a person reading the logs should understand each call without opening the code. A few rules cover most cases:

  • Use a verb plus an object: search_invoices, get_customer_by_email, draft_email_reply.
  • Give each verb one meaning. Use get for a single known record, list for a collection, create for a new record and update for a change to an existing one.
  • Avoid near-duplicates. update_customer and modify_customer will be confused, and the model will pick whichever it saw last.
  • Use the words your team uses for the system, not internal jargon. If staff say "purchase order," the tool should say purchase order, not po_entity.
  • Keep names stable. Renaming a tool breaks prompts, saved evaluations and log searches, so change names only with a version note.
  • Make risky actions visible in the name. Tools that send, post, cancel or pay should never share a prefix with read tools, so a reviewer can scan the list and see the write surface at a glance.

A useful test: read the tool list aloud as if you were a new employee. If two names sound like the same job, rename or merge them.

Typing arguments so wrong values fail early

The type of each argument is the first line of defense. A typed field gives the model a clear target and gives your system a clear reason to reject bad input before anything runs.

Use these habits for every parameter:

  • Declare the real type: integer for quantities, string for identifiers, boolean only for true yes or no questions.
  • Use enums for closed lists. A status field that accepts draft, approved, sent is safer than free text, because the model cannot write "almost sent."
  • Specify date and time formats, such as ISO 8601, and say whether the value is a local date or a timestamp with a time zone.
  • Treat IDs as opaque strings from the source system. Give the model a lookup tool to find the ID, rather than asking it to type one from memory.
  • Set bounds on numbers and lists. A parameter like max_results with a stated maximum prevents a single call from pulling a whole database.
  • Mark a field required only when the tool cannot run without it. Too many optional fields push the model to guess.
  • Keep one concept per field. Do not place a name, an amount and a date inside one string, because your system then has to parse what the model wrote.

Type rules also support your logs. When every argument has a known shape, a failed call tells you which field was wrong, which is far more useful than a generic error.

Descriptions are instructions for the model

The description field is where many teams stop writing carefully, yet it does the most work in tool selection. A good description states four things: what the tool does, when it should be used, when it should not be used, and what it returns. It should also say whether the tool has side effects.

For example, a description for a read tool might say that it returns open orders for one customer, that it should be used before answering any question about order status, and that it never changes order data. A description for a write tool should say that it creates a draft, not a sent message, and that a person must approve before the draft is released. Keep descriptions plain and specific. Long paragraphs of policy inside a description are harder for the model to apply than two short sentences that name the boundary.

Descriptions should not be the only protection. A permission that matters must also be enforced by the system that receives the call, because a model can misread even a clear description. The schema guides the choice, and the permission layer limits the damage when the choice is wrong.

Illustrative scenario: a refund question in a support queue

Illustrative scenario, not a client case: a support team wants an agent to answer refund questions. In the first version, a single tool called handle_refund accepts a free-text request and an optional amount. The agent sometimes issues refunds when it should only explain the policy, and it sometimes sends the wrong amount because the amount was a string containing a currency symbol.

In the revised schema, the team splits the work into three tools. get_order_by_number takes a required order number that matches a fixed pattern and returns the order status and paid amount. check_refund_policy takes an enum for the product category and returns the policy text. create_refund_request takes an order ID, an integer amount in the smallest currency unit, and a reason from a fixed list. It creates a request for a person to approve and never releases money. The wrong-amount problem disappears because the type is an integer, the reason cannot be invented, and the write action is visibly separate from the read actions.

The team then runs the same set of realistic questions against both versions and compares the calls. The change is about what the model is allowed to choose, not about how smart the model is.

How Be Human handles tool schemas in managed operations

In a Be Human engagement, the first step is to define the one role the agent will perform, then list the tools that role actually needs. Names, argument types and descriptions are written together with the people who own each connected system, so that the vocabulary matches the business. Read, draft and write actions are kept as separate tools from the start, and each write path routes to an approval step defined in the operating rules. After launch, recurring evaluations review tool-call logs for wrong choices and wrong arguments, and schema changes follow the same review as permission changes. When a vendor changes an API, the affected tool definitions are updated and tested before they return to production.

Test schemas with realistic requests before you trust them

A schema is a hypothesis until it has been tested. Build a small set of realistic requests from real tickets, emails or messages, and include the awkward ones: requests with missing details, requests that look like two tasks at once, and requests that should trigger no tool at all. Record which tool the agent chose, which arguments it sent, and whether the system accepted them. Separate three kinds of failure: wrong tool, wrong argument and missing confirmation before a write. Each kind points to a different fix. Wrong tool usually means naming or overlap problems. Wrong argument usually means typing or description problems. Missing confirmation means the approval step is absent or unclear.

Repeat the test after every schema change. Anthropic's guidance on evaluating agents describes the same discipline of measuring outcomes on defined tasks rather than judging a single demo. For a business team, the practical version is a short sheet of requests, a column for the expected tool, and a column for what actually happened. If you want a broader view of how to set up that sheet, the acceptance checklist for an AI agent integration covers the questions to settle before go-live.

Keep the tool list small, visible and reviewed

More tools do not make an agent more capable. They make it harder to choose correctly and harder for a reviewer to audit. Start with the smallest set that completes one role, record the purpose of every tool in a shared list, and remove tools that no longer earn their place. A permissions matrix that lists each tool, its access level and its approver makes review faster, because the write surface is in one place. When you later add a tool, add it to the list, the evaluation set and the logs in the same change.

If you are not sure which task in your business is the right first one to hand to an agent, the free Be Human AI diagnostic can help you find it.

Frequently asked questions

How many tools should one agent have? Start with the fewest tools that complete one defined role, usually between three and six for a first engagement. Each extra tool adds a choice the model must make correctly, so add a tool only when a real request cannot be completed without it. Review the list whenever the role changes.

Should the schema or the system prompt hold the rules? Put the rules that shape each call, such as allowed values and required fields, in the schema, because that is where the model reads the parameter definitions. Put the broader operating policy in the instructions, and enforce anything that must never be broken in the system that receives the call. A prompt can be ignored or misread, but a rejected argument cannot be sent.

What is the most common mistake in tool naming? The most common mistake is giving two tools names that describe nearly the same job, such as search and find or update and modify. The model then chooses between them inconsistently, and the logs show calls that look almost right. Merge overlapping tools or rename them so each verb and object pair has one clear meaning.

How do I know whether a schema change worked? Run the same set of realistic requests before and after the change and compare which tool was chosen, which arguments were sent and whether the system accepted them. A change that improves one request type but breaks another should be rolled back or refined. Keep the test set and the results with the schema version so the history stays readable.

Your next step

See where an AI agent fits in your company first.

Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.

Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.

Less busywork. More room for you.

Bring us the work you wish you had time for.

Book a call to try a personalized AI agent free for 7 days ↗Or take the free AI diagnostic →