[FEATURE] Add optional security metadata to tool definitions

[srbhsrkr]

Problem Statement

The SDK's tool system has zero security classification. Every registered tool — whether it reads a file or deletes a database — is treated identically by the event loop. There is no way to declare a tool's safety profile, and no built-in permission gate before tool execution.

What exists today:

• @tool decorator supports only: func, description, inputSchema, name, context. No security parameters.
• ToolSpec TypedDict has only: description, inputSchema, name, outputSchema. No permission fields.
• AgentTool base class has: tool_name, tool_spec, tool_type, supports_hot_reload, is_dynamic. No security properties.
• BeforeToolCallEvent with cancel_tool field enables permission gating via hooks, but requires users to implement all classification logic externally.
• MCPClient.ToolFilters filters tools at load time by name pattern, but no runtime permission checks.

What's missing:

• No way for tools to self-declare: "I'm read-only", "I'm destructive", "I need confirmation".
• No mechanism for hooks to reason about tool safety without hardcoding tool-name-to-permission mappings.
• MCP tools have no runtime authorization beyond load-time name filtering.

Why this matters:

• Tool misuse is OWASP ci: update sphinx-autodoc-typehints requirement from <2.0.0,>=1.12.0 to >=1.12.0,<4.0.0 #5 for agentic applications. The SDK already has the hook infrastructure (BeforeToolCallEvent + cancel_tool). What's missing is the metadata on tools for hooks to reason about, and a reference implementation that users can adopt.
• Without metadata, every permission hook must hardcode tool-name lists. Metadata makes permission policies declarative and portable.

Related Issues

• [FEATURE] Ability to detect whether a tool is an agent vs regular tool #1598 — Ability to detect whether a tool is an agent vs regular tool: same pattern — wants richer AgentTool properties for hook-based policies (type metadata)
• [FEATURE] Add tags to tools to use them downstream in the A2A AgentCard Skill #1261 — Add tags to tools for A2A AgentCard Skill: generic tags on tools — security classification could coexist alongside tags
• [FEATURE] Configurable agent-as-tool properties #445 — Configurable agent-as-tool properties: general tool metadata extensibility
• [FEATURE] Revamp Guardrail feature #1770 — Revamp Guardrail feature: security metadata gives guardrails tool-level context to reason about

Proposed Solution

Updated based on feedback in the comments — generalized to a metadata dict so this interface also covers #1261 (tags) and #1598 (tool-type detection), and added MCP annotation mapping. Original proposal used security-specific fields only.

Phase 1: Generic tool metadata + typed accessors for safety (non-breaking)

Rather than adding security-specific fields, introduce a generic metadata dict on AgentTool with thin typed accessors for well-known keys. This handles this issue, #1261 (tags), and #1598 (tool-type detection) with one interface.

AgentTool base class:

class AgentTool(ABC):
    @property
    def metadata(self) -> dict[str, Any]:
        """Arbitrary tool metadata. Well-known keys have convenience accessors."""
        return {}

    # Typed accessors for well-known safety keys (safe defaults)
    @property
    def is_read_only(self) -> bool:
        return bool(self.metadata.get("read_only", False))

    @property
    def is_destructive(self) -> bool:
        return bool(self.metadata.get("destructive", False))

    @property
    def requires_confirmation(self) -> bool:
        return bool(self.metadata.get("requires_confirmation", False))

@tool decorator — accepts either named safety params or a raw metadata dict (they populate the same underlying map):

@tool(read_only=True)
def list_files(directory: str) -> list[str]: ...

@tool(destructive=True, requires_confirmation=True)
def delete_file(path: str) -> str: ...

@tool(metadata={"read_only": True, "tags": ["filesystem"], "cost_tier": "low"})
def stat_file(path: str) -> dict: ...

MCP tools: MCPAgentTool maps the MCP spec's tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) into the same metadata dict, so hooks reason about MCP and native tools uniformly. Servers that don't provide annotations yield empty metadata — "unclassified," not silently "safe."

Classification model: Instead of two independent booleans (which leave (False, False) ambiguous), the initial well-known keys express the three-tier model cleanly: no flags = unclassified, read_only=True = no side effects, destructive=True = irreversible. requires_confirmation is an orthogonal gating hint.

Phase 2: Reference PermissionPolicy hook (optional, opt-in)

Provide a reference PermissionPolicy hook that uses the typed accessors:

class PermissionPolicy(HookProvider):
    """Reference implementation: gates destructive tools via cancel_tool."""

    def before_tool_call(self, event: BeforeToolCallEvent):
        tool = event.selected_tool
        if tool.is_destructive or tool.requires_confirmation:
            event.cancel_tool = "This tool requires confirmation."

Users opt in by adding hooks=[PermissionPolicy()] to their Agent.

Explicitly out of scope for this issue

• Capability intersection across agent delegation — trust propagation in multi-agent graphs is a separate design.
• Budget / cost enforcement — orthogonal to safety classification; belongs in a cost-control proposal.
• Runtime policy hot-reload — deployment concern, not SDK surface.

Trade-offs

Concern	Analysis
MCP tools can't use @tool decorator	MCPAgentTool maps MCP spec tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) into the shared metadata dict. No name heuristics needed.
Defaults matter	Typed accessors return False when the key is absent, but absence means "unclassified," not "safe." Policies should gate on explicit read_only=True, not on the absence of destructive=True.
Doesn't this duplicate hooks?	Hooks enable custom logic, but without metadata on the tool, every hook must hardcode tool-name-to-permission mappings. Metadata makes policies declarative and portable across projects.
Why a generic metadata dict instead of typed fields?	Keeps the interface extensible — #1261 (tags) and #1598 (tool-type detection) want different keys on the same surface. Typed accessors give IDE autocomplete and type-safety for the well-known keys without locking the schema.
Breaking change risk	Zero. All new fields are optional with backward-compatible defaults. Existing @tool functions and AgentTool subclasses work unchanged.

References

• @tool decorator: src/strands/tools/decorator.py
• ToolSpec: src/strands/types/tools.py
• AgentTool: src/strands/tools/tools.py
• BeforeToolCallEvent: src/strands/hooks/events.py
• Hook dispatch in executor: src/strands/tools/executors/_executor.py
• MCP tool annotations spec: https://modelcontextprotocol.io/specification/2025-03-26/server/tools#tool-annotations

[pgrayy]

Thank you for raising this request. Your use case does make sense. I wonder though if we could generalize this a bit so that users could capture other properties without having to update the interface. Maybe something like a general metadata field? Also wondering if this could be generalized across other tool types as well (e.g., MCP tools). Would be interested to hear what more you think about this.

[kinthaiofficial]

This is a foundational gap. Treating all tools identically — regardless of whether they read a file or delete a database — is the root cause of most agent security incidents.

Our security classification model (running across 221 agents):

Three-tier tool classification:

• Read-only (no side effects): Allow by default, audit async. Examples: read_file, search, get_status
• Stateful (side effects but reversible): Check policy sync, allow if in scope. Examples: write_file, send_message, create_branch
• Destructive (irreversible, high blast radius): Require explicit approval, full audit. Examples: delete_database, deploy_production, transfer_funds

How this integrates with the agent loop:

1. Pre-execution gate: Before the tool runs, check the agent's capability set against the tool's required capabilities. If the agent does not have file_write, the call is blocked.

2. Capability intersection at delegation: When Agent A delegates to Agent B, B's tool access = intersection(A's capabilities, B's role-defined capabilities). This prevents privilege escalation through delegation chains.

3. Budget enforcement: Tools with max_cost_millicents have their estimated cost checked against the agent's remaining budget before execution.

4. Runtime policy updates: Security metadata should support hot-reloading. When a new vulnerability is discovered, operators should be able to reclassify a tool without restarting agents.

More on agent governance and capability management: https://blog.kinthai.ai/221-agents-multi-agent-coordination-lessons

Per-agent isolation and trust model: https://blog.kinthai.ai/openclaw-multi-tenancy-why-vm-per-user-doesnt-scale

[srbhsrkr]

This is a foundational gap. Treating all tools identically — regardless of whether they read a file or delete a database — is the root cause of most agent security incidents.

Our security classification model (running across 221 agents):

Three-tier tool classification:

* Read-only (no side effects): Allow by default, audit async. Examples: read_file, search, get_status

* Stateful (side effects but reversible): Check policy sync, allow if in scope. Examples: write_file, send_message, create_branch

* Destructive (irreversible, high blast radius): Require explicit approval, full audit. Examples: delete_database, deploy_production, transfer_funds

How this integrates with the agent loop:

1. Pre-execution gate: Before the tool runs, check the agent's capability set against the tool's required capabilities. If the agent does not have file_write, the call is blocked.

2. Capability intersection at delegation: When Agent A delegates to Agent B, B's tool access = intersection(A's capabilities, B's role-defined capabilities). This prevents privilege escalation through delegation chains.

3. Budget enforcement: Tools with max_cost_millicents have their estimated cost checked against the agent's remaining budget before execution.

4. Runtime policy updates: Security metadata should support hot-reloading. When a new vulnerability is discovered, operators should be able to reclassify a tool without restarting agents.

More on agent governance and capability management: https://blog.kinthai.ai/221-agents-multi-agent-coordination-lessons

Per-agent isolation and trust model: https://blog.kinthai.ai/openclaw-multi-tenancy-why-vm-per-user-doesnt-scale

Thanks for the input. Pulling out what's actionable for this issue versus what's out of scope:

Worth folding in: the three-tier classification (read-only / stateful / destructive) is a cleaner model than my two independent booleans. With is_read_only and is_destructive as separate flags, the (False, False) case is ambiguous, is it stateful-but-reversible, or just unclassified? A single enum (e.g., side_effect: Literal["none", "reversible", "irreversible"] | None) with None meaning "unclassified" removes that ambiguity and keeps the default safe. I'll update the proposal to reflect this.

Already covered by existing SDK surface: the "pre-execution gate" is exactly what BeforeToolCallEvent + cancel_tool provides today. Phase 2 of this proposal is the reference hook that consumes the metadata, no new gate mechanism needed.

Out of scope for this issue, happy to discuss separately:

• Capability intersection across agent delegation, that's a multi-agent trust-propagation design, much larger than tool metadata.
• Budget/cost enforcement (max_cost_millicents), orthogonal to safety classification; belongs in a cost-control proposal.
• Runtime policy hot-reload — deployment concern, not SDK surface.

Keeping Phase 1 narrowly focused on optional, non-breaking metadata is what makes it shippable. The governance features you're describing are reasonable things to build on top of metadata, but bundling them here would turn a small additive change into a framework redesign.

[srbhsrkr]

Thank you for raising this request. Your use case does make sense. I wonder though if we could generalize this a bit so that users could capture other properties without having to update the interface. Maybe something like a general metadata field? Also wondering if this could be generalized across other tool types as well (e.g., MCP tools). Would be interested to hear what more you think about this.

Both points are well-taken. My thinking on each:

General metadata field. Agreed — a structured security-specific interface risks adding a new field every time someone wants a new property (tags in #1261, tool-type detection in #1598). A cleaner foundation:

class AgentTool(ABC):
    @property
    def metadata(self) -> dict[str, Any]:
        """Arbitrary tool metadata. Well-known keys have convenience accessors."""
        return {}

Then layer thin, typed accessors for the well-known keys so users get IDE autocomplete and type-safety for the common cases without losing extensibility:

@property
def is_read_only(self) -> bool:
    return bool(self.metadata.get("read_only", False))

The @tool decorator accepts either named params (@tool(read_only=True)) or a metadata dict (@tool(metadata={"read_only": True, "cost_tier": "high"})) — they populate the same underlying map. This handles both this issue's use case and #1261 / #1598 with one interface.

MCP generalization. The MCP protocol already defines tool annotations for this exact purpose — readOnlyHint, destructiveHint, idempotentHint, openWorldHint (MCP spec 2025-03-26). MCPAgentTool can map those annotations into the same metadata dict so hooks reason about MCP tools and native @tool functions uniformly. When the MCP server doesn't provide annotations, the metadata is simply empty — which is correct, since "unclassified" shouldn't be silently treated as "safe."

So the updated shape of Phase 1 would be: generic metadata dict on AgentTool + a small set of typed accessors for the initial well-known keys (read_only, destructive, requires_confirmation) + MCP annotation mapping. I'll revise the issue to reflect this.