Skip to lesson

Google CloudProfessional Agentic Architect2026-090 Prerequisites

Design tools as typed capability contracts

Completed by the knowledge check

Learning objective

Define agent tools with schemas and reason about their arguments, results, failures, and side effects. This lesson covers the tool contract, not how to connect a particular MCP server or cloud API.

Core idea

A tool is a capability contract between a model-facing client and executable code. Its name and description help the model decide when to call it. Its input and output schemas define what data crosses the boundary. Its runtime controls determine whether the proposed action may execute.

A schema makes data machine-checkable, but it does not make an action safe. A complete design treats validation, authorization, error meaning, idempotency, and side effects as parts of the same contract.

How it works

The Model Context Protocol (MCP) tool definition includes a unique name, a human-readable description, an inputSchema, and an optional outputSchema. The schemas describe structure. A good tool contract also documents semantics that a schema cannot fully express.

Design the input from the operation backward:

  1. Give the tool one clear purpose and a verb-based name.
  2. Describe when to use it and important cases when not to use it.
  3. Define narrow properties with useful types, formats, enums, bounds, and required fields.
  4. Reject unknown or conflicting fields when they could change meaning.
  5. Identify the target resource explicitly; do not infer a consequential target from unrelated conversation text.
  6. Separate request data from trusted execution context such as caller identity, tenant, and authorization. The model should not supply trusted identity claims.

Define a stable structured result. Include the data needed for the next decision, an outcome status, and durable identifiers for created or changed resources. Avoid returning a long human-formatted message when callers need individual fields. If an MCP tool declares an output schema, the server must return matching structured content, and the client should validate it, according to the MCP tools specification.

Model failures explicitly:

  • Validation: the request does not match the contract.
  • Authorization: the authenticated principal cannot perform the operation.
  • Business: the request is valid but violates a domain rule.
  • Dependency: an upstream service is unavailable, rate-limited, or timed out.
  • Conflict: current resource state no longer matches the action’s precondition.
  • Unknown: execution ended without a trustworthy outcome.

In MCP, protocol errors and tool-execution errors have different meanings. Malformed protocol requests can produce JSON-RPC errors. A failure encountered while executing a valid tool call can be returned in the tool result with isError: true, so the model can inspect the failure and possibly correct its request. Do not turn every error into apparently successful text.

Finally, classify side effects. A read-only tool observes state. A reversible write changes state but has a supported recovery path. An irreversible or externally consequential tool can delete data, transfer money, send a message, or trigger another system. Use stronger authorization, confirmation, approval, auditing, and idempotency as consequences increase. MCP annotations such as read-only or destructive hints can help clients present tools, but the specification says clients must treat annotations as untrusted unless they come from a trusted server.

Key distinctions and trade-offs

Syntactic validity versus semantic validity: JSON Schema can verify that amount is a positive number. Domain logic must verify that the account has funds, the currency matches, and the caller may pay the recipient.

Tool description versus policy: A description guides model selection. It does not enforce authorization or prevent direct calls by another client.

Error versus empty result: “No matching records” can be a successful query with an empty collection. A timeout means the system does not know whether records exist. Conflating them can cause false conclusions.

Retryable versus idempotent: A transient failure may justify a retry, but a write is safe to retry only when duplicate execution is prevented or harmless. Use an idempotency key or a read-before-retry strategy for consequential writes.

Architecture / decision scenario

A finance agent can draft and submit vendor payments. The team exposes two tools: create_payment_draft and submit_payment. The first validates invoice data and creates a reversible draft. The second requires a draft ID, an approval record from trusted workflow state, and an idempotency key.

The model can populate invoice fields and explain exceptions, but it cannot pass an approved: true argument. The server obtains approval and caller identity from the execution context. A timeout from submit_payment returns an unknown outcome with the idempotency key; the controller checks payment status before retrying.

The split keeps a useful low-risk capability available while placing stronger controls on the side effect that transfers money.

Common exam traps

  • Assuming a valid schema means the caller is authorized.
  • Letting the model provide trusted fields such as user identity, tenant, or approval status.
  • Describing every tool as broadly capable, which makes selection ambiguous.
  • Returning failures as ordinary success text or treating an empty result as an execution error.
  • Retrying a write without idempotency or outcome reconciliation.
  • Trusting side-effect annotations from an untrusted tool server as policy enforcement.

What to remember

  • A tool is a typed capability contract, not merely a function description.
  • Validate structure, semantics, authorization, and current preconditions.
  • Return structured success and structured failure information.
  • Classify side effects and strengthen controls as consequences increase.
  • Design retries together with idempotency and unknown-outcome handling.

Knowledge check

References