Skip to main content
Tools are where an agent’s reasoning touches your systems. Their design decides more about safety and reliability than any prompt, and tool sprawl is the most common self-inflicted wound in agent engineering.

​
3.1 Fewer, better tools

The most useful published lesson here comes from Microsoft’s Azure SRE Agent team (sources in Appendix D). They started with more than a hundred tools spread across more than fifty narrowly specialized agents, and ended with five core tools (mostly wide CLIs such as az and kubectl) and a handful of generalist agents. Every tool you add is context the model must carry, a choice it can get wrong, and an interface you must version and test. Five design rules hold up:
  1. Tools are capabilities, not API endpoints. Wrap intent (“get recent deploys for service S”, “top slow queries on database D”), not raw verbs. One good capability replaces five thin wrappers and removes argument-guessing errors.
  2. Descriptions are prompts. The model picks tools by their descriptions. Write them like documentation for a sharp new hire: when to use the tool, when not to, what the result contains, and cost or latency notes for expensive probes.
  3. Read and write are different species. Separate read tools, which run freely inside the loop, from write tools, which are policy-gated (Chapter 6). Enforce the split at the interface, not by convention, so the agent can’t change anything through a read path.
  4. Results are context, so shape them. Return structured, pre-summarized, size-capped results with a pointer to the full data. A tool that returns 80,000 raw log lines attacks your own context budget (Chapter 2).
  5. Every write is idempotent and previewable. A mutating tool supports a plan or dry run, gives the same outcome when retried, and returns a result a machine can check. That turns verification (Chapter 1) and rollback (Chapter 6) into engineering instead of hope.
Rules 1 and 2 side by side:

​
3.2 Skills and runbooks: operational knowledge as code

Above single tools sits the layer that encodes procedure: skills, reusable and versioned units of operational know-how such as “rotate credentials for X”, “drain and recycle node pool Y”, or “collect the evidence bundle for incident class Z”. Skills are where the determinism boundary from Chapter 1 becomes reusable. The model picks a skill and fills in its parameters; the skill’s tested steps and scripts do the work, with their own pre-flight checks, timeouts, and rollback hooks. What that means in practice:
  • Skills live in version control with owners, tests, and a changelog.
  • They state their blast radius and whether they can be undone, so policy (Chapter 6) can classify them.
  • Their run history feeds evaluation (Chapter 7).
A platform’s skill catalog (how rich, how tested, how clear about risk) is a better maturity signal than its demo.
IN PRACTICE: SKILLS AND RISK IN CLOUDTHINKERA CloudThinker skill is a SKILL.md file: YAML frontmatter with a name and a description, then Markdown instructions. Agents choose skills by name and description, so the description is the prompt, exactly as rule 2 says. A .zip package can carry scripts/, schemas/, and references/ folders next to the file, which keeps procedures in Git and out of the model’s improvisation. See Skill format.Skills aren’t versioned in CloudThinker. Uploading a skill with an existing name offers Replace, which deletes the old skill and uploads the new one; it takes effect for every agent in the workspace, and Available in resets to Chat only. To roll back, re-upload the earlier .zip, so keep your skill packages in Git and treat that history as the changelog. See Custom skills.Risk is enforced at the call, not trusted to the skill’s label. Every write an agent makes, from any skill, passes the Always blocked list (built-in calls that never run, such as stopping CloudTrail logging), then your Rules, then the Approval mode. Each Rule shows an access badge so risky ones stand out: Write for calls that change a resource, Destructive for deletes and similar calls such as a Git force push, Session for calls that open a remote shell such as ssh, Sensitive read for reads of secrets, and Every operation for *:*. See What a Rule contains. When you evaluate any platform, ask where the risk decision happens and whether a mislabeled skill could bypass it.

​
3.3 MCP in production

The Model Context Protocol (MCP) is an open standard for exposing tools and data to AI agents. It is why a platform can plug in an observability stack or a ticketing system without custom glue. If a platform speaks MCP, agents and tools from different vendors compose. If it doesn’t, every new tool needs vendor-built glue, and you can’t bring your own. Production use is not plug-and-play. The checklist: Integration is not sensing. Connecting tools so agents can act on systems (the MCP layer) and pushing events from systems so agents notice (the sensing pipeline, Chapter 4) are different mechanisms with different reliability and security profiles. A platform, or a diagram, that blurs them usually has a gap in one.
IN PRACTICE: AN MCP SERVER AS A CONNECTIONIn CloudThinker, your own MCP server is a connection like any other:
  • Agents can call only the tools your server exposes, each named prefix__tool_name with the prefix you set, so you can see the source in approval requests and Rules.
  • Set MCP tool annotations on your server. Approvals treats a tool as a read only when it declares readOnlyHint: true, and as destructive when it declares destructiveHint: true. A tool with no hint is treated as a write, so an unlabeled tool fails safe.
  • Reads run without asking. Writes go through your Rules and Approval mode.
  • URLs that point at loopback, private, or cloud metadata addresses are rejected, including host names that resolve to them.
Where CloudThinker falls short of the checklist above, close the gap on your side:
  • Auth is per connection, not per agent. CloudThinker sends the static HTTP headers you set on the connection, so every agent that has the connection uses the same token. There’s no OAuth and no credential broker. Issue a token used only by CloudThinker, scope it to the tools you expose, rotate it on a schedule, and attach the connection only to the custom agents that need it.
  • No version pinning. CloudThinker calls whatever your server serves. It reloads and re-sorts the tool list only when you save a change to the URL, headers, or transport. Pin and contract-test the server in your own deploy pipeline.
  • Egress. Connections run from CloudThinker Cloud and reach your server over the internet. You can allowlist CloudThinker’s egress IPs on your firewall; see Reaching private services. What your server reaches from there is yours to control.
KEY TAKEAWAYDesign few, intent-shaped tools with read and write paths separated at the interface. Encode procedure as versioned skills with declared risk, and enforce that risk at the call. Treat MCP as production supply chain: pinned, allowlisted, contract-tested, and egress-mapped. The tool layer is where “the agent did something weird” becomes either impossible or inevitable.

​
Next steps

Chapter 4 · Orchestration and Two-Engine Economics

How agents are coordinated, and what 24/7 coverage costs.

Connect an MCP server

Add your own MCP server and control which of its tools count as writes.