IBM's Z DevOps ecosystem — Zowe, the RSE API, IBM's internal coding assistant "Bob," Copilot integrations — had no shared standard for how AI agent tools should be named, described, or parameterized. I was individually tasked with defining that standard from the ground up: researching how leading AI companies structure tool design, then converting the result into guidelines the whole org could actually use.
Z DevX builds developer tooling for IBM's Z (mainframe) ecosystem, including AI coding assistants that plug into tools like Zowe and the RSE API. As more of these tools shipped, there was no shared design standard behind them — each was named, described, and parameterized differently, by whoever built it. That inconsistency showed up as real confusion among developers, architects, and designers, stalled work, and inefficient token usage as AI agents struggled to parse ambiguous tool signals.
Without shared conventions, tool naming, descriptions, and parameter design were left to individual judgment — which meant AI agents calling these tools (IBM's Bob, Copilot integrations) had inconsistent, sometimes ambiguous signals to work from. Every new tool made the inconsistency worse, and there was no reference to point new tool authors to.
I ran a gap analysis comparing Z DevX's existing tools against published best practices from leading AI companies, then wrote a full guideline covering naming, tool descriptions, parameters, context and token management, modes, tool grouping, security, and localization — the first standard of its kind for the team.
Decision 1 — an information architecture, not just a style guide. Beyond naming conventions, I designed an IA that organizes tools into modes and skills, so an AI agent isn't handed every tool at once — reducing decision-making complexity and preventing redundant, overlapping tool options from overwhelming the model.
Decision 2 — converting the guideline into something enforceable. A written guideline that lives in a doc gets skimmed once and forgotten. I condensed it into a company-wide skill library — a SKILL.md — so the standard is something tools can actually be checked against, not just read.
Decision 3 — iterating with the people who'd actually use it. Partnered with lead architects and design peers to pressure-test the standard, translating ambiguous requirements around context size, accessibility, and localization into something concrete enough for cross-team reuse.
The end result: a 9-section MCP design guideline (naming → descriptions → parameters → context/token management → modes → tool grouping → security → localization) and the SKILL.md it's built into, now the reference for how AI agent tools get designed across Z DevX.
Adoption drove two measurable shifts: a 30% increase in the team's AI tool usage, and a 50% improvement in token efficiency from the guideline's context-management standards. The guideline was adopted as Z DevX's standard for new MCP tools going forward — and the Bob team has since started building their own tools against it, extending adoption beyond the group that originally commissioned the standard.