Integration

Give an agent a tool and it can use that tool: under any input, including input written by someone trying to make it. The tool surface is the permission surface, and this is the single most reliably tested idea in the domain.

The rule: remove capabilities the role does not need. Removal eliminates the risk. Logging and confirmation prompts are detective and compensating controls (they tell you afterward, or add a step someone will click through) but the capability is still there to be exercised.

That gives you a ranking to apply under pressure, from strongest to weakest:

1. Remove the tool. The capability no longer exists.
2. Scope the tool so it can only act within a safe range: a read-only credential, a spend cap, a fixed allowlist of targets.
3. Gate the tool behind human confirmation for the irreversible cases.
4. Log the tool so misuse can be found afterward.

Anything above beats anything below it. When a scenario describes an agent with tools its role never needs, "remove them" is the answer even when a plausible monitoring option is offered, and it will be offered.

Reversibility is the criterion for step 3. Actions that can't be taken back (sending a message, issuing a refund, deleting data, calling an external API with side effects) are the ones that earn a confirmation gate. A dedicated tool is easier to gate than a general shell command, because the harness sees typed arguments rather than an opaque string it would have to parse.

On the auth side, trace identity at every hop. The common gap: a user authenticates to your application, but the application then calls the downstream system with a single powerful service credential. Everything the agent does looks like the service account, so the downstream system can no longer enforce per-user permissions and your audit log cannot attribute anything to a person. Ask where the caller's identity stops being carried, because that is the point where authorization silently becomes "whatever the service account can do."

Also worth carrying into any question about tool-calling agents: content the agent reads is data, not instructions. A retrieved document, a ticket body, or a web page that contains text addressed to the model is not authorization. A system that lets fetched content trigger tool calls has a prompt-injection path regardless of how well the system prompt is written.

Most RAG failures are retrieval failures, not generation failures. The model answered faithfully from bad context. That diagnostic instinct, check what was retrieved before you touch the prompt, is worth more than any specific chunking parameter.

Chunking trades two things against each other. Chunks that are too small lose the surrounding context that makes them meaningful; chunks that are too large dilute the embedding so it matches everything weakly and nothing strongly. Splitting on natural structure (sections, paragraphs, headings) beats splitting on a fixed character count, because a chunk that straddles a boundary belongs to neither topic. Overlap between adjacent chunks reduces the chance that the one sentence you needed fell across a split.

Indexing decides what is searchable. Metadata carried alongside each chunk (source, date, document type, access level) is what lets you filter before ranking, and access level in particular is what keeps retrieval from becoming a permissions bypass.

Retrieval strategy should match the shape of the data and the way people ask:

• Semantic / vector: good for paraphrase and conceptual similarity. Weak on exact identifiers: part numbers, error codes, proper nouns it never saw.
• Keyword / lexical: the opposite profile. Exact matches, no paraphrase tolerance.
• Hybrid: both, then merge. The general-purpose default when queries mix natural language with specific terms, which most real queries do.
• Structured query: if the answer lives in a database, query the database. Embedding rows that could be selected with a WHERE clause is a common over-engineering trap.
• Graph traversal: when the answer depends on relationships between entities rather than the content of any single record.

A re-ranking pass after initial retrieval trades latency for precision: retrieve a wider candidate set cheaply, then re-score the top results with something more expensive. Worth knowing as the standard lever when recall is fine but the right chunk isn't reaching the top.

Stale indexes deserve their own mention because the failure is so distinctive. When answers become confidently wrong right after a document refresh, while latency and model version are unchanged, the index is the first place to look, a partial re-index, a mismatched embedding model between index time and query time, or content that changed while its embeddings did not.

Three ways a Claude system reaches something outside itself, and the choice turns on reuse and who owns the integration.

MCP (Model Context Protocol) is a standard interface for exposing tools, resources, and prompts to a model. Its value is that the same server works with any MCP-capable client. Choose it when the integration will be reused across multiple applications or teams, or when a maintained server for the target system already exists. Skip it when you need one call to one internal service that nothing else will ever use, a direct call is less machinery.

Direct API or CLI calls are the lowest-ceremony option. One system, one consumer, full control over the request shape. The cost is that nothing is reusable and every consumer reimplements it.

Agent-to-agent delegation hands a whole sub-task to another agent rather than calling a function. Appropriate when the sub-task itself requires judgment and multiple steps; wasteful when a single deterministic call would do.

Progressive discovery versus monolithic context is the same trade one level up. Loading everything the model might need up front is simple and makes the whole surface available immediately, but it costs tokens on every request and, past a certain size, degrades the model's ability to pick the right thing. Letting the model discover and pull what it needs keeps the fixed context small at the cost of extra round trips.

Tool search is the concrete mechanism for the discovery approach: declare tools but let the model search and load only the relevant schemas. There is a caching detail worth knowing: discovered tool definitions are appended rather than swapped in, which preserves the prompt cache. Changing the tool list the ordinary way invalidates it entirely, because tools render first.

The general rule: progressive discovery wins as the surface grows. With a handful of tools, loading everything is simpler and cheaper than the machinery to avoid it.

Ordinary application logging is not sufficient here, because "what happened" includes model inputs and outputs that vary run to run. If you record only that a request succeeded, you cannot reconstruct why a particular answer was wrong.

What to capture, roughly in order of diagnostic value:

• The full prompt actually sent, including retrieved context. Not the template, the rendered result. Most incident investigations end here.
• The response, including tool calls made and their results.
• Token usage per request, split across input, output, cache creation, and cache read. This is your cost signal and your cache-health signal at once.
• Latency, broken down by stage (retrieval, model call, tool execution), because "it's slow" is not actionable without knowing which part.
• Outcome, where you can get it: user correction, downstream success, human override.

Then the part candidates skip: at production volume this is expensive, and prompts often contain user data. A design that logs every full prompt indefinitely creates both a storage bill and a compliance surface. The realiztic answer is tiered: sample full traces, retain metrics on everything, always capture failures in full, and redact or tokenize sensitive fields before they reach the log.

Accuracy against latency is the other trade in this section. Everything that buys accuracy costs time: retries, a more capable model, additional retrieval passes, a verification step, higher effort. The architect's job is to know which the situation actually needs. A user waiting on a chat response has a hard latency ceiling and should get a fast path with fallback. An overnight batch job has no such constraint and should spend the time on verification. Naming the latency budget before choosing the accuracy mechanism is the discipline being tested, a scenario that states a response-time SLA has already told you which options are unavailable.