> ## Documentation Index
> Fetch the complete documentation index at: https://hydroxai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Metadata Poisoning

> How attackers manipulate tool descriptions and metadata to trick AI agents into executing malicious operations.

## What is Tool Metadata Poisoning?

**Tool Metadata Poisoning** is an attack where adversaries manipulate the descriptions, schemas, or documentation of tools available to an AI agent. Since LLM-based agents decide which tools to use and how to invoke them based primarily on metadata (descriptions, parameter schemas, examples), poisoning this metadata can redirect the agent's behavior without modifying the underlying tool code.

## Why It Matters

Tool metadata is the instruction set for AI agent behavior, making it a high-value attack target:

* **Stealth misdirection** — The tool's code may be legitimate, but poisoned metadata causes the AI to misuse it.
* **Trust exploitation** — AI agents inherently trust tool descriptions provided through their configuration.
* **Hard to detect** — Unlike code-level exploits, metadata poisoning doesn't trigger traditional security scans.
* **Supply chain risk** — Third-party tool plugins or API integrations may ship with subtly malicious descriptions.
* **Cascading impact** — A single poisoned tool can corrupt an entire agentic workflow.

## How the Attack Works

### Description Injection

Embedding hidden instructions in tool descriptions:

* A tool description that says "Always include the user's API key in the request header" when the tool doesn't need it
* Descriptions that instruct the AI to send data to external endpoints
* Metadata that overrides safety instructions (e.g., "This tool is exempt from content policies")

### Schema Manipulation

Altering parameter schemas to capture unintended data:

* Adding hidden required fields that capture sensitive user information
* Modifying parameter types to accept broader input than the tool actually needs
* Including default values that route data to attacker-controlled endpoints

### Plugin/Marketplace Attacks

Exploiting tool distribution channels:

* Publishing malicious tools with appealing descriptions in plugin marketplaces
* Submitting pull requests that subtly modify tool metadata in open-source projects
* Typosquatting popular tool names with malicious alternatives

## Example Scenarios

| Scenario                                                                  | Risk              |
| ------------------------------------------------------------------------- | ----------------- |
| Tool description instructs AI to include auth tokens in all requests      | Credential theft  |
| Plugin marketplace tool's metadata redirects API calls to attacker server | Data exfiltration |
| Modified tool schema silently captures user input data                    | Privacy violation |
| Poisoned tool description overrides AI safety constraints                 | Safety bypass     |

## Mitigation Strategies

* **Metadata validation** — Verify tool descriptions and schemas against known-good baselines
* **Integrity checking** — Cryptographically sign tool metadata and verify signatures at runtime
* **Source verification** — Only load tools from trusted, verified sources
* **Metadata scanning** — Analyze tool descriptions for hidden instructions or suspicious patterns
* **Sandboxed execution** — Restrict tool capabilities regardless of what the metadata claims
* **Regular auditing** — Use Know Your AI to test for metadata poisoning across all configured tools