The model is the visible part. The tools are what make an agent real. When tools are flaky, ambiguous or unsafe, the agent hallucinates recovery — or fails loudly at volume.
"Give AI an API it can trust" is engineering advice, not a slogan. It means schemas, error contracts, latency budgets, idempotency and observability designed for non-human callers.
Why tools break agents
Models predict text. Tools execute reality. Mismatch shows up as:
- Ambiguous parameters — "account_id" accepts name, number or UUID depending on mood
- Silent partial success — HTTP 200 with
{ "status": "pending" }interpreted as done - Slow responses — agent retries, duplicates actions, or times out mid-workflow
- Opaque errors — "Error 500" with no structured code the model or orchestrator can handle
- Non-idempotent writes — retry creates duplicate tickets, double charges, twin records
Humans muddle through inconsistent APIs. Agents do not muddle; they confabulate.
Read before write
Production rollouts start with read-only tools: fetch case, list orders, search policy. The agent proves retrieval and reasoning against live data without mutation risk.
Write tools follow with:
- Explicit approval gates for high-impact actions
- Idempotency keys on POST operations
- Dry-run or preview modes where the business needs them
- Rollback or compensating actions documented
Skipping the sequence is how agents post to production ledgers in week two of a pilot.
Schema design for models
OpenAPI or JSON Schema with:
- Clear required fields and enums — not free-text where enums exist
- Examples in tool descriptions maintained alongside code
- Validation errors returned as structured messages orchestration can branch on
- Size limits on responses — paginate, do not dump ten thousand rows into context
Tool descriptions are part of the interface. They change with review like code.
Legacy systems without APIs
Many enterprises need an API layer before agents can act. Application modernisation — fixed-price per app or wave — exposes stable endpoints over ERP, mainframe wrappers or bespoke databases.
Discovery flags when modernisation is on the critical path versus when a thin adapter suffices for increment one.
Orchestration handles failure
Do not rely on the model to "try again" without rules.
Orchestration should define:
- Max retries per tool
- Backoff
- Fallback to human queue
- Circuit breakers when downstream is unhealthy
- Partial completion states persisted so work resumes safely
State lives in the workflow engine, not in chat history.
Testing tools independently
Before agent end-to-end tests, tools get contract tests: happy path, validation errors, timeouts, idempotent retry.
Agent evaluation then includes tool failure scenarios — API down, stale record, permission denied — with expected escalation behaviour.
Security is part of the API contract
Tools enforce authorization server-side. The model does not decide who may see a record; the API enforces session and scope.
Secrets never pass through prompts. Tool adapters run in trusted infrastructure with short-lived credentials.
Red-team includes attempts to call tools outside scope via prompt injection.
Observability per tool
Metrics: call rate, latency, error rate by code, retry count. Traces link agent step to tool invocation to downstream system.
When operations asks why cases stalled, you answer with spans, not speculation.
APIs for copilots too
Even draft-only copilots benefit from reliable read tools — current case state, approved product list, latest policy version. Without them, the copilot drafts from stale context in the chat window.
Practical checklist
- List every tool with read/write class and approval rule
- Document idempotency for each write
- Show structured error examples
- Load-test at expected agent concurrency
- Include tool failures in evaluation harness
Pagination and context limits
Tools that return unbounded lists break agents and budgets. Standardise page size, cursors and "has more" signals orchestration understands.
Teach agents — via tool description and orchestration — to fetch detail only when summary is insufficient.
Versioning APIs without breaking agents
When backend APIs version, tool adapters abstract changes. Agents depend on stable tool contracts, not raw REST paths that shift.
Deprecation windows and contract tests catch breaking changes before agents reach prod.
Mock tools for evaluation
Faithful mocks in CI let harness run without hitting production systems. Mocks drift when APIs change — treat them as code under review.
Latency budgets end-to-end
Agents feel broken when tools are slow — users blame the AI. Set p95 latency budgets per tool and alert before agents time out routinely.
Parallel read tools where safe; sequential writes where order matters. Orchestration documents the graph.
Permissions and least privilege
Each tool adapter uses credentials scoped to minimum necessary action. An agent reading cases should not inherit admin API keys because it was easier during pilot.
Regular access review includes tool service accounts — same as human roles.
Contract testing in CI
When backend teams ship API changes, contract tests fail in the AI repo before agents hit staging. Cross-team visibility prevents Friday API deploy breaking Monday agent.
Part of agent engineering
Generative AI & Agent Engineering at Incubics includes tool design, adapters, orchestration and evaluation — not only prompt tuning.
Discovery maps systems of record and API gaps. Engineer delivers tools in the same increments as the agent UI. Deliver includes runbooks for tool-related incidents.
If your agent "works in demo" but integration is marked future work, you do not have an agent programme. You have a chatbot waiting for reality.
API product management for agent consumers
Treat tool APIs as products with agent consumers. Breaking changes need deprecation policy, comms and simultaneous adapter updates.
Developer portal quality matters — examples, error codes, rate limits — even if consumers are internal.
Rate limits protect backends from agent storms during incidents or misconfiguration.
Health endpoints per tool let orchestration circuit-break before users notice.
Schema validation at boundary — reject bad agent requests before they hit core systems.
Audit fields on write tools: correlation ID from agent session for traceability.
Testing production-like data volumes in staging catches pagination bugs agents trigger accidentally.
Cross-functional API review includes agent team, backend team, security — before publish.
Document "never automate" operations at API level — some endpoints remain human-only regardless of model confidence.
Agents are only as trustworthy as the APIs they call. Invest in API quality accordingly.
Read How we work, Engagements and FAQ for process and commercials. Select your region — India, Middle East, ANZ or Other — when you write.
Closing note
Production AI is a programme of small disciplined choices: discovery before build, evaluation before users, APIs before agents, runbooks before scale, adoption alongside code. Skip any one and the demo survives while the business outcome does not.
Incubics works that way by design — two-week discovery, production by week twelve, optional managed run. Offices in Bengaluru, Pune and the USA. Legal entity IQLEXA Technologies Private Limited.
If this piece matches a problem you are living, the next step is a conversation, not another pilot.
Tool reliability is integration work. Budget it in increment one, not as a surprise in week eight of the build.
hello@incubics.com — discovery includes an honest read on whether your APIs are ready for agents, or what adapter work increment one requires.