What is the difference between a read-only tool and an action tool?

A read-only tool retrieves information without intentionally changing external state, while an action tool performs an operation that changes something in the outside world or another system.

This difference matters because action tools usually carry more risk and therefore need stronger controls.

Read-only tools

A read-only tool is used to inspect or retrieve information.

Examples include:

• get_order_status
• search_documents
• read_file
• get_customer
• check_inventory
• fetch_weather

These tools are mainly used for observation.

Calling them should not intentionally modify the underlying system.

Action tools

An action tool changes state or causes an external effect.

Examples include:

• send_email
• cancel_order
• issue_refund
• update_customer_address
• create_ticket
• deploy_release

These tools do something rather than only observe.

Simple example

Suppose a user says:

“Cancel order 123 if it has not shipped.”

The agent may first use a read-only tool:

get_order_status(order_id = 123)

If the result is:

status = processing

the agent may then use an action tool:

cancel_order(order_id = 123)

The first tool observes.

The second changes the system.

Read-only tools are generally lower risk

A failed read-only call may cause:

• missing information
• stale information
• additional latency

But it usually does not create a real-world side effect.

For example, calling get_order_status twice normally does not change the order.

This makes read-only calls easier to retry.

Action tools can create real consequences

An action tool may:

• send something
• delete something
• modify a record
• charge money
• trigger a workflow
• change permissions

If used incorrectly, the effect may be difficult or impossible to reverse.

For this reason, action tools need stronger protection.

Permissions should usually be stricter for action tools

An agent may be allowed to inspect a customer account without being allowed to modify it.

For example:

Allowed:

• get_customer
• get_orders

Restricted:

• delete_customer
• issue_refund

This follows the principle of least privilege.

Action tools may require approval

Some actions should not execute immediately even if the agent has selected the correct tool.

Examples include:

• transferring money
• deleting production data
• issuing a large refund
• deploying to production

The workflow may require:

• human approval
• explicit user confirmation
• policy validation
• additional authorization

before execution.

Retry behavior is different

Read-only calls are often safe to retry.

For example:

get_inventory(product_id = P42)

can usually be called again if the first attempt times out.

Action tools are more complicated.

Suppose:

send_email

times out.

The email may already have been sent even though the agent did not receive confirmation.

Blindly retrying could send the email twice.

Action tools benefit from idempotency

For state-changing operations, systems often use:

• idempotency keys
• transaction IDs
• request IDs
• status verification

These mechanisms help prevent duplicate actions when retries happen.

For example:

create_payment

• amount = 1000
• idempotency_key = payment_123

Repeating the call with the same key should represent the same logical payment rather than creating another one.

Read-only does not automatically mean harmless

A read-only tool can still expose sensitive information.

For example:

• employee salary records
• customer financial data
• confidential documents

So read-only tools still need:

• authentication
• authorization
• tenant isolation
• audit logging where appropriate

The difference is about state changes, not whether security matters.

Action tools should expose clear side effects

A tool description should make it obvious when the tool changes something.

For example:

Weak:

manage_subscription

Clearer:

cancel_subscription: Schedule the customer's subscription for cancellation at the end of the billing period.

The second description helps the agent understand the actual consequence.

Prefer read-only checks before risky actions

A common pattern is:

Observe → Validate → Act

For example:

1. retrieve the order
2. confirm it belongs to the user
3. check whether cancellation is allowed
4. execute cancel_order

This is safer than immediately calling an action tool.

Some tools may both read and write

A badly designed tool may combine several capabilities.

For example:

manage_customer

might retrieve, update, or delete customer data depending on arguments.

For agents, narrower tools are often safer:

• get_customer
• update_customer
• delete_customer

This makes permissions and side effects easier to understand and enforce.

A practical distinction

Ask:

Does calling this tool intentionally change external state?

If no, it is generally read-only.

If yes, it is an action tool.

In short

A read-only tool retrieves information, while an action tool changes external state or causes a real-world effect.

Read-only tools are usually easier to retry and lower risk, while action tools need stronger permissions, validation, approval, auditability, and duplicate-action protection.