New: outcomized services. Pay per result, with a monthly cap you set. See pricing →
Engineering

Agents That Write to Your Tools Must Read Back

Updated 2026-10 · 8 min read · By the Founder of Outcomizer, former CTO and co-founder

An agent that only reads your tools can embarrass you. An agent that writes to them can destroy work. We learned this in the most ordinary way: an agent updated documents in our project tool, every call returned success, and the documents were broken. Twice, in two different ways.

Neither failure was the model's fault. Both were integration contracts the agent did not know about. This article covers the two traps, then the general rules we now build into every agent that writes to an external system.

Nobody owns the agents after they ship?Evals, cost caps, fixes, and a monthly report. From $1,500 a month.

Trap one: the tool that renders markup as text

The agent wrote a nicely formatted document: headings, bold text, a checklist. It sent HTML, because HTML is what rich text usually is. The tool's API accepted it and stored it, and every tag showed up on the page as literal visible text. Angle brackets, entity codes, all of it. Markdown fared no better: asterisks rendered as asterisks.

The fix was a written contract: this integration takes plain text only, in every field. Formatting uses plain characters: blank lines between paragraphs, capitals for headings, square brackets for checkboxes, hyphens for bullets. Before every write, the agent scans the string for angle brackets and ampersands, and rewrites it if either appears.

Meanwhile a different tool we use takes Markdown and renders it correctly. Same agent, same session, opposite rules. That is why the contract has to be per integration and written down, not inferred.

Trap two: the update that wipes what you omit

The second trap was worse. The update call for a document had no partial update. Sending only a new title wiped the body to empty. Sending only new content wiped the title. The API returned success both times. The agent, reasonably, assumed an update meant "change the fields I sent".

Now the rule is: always send the full object on that call, even when you mean to change one field. If the agent does not have the current content in hand, it fetches it first and sends it back unchanged. The same caution applies to any update endpoint in that tool until we have proven it patches.

Rule: read back after every write

The rule that would have caught both traps on the first occurrence: after any write, read the object back and compare it to what you meant to write. A success response tells you the request was accepted. It does not tell you the content is intact.

Read-after-write is cheap: one extra call per write. For agents that write a lot, verify a sample and verify every write to anything customer-facing. When the read-back does not match, the agent stops and reports. It does not retry blindly, because a retry on a destructive call can make things worse.

This is one of the first checks we add when we take over care of an agent in production, because most write failures are silent until a person happens to open the page.

Nobody owns the agents after they ship?

Evals, cost caps, fixes, and a monthly report. From $1,500 a month.

See Agent Care

Rule: know replace versus patch semantics

For every write endpoint an agent can call, write down whether it replaces the whole object or patches the fields you send. Do not trust the HTTP verb alone. Plenty of APIs use PUT for partial updates or POST for full replacement, and some tool wrappers hide which one sits underneath.

Test it once, deliberately, on a throwaway object: update one field and read back the rest. Put the result in the agent's rules for that integration. Until you know, treat every update as a replace and send the full object.

Rule: idempotency keys for anything that creates

Agents retry. Networks time out after the server already did the work. Without protection, a retried "create invoice" or "send email" happens twice. Where the API supports idempotency keys, generate one per logical action and reuse it on retries. Where it does not, check for an existing object with the same natural key before creating.

Deduplication also belongs in the agent's own logic. Before our agents create tasks, they check for open items with the same title in the same place. It is a small query that prevents a cluttered board and confused humans.

Write the contract into the agent, not the wiki

Each integration gets a short rule block that loads whenever the agent uses it: accepted formats, replace or patch per endpoint, required fields, known limitations, and things the API cannot do. That last part matters. If a tool has no way to delete a column or upload a file, the agent should say so and offer the workaround, rather than promising it and failing.

When something surprising happens in production, the fix goes into that rule block the same day. The next run inherits it. Over time, the rule blocks become the most accurate documentation of your integrations that exists anywhere.

Key takeaways

  • A success response means the write was accepted, not that the content is intact. Read it back.
  • Write down, per integration, which formats render: plain text, Markdown, or HTML.
  • Test whether each update endpoint replaces or patches. Until you know, send the full object.
  • Use idempotency keys or natural-key checks on anything that creates or sends.
  • Fix integration surprises in the agent rule block the same day, so every future run inherits the fix.

Frequently asked questions

For writes, roughly. Writes are usually a small share of agent calls, so the total increase is modest. If it matters, verify every customer-facing write and a sample of the rest.

No. It should stop and report. A mismatch means the contract is not what the agent thinks it is, and retrying a destructive call on a wrong assumption can make the damage worse.

No. It applies to any way an agent writes to an external system: MCP tools, direct API calls, or browser automation. MCP wrappers can make it worse by hiding which endpoint and verb sit underneath.

Free playbook

The 15-Day AI MVP Playbook

Day-by-day plan, a starter CLAUDE.md, the Lovable-to-production checklist, eval and cost worksheets, and 10 prompts. Pure value, no pitch.

Get the playbook →
Next step

Book 20 minutes, or send a brief

A former CTO replies. You leave with a written plan and a fixed estimate.

No spam. One reply within one business day. Or skip the form and book a call.

Thank you. Your brief is on its way. Grab a time now so we can talk it through.

Prefer LinkedIn? Connect with Harish.

HG
Harish Ganapathi, Founder of Outcomizer, former CTO and co-founder

I started Outcomizer because hourly billing rewards the wrong thing. As a CTO I led an 18-engineer team and shipped the products in these case studies, including a Fortune 100 shipping system and a SaaS we later sold. Now I put my fee on the result. I still do the work. You work with me, not a sales layer on top of a bench.

Connect on LinkedIn →
Book a callFree lead test