Agentic Builder Path / Agentic Systems
Tool and MCP Server Design
How to expose tools to agents through clear contracts, permissions, telemetry, and failure handling.
How to expose tools to agents through clear contracts, permissions, telemetry, and failure handling.
Use the brief to sharpen a real ai upskill conversation: what is the decision, what evidence matters, and what should remain human-led?
Capture one design rule you would reuse when reviewing an AI workload, assistant, or operating model.
Executive note
The Core Idea
Agents become more useful when they can use tools. A tool might search approved knowledge, read a record, create a ticket, run a calculation, check access, or call another business service.
MCP, the Model Context Protocol, is one pattern for exposing tools and context to AI systems in a reusable way. The design challenge is not simply "can the agent call this?" The better question is "can the agent call this safely, predictably, and with evidence?"
Section 2 of 7
Treat Tools As Contracts
A tool is an API contract for an AI system. The contract should be narrow and explicit.
Good tool contracts describe:
Vague tools create vague behavior. A tool called `doWork` gives the model too much interpretation space. A tool called `searchApprovedPolicyDocuments` gives clearer intent, boundary, and evaluation criteria.
- What the tool does.
- What inputs it accepts.
- What permissions are required.
- What result shape it returns.
- What errors mean.
- What the agent should do if the tool cannot complete.
Section 3 of 7
Design For Least Privilege
Agents should not receive broad access just because the user has broad access. The tool should check the user, the agent, the requested object, and the action.
That is where fine-grained authorization matters. A user may be allowed to view a curriculum, but not edit it. An agent may be allowed to draft a quiz, but not publish it. A verifier may be allowed to check a credential, but not list all credentials for a user.
Good systems make those distinctions before the tool runs.
Section 4 of 7
Failure Is Part Of The User Experience
Tool calls fail. A record might not exist, the user may not have permission, a dependency may be unavailable, or the result may be too large.
Agents need structured failures, not only generic exceptions. A good tool response helps the agent explain what happened and what the user can do next.
For example:
- `not_found`: the requested object does not exist or is outside scope.
- `permission_denied`: the user or agent cannot perform the action.
- `needs_approval`: the action is allowed only after confirmation.
- `temporarily_unavailable`: retry later or use a fallback.
Section 5 of 7
Observability Is Not Optional
Tool use should emit technical and business signals. Technical telemetry shows latency, errors, retries, and dependencies. Business events show what the user journey did: opened a brief, launched a knowledge check, answered a question, requested feedback, or earned a credential.
Correlate both signal types with trace identifiers so teams can explain the full story behind an outcome.
Section 6 of 7
Recommended Practices
- Start with read-only tools before write tools.
- Keep tool names and descriptions precise.
- Validate all inputs server-side.
- Check OpenFGA or equivalent authorization inside the API.
- Emit OTel traces and business events for every meaningful call.
- Treat MCP servers as production services with versioning, ownership, and release notes.
Section 7 of 7
Remember This
Tool design is where agentic AI becomes real enterprise software. A useful tool is not only callable. It is permissioned, observable, testable, and small enough for both humans and agents to understand.