If you have ever pointed an agent at an enterprise API, you will know how it goes. The response comes back five levels deep, the model spends half its context working out where the manager's name lives, it retries when a field is not where it expected, and eventually it fills the gap with something it made up. Then you spend the afternoon wondering whether the problem is your prompt.
It usually is not your prompt. Most enterprise APIs were designed for a developer who reads the documentation once and writes code against it. Your agent does not get that luxury. It meets the API fresh on every call and has to work it out from whatever is in front of it.
This series is about building agents you can actually trust with enterprise systems, the kind that stay inside the rules of the organisation they work for. I am starting with the tools those agents call, using Workday's Agent-Ready MCP tools, because how a tool is designed decides most of what happens next.
What changes when the tool is written for the model
Agent-Ready tools cover areas such as Workforce, Financials, Talent, Payroll and Recruiting, and three choices make them behave differently from the APIs you are used to.
The first is that the schemas are flat. Instead of something like this:
{
"supervisoryOrganization": {
"id": "SO-1180",
"manager": { "worker": { "...": "..." } }
}
}
your agent gets one layer of clearly named fields. Less structure to navigate means fewer tokens spent parsing, faster responses and far less room for invention.
The second is that every tool describes itself. Each one carries metadata about what it does and what each parameter expects, so when an agent sends "Oct 1" to a field that wants an ISO-8601 date, the error gives it enough to fix the value on the next attempt instead of guessing again. I have written before about APIs that already know what went wrong, and this is that idea applied to a reader that never gets tired of retrying.
The third is that they speak a standard. The tools follow the MCP JSON-RPC 2.0 specification behind a single endpoint for your tenant:
https://{agentGatewayRegionEndpoint}/{tenantName}/mcp
Your agent connects once, and the model handles tool selection and call syntax from there.
Bring your own agent
This is the bit I find most interesting as a developer, because you do not have to build inside Workday to use any of this. If your agent lives in Claude, Cursor, Copilot Studio or Google Agentspace, it can call the same tools a Workday Custom Agent does. The difference is that you do the registration yourself.
A Custom Agent built in Workday discovers and registers its tools automatically when you save and deploy. A third-party agent has to be registered in the Agent System of Record (ASOR) first, with the tools it is allowed to use listed in its agent definition. Here is a trimmed version of the documented example, a preferred name change agent built on Google Agentspace:
{
"name": "Preferred Name Change Agent",
"provider": "SELF-BUILT",
"platform": "GOOGLE_AGENTSPACE",
"workdayConfig": [{
"skillId": "preferred_name_change",
"executionMode": { "id": "Mode=Delegate" },
"workdayResources": [
{ "tool_name": "create_worker_preferred_name_change", "agent_resource": { "id": "..." } },
{ "tool_name": "list_name_titles", "agent_resource": { "id": "..." } },
{ "tool_name": "list_name_salutations", "agent_resource": { "id": "..." } },
{ "tool_name": "list_hereditary_name_suffixes", "agent_resource": { "id": "..." } },
{ "tool_name": "list_social_name_suffixes", "agent_resource": { "id": "..." } }
]
}]
}
Registering the agent gives you an Agent System User (ASU) token. Authentication is OAuth 2.1 with PKCE only, which most agent platforms and MCP clients already handle natively, so in practice connecting looks like adding any other remote MCP server to your client of choice and pointing it at your tenant's endpoint.
You might be wondering why that example lists five tools when the agent only does one thing. That is down to prompt tools, which are worth understanding before you register anything.
The tool type that will catch you out
You will see three kinds of tool in the catalogue.
| Type | What it does |
|---|---|
| Basic | Reads data |
| Advanced | Writes data |
| Prompt | Reads the valid options a write tool needs |
Lots of Workday fields only accept a value from a predefined list, and a write tool needs the Workday ID (WID) of the right option rather than a string the model came up with. So before create_worker_preferred_name_change can submit anything, the agent calls the four prompt tools to fetch valid titles, salutations and suffixes, picks the right one and passes its WID along.
The catch is that every prompt tool a write depends on has to be in your agent definition too. Leave one out and the write cannot complete. The MCP Explorer lists the required prompt tools in each tool's Details section, so check there before you register.
Finding the tools you need
The MCP Explorer on developer.workday.com is where I would start. You can filter by type, read each tool's description and schema, and copy the WIDs you need.
If you would rather do this from a script or a build pipeline, the ASOR Agent Resource Search API gives you the same catalogue programmatically:
curl "https://us.agent.workday.com/asor/agentResourceSearch/v1?searchString=time%20off&toolType=AGENT_READY&protocol=MCP" \
-H "Authorization: Bearer [token]"
searchString is required and matches partial, case-insensitive names. You can narrow results with toolType (AGENT_READY for native tools, or AGENT to find Workday agents your agent can call as tools), operationType (CREATE, PATCH or VIEW) and protocol=MCP. Each result includes the wid that goes into agent_resource.id when you register. You will need Extend Professional and a token for a user with the Setup: Agents domain, and depending on your subscription agreement the API may need enabling first.
Guardrails you do not have to write
Good tools fix the performance problem. What gets an agent past a security review is knowing what stops it doing something it should not, and here none of that lives in your prompt.
| The question | The answer |
|---|---|
| Who is it acting as? | Its own Agent System User, authenticated with OAuth 2.1 and PKCE |
| Whose data can it see? | In delegate mode, never more than the person it is acting for |
| What can it call? | Only the tools in its agent definition, with security set per skill and per tool |
That last row is the one I would point a security team at. You are not asking the model to please stay in its lane. The platform enforces identity, permissions and an explicit allowlist, whether the agent was built in Workday or in your own stack.
Build for change, not for a version
Read this section twice before you ship anything. Agent-Ready tools are one continuous, unversioned surface that Workday keeps optimising for how models use it. Names, schemas, field names and descriptions can change without notice, and the MCP Explorer updates every Tuesday with a CSV change log you can download.
That is a fair trade for tools that keep getting better for agents, but it changes how you build:
- Use them from agents only. Hard-coded UIs and standard integrations on these tools are not permitted, and anything that depends on a specific tool name, field or structure will eventually break.
- Keep tool names out of your prompts and let the agent discover tools at runtime from their descriptions.
- Know what counts as breaking. Workday keeps it narrow: a tool removed with no replacement, a validation you cannot satisfy, or a security change that takes away access you had. Those come with advance notice. Renames and automatic migrations do not.
- Expect your results to vary. The tools themselves run deterministically, but the model, client, instructions and prompt around them do not.
- Watch for long tool names, which some MCP hosts fail on. If one causes trouble, drop it from your registration and report it.
It also helps to know the limits up front, which are 2,000 concurrent requests, with a refresh rate and burst limit of 500 requests each. The server supports MCP protocol versions 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25, so most current clients will connect without any fuss.
Start here
If you want to try this yourself, join the Workday Developer Program to get access to the MCP Explorer, the docs and a community of people building agents on Workday.
Try this with your own agent:
- Browse the MCP Explorer and pick one read tool and one write tool.
- Note the WIDs, including every prompt tool the write needs.
- Register your agent in ASOR with those tools in its definition.
- Connect your MCP client to your tenant's endpoint and ask it to do something useful.
The interesting part of building enterprise agents was never getting the model to call a tool. It is making sure the tool tells the model enough to get it right, and that the platform refuses when the model gets it wrong.
In Part 2, I look at what happens when the job does not stop at Workday's edge, and how Custom Agent Actions let you turn your own workflows and third-party services into tools that carry the same guardrails.
Top comments (0)