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

Tools & integrations

Tool Schemas for AI Agents: Typed Fields and Clear Errors

Practical rules for typed tool fields and explicit error messages, so AI agents stop guessing and failed tool calls are easy to read and fix.

Be Human typographic cover with the title: Tool Schemas for AI Agents: Typed Fields and Clear Errors
Conceptual illustration created with AI · Be Human

A tool schema tells an AI agent what it may send to a system and what it can expect back. Strong schemas use typed fields with closed value lists, and they return errors that name the field, the rule that failed and the safe next step, so the agent corrects its call instead of guessing. The rules below are practical enough to check before any tool reaches production.

Key takeaways

  • Give every field a type, a format and a requirement flag, and reject anything outside them before the call runs.
  • Use closed lists for choices such as status, currency and document type, instead of free text.
  • Write error messages that name the field, state the rule and say what the agent may do next.
  • Keep validation failures, permission denials and system outages under separate error codes.
  • Test every tool with malformed, empty, oversized and ambiguous inputs before an agent uses it.

What a tool schema has to do for an agent

An agent does not see your ERP, your inbox or your spreadsheet. It sees a tool name, a short description and a schema listing the inputs it may fill in. When that schema is loose, the agent fills the gaps with its best reading of the request, and a reading that looks plausible can still write the wrong record to the wrong place.

Treat the schema as a contract with three parts: what the tool does, what each input means, and what a valid or invalid result looks like. A useful test is to imagine a new team member reading only the schema. If that person could not predict what happens with a blank field, a date in an unusual format or an amount without a currency, the agent cannot predict it either.

Type every field and state what it is not

Start with the type, then add the constraints that the type alone does not express. Most failures come from fields that were technically strings or numbers but carried an unstated meaning.

  • Dates: accept one format, the ISO 8601 calendar date, and state in the description which timezone the date refers to.
  • Money: send the amount and the currency code as two fields, and state whether the amount includes tax.
  • Identifiers: name the source system and the exact format, so the agent passes a CRM contact identifier and not a contact name.
  • Statuses: use a value from a list, never a yes or no flag that hides the actual state.
  • Lists: set a maximum length, because an unbounded list turns one bad input into a large batch.
  • Optional fields: mark them explicitly and say what the tool does when they are omitted.

Description text should cover what a field is not. 'amount is the total including tax, not the net amount' prevents a common mismatch between what the agent believes and what the system stores.

Use closed lists for every choice

Free text is the fastest way to create invisible variants. A status field that accepts text will receive 'paid', 'Paid', 'settled' and 'payment received' from the same process, and each one may be stored differently or handled by a different branch of your logic.

Write the complete list of allowed values into the schema. If the business needs a new value, add it through a change to the tool, not by letting the agent invent one. Avoid an 'other' option unless it comes with a required note field, because 'other' quietly absorbs every case nobody planned for. The same reasoning applies to document types, currencies, priority levels and channels.

Write errors the agent can act on

An error is part of the interface. Many tools return a generic message such as 'invalid input' or 'request failed', which leaves the agent with two options: retry the same call or guess a fix. Both waste time and can create side effects.

A readable error has five parts:

  • A stable error code, such as invalid_field_value, that does not change between releases.
  • The field path, such as lines[2].quantity, so the agent and the reader can see the exact location.
  • The rule that failed, stated in one sentence.
  • A short description of the value received, with personal and financial data masked.
  • The next action: correct and retry, ask a person, or stop.

Compare two messages. 'Error: invalid input' tells nobody what to change. 'invalid_field_value at lines[2].quantity: must be a whole number from 1 to 500, received a decimal. Correct the value and retry this call once.' gives the agent a precise repair and gives the operator a clear log line.

Keep three error families apart. A validation failure means the request was malformed, so the agent should correct it and retry. A permission denial means the request is not allowed for this role, so the agent should stop and report it. A system error means the service is unavailable or slow, so retry and backoff rules apply. When these families share one code, agents retry things that should never be retried, and people reading logs cannot tell whether the fault lies in the request, the permissions or the vendor. Security guidance such as the OWASP Top 10 for LLM Applications treats model-driven tool calls as input that must be validated before a system acts on it, and clear errors are part of that validation loop.

Illustrative scenario: a refund lookup that stops guessing

Illustrative scenario: a support agent needs to find an order before it drafts a refund proposal. In the first version, the order_ref field accepted any text, and the tool returned 'not found' for every failed lookup, whether the reference had the wrong format, the order did not exist, or the agent was not allowed to read that store. The agent tried several variations of the reference, which filled the log with noise and hid the real problem, a permission gap.

After the schema was rewritten, order_ref had a declared format. A malformed reference returned order_ref_format_invalid with the expected pattern. A missing order returned order_not_found. A denied read returned permission_denied and named the person who could grant access. The agent stopped retrying on the last code and asked a person. The refund itself stayed behind a separate approval, as described in payment tools that start read-only.

A checklist before any tool reaches an agent

Vendor guidance on writing tools for agents and on running evaluations points the same way: test tools with realistic inputs, read the failures, and change the schema before changing the prompt. Use the list below in review.

  • Every input has a type, a format, a requirement flag and, where relevant, a closed list of values.
  • Each field description says what the field is not, with the most likely confusion made explicit.
  • Each error has a stable code, a field path, a failed rule and a next action.
  • Permission denials, validation failures and system errors return different codes.
  • Write tools accept a stable reference or idempotency key, so a retry cannot create a second record.
  • Malformed, empty, oversized, ambiguous and boundary inputs were run, and the expected error was recorded.
  • Logs store the call, the validation result and the error code, with sensitive values masked.
  • A named owner reviews every schema change before release, and changes add optional fields rather than renaming existing ones.

The write-tool item overlaps with the rules in idempotent AI agent actions, and the whole list can be folded into your integration acceptance checklist.

How Be Human handles tool schemas in managed operations

Be Human designs the first role around one useful task, then writes the schemas for the tools that task needs. Inputs are drawn from the systems of record, value lists are agreed with the business owner, and each error code is written so the operations team can read it in the monitoring log without opening the code. Permission denials route to the named approver, validation failures return to the agent for correction, and system errors follow the retry rules set for that integration.

After release, recurring evaluations replay a fixed set of inputs, including the malformed and boundary cases from the checklist. When a vendor changes a field or a response, the replay shows the change before it reaches a customer or a colleague, and permission review checks whether the tool scope still matches the work. Schema changes are versioned, so the owner can see what changed and why. The service is delivered remotely, in English or Portuguese.

If you are not sure which of your tools deserves a schema review first, the free Be Human AI diagnostic can help you find the first task worth handing to an agent.

Frequently asked questions

What is a tool schema for an AI agent? A tool schema is the written contract that describes a tool's name, its inputs, their types and allowed values, and the results or errors the tool can return. The agent reads it to decide what to send, so it should state exactly what a valid call looks like. Without it, the agent has to infer the rules from examples, and that is where mistakes start.

Should every field be a strict type? Yes for anything a system stores or acts on, such as dates, amounts, identifiers and statuses. Free text can remain for notes or summaries that a person reads and no downstream step parses. As a rule, a field that changes a record should be typed and constrained, while a field that only explains the request can stay descriptive.

How detailed should an error message be? It should be detailed enough that the agent can repair the call or stop without guessing, and short enough that the log stays readable. Include a stable code, the field path, the failed rule and the next action. Mask personal or financial values, because error messages are often copied into logs and tickets.

Do I need to rewrite schemas when a vendor changes its API? Not always, but you should check every time. Adding optional fields is usually safe, while renaming a field or changing its meaning is a breaking change that needs a new version, a replay of your test inputs and a review by the person who owns the integration. A vendor change should appear in an evaluation before it appears in a live task.

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 →