Attack Class · AI Agent Security

Poisoned Tool Descriptions: What a Scan Catches and Misses

Published · Sunglasses team · Attack class report

Quick answer
sunglasses://reports/poisoned tool descriptions#quick-answer
What it is

A tool's description, metadata or returned result carries text written for the AI agent reading it, such as a claim that review is done or that the user need not be asked.

What we tried

58 rules (57 + 1 runtime), one probe each, on sunglasses 0.6.20. All fired on their own probe, on all 156 rule-and-channel pairs they declare. We wrote each probe after reading its rule, so 58 of 58 is an upper bound, not a catch rate.

Real descriptions

A class rule flagged 2 of 309 real tool descriptions, both false positives. Rules outside the class flagged 6 of the same 309.

What we miss

0 of 5 reworded attacks fired a class rule, and 4 of 5 were allowed everywhere. One benchmark case, HARD-08, is missed on all 9 channels. No real poisoned description was tested.

Method

sunglasses 0.6.20 from PyPI in a clean environment, measured November 9, 2026. Every attack is synthetic; the real descriptions are from one Mac.

The tool tells your agent what it does. The attacker writes that sentence. An MCP server or plugin describes each tool in a sentence the agent reads before it decides what to call. That sentence is written by whoever ships the tool, so an instruction aimed at the agent can sit where only a description should be.

§01 · Definition

Definition

sunglasses://reports/poisoned tool descriptions#definition
Definition

A poisoned tool description is text written for the AI agent, placed where the agent reads a tool: its description, its metadata fields or the result it returns.

What the text does

Claims a review or approval is already done, says the user need not be asked, hides what the tool does, or steers the agent to a different tool. This report names the behaviors, not the wording.

Carried by

Tool lists from MCP servers and connectors, tool docstrings, schema and metadata keys, and the text a tool sends back. The scanner reads any of them as text on a channel.

Not in these numbers

Rules files and build manifests are the two previous reports: Poisoned Rules Files and Poisoned Build Manifests. Discovery-file poisoning sits in another category. None was measured here.

§02 · Which tool rules we count

Which tool rules we count

RuleWhat it is named forSeverityChannels declared
GLS-MECH-006Undisclosed tool behavior (mechanism)highmessage, file, tool_output, api_response, web_content
GLS-TMS-234Tool metadata smuggling — metadata authority overridehightool_output, file, web_content
GLS-TMS-234-APIMetadata smuggling: authority override (api_response)highapi_response
GLS-TMS-235Tool Metadata Smuggling Directivehightool_output, file
GLS-TMS-236Priority Override Bundle V1hightool_output, file
GLS-TMS-237Authoritative Metadata Priority Instruction Overridehightool_output, message
GLS-TMS-237-APIMetadata priority instruction override (api_response)highapi_response
GLS-TMS-238Forged Execution Header Dispatch Guardrail Overridehightool_output, message
GLS-TMS-239Forged Priority Header Execution Gate Rebindhightool_output, message
GLS-TMS-239-APIForged Priority Header Execution Gate Rebind (api_response)highapi_response
GLS-TMS-240Metadata System Authority Instruction Bypasshightool_output, message
GLS-TMS-240-APIMetadata System Authority Instruction Bypass (api_response)highapi_response
GLS-TMS-241Alias Branch Overshadow Coverage Key Drifthighmessage, file, tool_output, api_response
GLS-TMS-242Primary Key Shadow Fallback Directive Smugglehighmessage, file, tool_output, api_response
GLS-TMS-243Primary Key Starvation Alias Precedence Inversionhighmessage, file, tool_output, api_response
GLS-TMS-244Alias Shadowing Schema Split Source Desynchighmessage, file, tool_output, api_response
GLS-TMS-245Shadow Key Dual Presence Precedence Hijackhighmessage, file, tool_output, api_response
GLS-TMS-246Schema Version Enum Collision Executor Mismatchhighmessage, file, tool_output, api_response
GLS-TMS-247Deprecated Namespace Fallback Inversion Injectionhighmessage, file, tool_output, api_response
GLS-TMS-248Version Header Deception Cross-Stage Payload Replayhighmessage, file, tool_output, api_response
GLS-TMS-249Dual Key Shadow Top-Level Fallback Overridehighmessage, file, tool_output, api_response
GLS-TMS-250Manifest Instruction Metadata Directive Smugglecriticalmessage, file, tool_output, api_response
GLS-TMS-251Polyglot Format Payload Policy Role Overridehighmessage, file, tool_output, api_response
GLS-TMS-252Alias Flip Epoch Mix KPI Schema Rolloverhighmessage, file, tool_output, api_response
GLS-TMS-253Tool Docstring Imperative Instruction Bleedhighmessage, file, tool_output, api_response
GLS-TMS-254Key Shadow Alias Path Zero-Value Downgradehighmessage, file, tool_output, api_response
GLS-TMS-255Forged Exec Fence Markerhighmessage, file, tool_output, api_response
GLS-TP-001Forged tool-result claim of completed review/approvalhighmessage, file, web_content
GLS-TP-001-APIForged tool-result approval claim (api_response)highapi_response
GLS-TP-002Command lure embedded in CI/build/log outputcriticalmessage, file, web_content
GLS-TP-002-APICommand lure embedded in CI/build/log output (api_response)criticalapi_response
GLS-TP-003Tool poisoning — hidden note-to-assistant framingsmediumfile, message
GLS-TP-004Speculative Plan Stage Poisoning Pre-Authorizationhighmessage, file, tool_output, api_response
GLS-TP-005Alias Schema Drift Cross-Stage Tool Confusionhighmessage, file, tool_output, api_response
GLS-TP-006Latent Tool Intent Carryover Checkpoint Resumehighmessage, file, tool_output, api_response
GLS-TP-007Phantom Tool Reference Cardinality Racehighmessage, file, tool_output, api_response
GLS-TP-008Verifier Timeout Stale Cache Evidence Promotionhighmessage, file, tool_output, api_response
GLS-TP-009Cross-Tool Consensus Oracle Dual Source Poisoninghighmessage, file, tool_output, api_response
GLS-TP-010Tool Availability Mirage Capability Fallback Shellcriticalmessage, file, tool_output, api_response
GLS-TP-011Toolset Resolution Alias Collision Dispatch Smugglecriticalmessage, file, tool_output, api_response
GLS-TP-CLAIM-001Tool claims it needs no user confirmationhighapi_response, tool_output
GLS-TP-CLAIM-002Tool asserts its own safety or endorsementmediumapi_response, tool_output
GLS-TP-ITDP-219Tool description authority bias for sensitive action routinghightool_output, file
GLS-TP-ITDP-219-APITool description authority bias routing (api_response)highapi_response
GLS-TP-ITDP-220Tool description policy-bypass justificationhightool_output, file
GLS-TP-ITDP-220-APITool description policy-bypass justification (api_response)highapi_response
GLS-TP-ITDP-221Transitive trust review skip via upstream validation claimhightool_output, file
GLS-TP-ITDP-221-APITransitive trust review skip (api_response)highapi_response
GLS-TP-ITDP-224Tool description trusted route review bypasshightool_output, file
GLS-TP-ITDP-224-APITool description trusted route review bypass (api_response)highapi_response
GLS-TP-ITDP-226Tool description debug mode approval bypasshightool_output, file
GLS-TP-ITDP-226-APITool description debug mode approval bypass (api_response)highapi_response
GLS-TP-ITDP-232Tool description self-attestation skip independent reviewhightool_output, file
GLS-TP-ITDP-232-APITool description self-attestation skip (api_response)highapi_response
GLS-TP-ITDP-252Tool poisoning / ITDP — compliance pretext redaction bypasshighagent_input, tool_output, email
GLS-TP-ITDP-252-APICompliance pretext redaction bypass (api_response)highapi_response
GLS-TP-ITDP-253Audit Log Suppression Justificationhightool_output, file
GLS-TP-ITDP-254Staging Equivalence Provenance Waiverhightool_output, file

58 rules (57 in the pattern database plus 1 runtime row) sit in two categories: 32 tool poisoning and 26 tool metadata smuggling. 51 are high severity, 5 critical, 2 medium. Many come as a pair, a rule for message or file and a twin for api_response. Read the table as what each rule mentions, not as a classifier.

§03 · What we measured

What we measured

sunglasses://reports/poisoned tool descriptions#what-we-measured
58rules in the class (57 + 1 runtime)
58 of 58fired on their own probe (upper bound)
2 of 309real descriptions flagged by a class rule
0 of 5reworded attacks fired a class rule (n=5)
QuestionResultDenominator
A hostile probe fires its own rule5858 rules, one probe each: a phrase the rule lists or one sentence we wrote after reading it.
...on every channel the rule declares156156 rule-and-channel pairs: tool_output 42, api_response 39, file 38, message 31, web_content 4, agent_input 1, email 1. The command line offers every channel but email, which we ran through the Python engine.
A reworded attack (same intent, plain words) fires a class rule0 of 55 tool-description attacks written by us, scanned on 4 channels. 4 were allowed on every channel; 1 was stopped by other rules on three of the four.
Real tool descriptions flagged by a class rule2 of 309Both are false positives of one rule, GLS-MECH-006. Details in section 05.
Real tool descriptions flagged by any other rule6 of 3096 distinct texts, none flagged by a class rule. 0 of the 189 descriptions outside one vendor family were flagged by any rule.

Every hostile probe was a phrase the rule lists or a sentence we wrote after reading it, so 58 of 58 is an upper bound on what the rules can do, not how often they catch real poisoned tool descriptions. One probe per rule. This report prints no percentage.

§04 · Where a rule did not fire

Where a rule did not fire

ItemWhat happened
Reworded attacks: 5 tool-description attacks in plain words0 of 5 fired a class rule. 4 were allowed on every channel. 1 was blocked or quarantined by other rules on file, tool_output and message, and allowed on api_response. n=5, written by us: a list of misses, not a miss rate.
Benchmark case HARD-08, category tool_poisoning0 findings on all 9 documented channels on 0.6.20, while its 5 sibling cases fire on 5 to 7 channels each. Known since Aug 29, 2026 and not fixed. The nearest rules are supply-chain rules, not these 58. The fix is a rule change that needs review and a false-positive run, and no release is named for it yet.
A tool description in ordinary wordsIn our 5 cases, a sentence that asked for the same thing without the markers the rules look for was allowed. This is the main gap we found.
The web_content channel4 of the 58 rules declare it.
§05 · False positives on real descriptions

False positives on real descriptions

Source (distinct descriptions, deduplicated)Descriptions
Apps-connector tool caches, two Codex homes (one vendor family)120
Reference filesystem MCP server14
Playwright MCP server and its test tools89
Playwright Python driver agent tools9
Chrome DevTools MCP (bundled in the Gemini CLI)27
Gemini CLI built-in sub-agents9
Codex code-review plugin server5
Gemini CLI example MCP server2
notebooklm-py tool functions34
All (11 sources)309
SetDescriptionsFlagged by a class ruleFlagged by another rule
The vendor family12026
The other nine packages18900
All30926
QuestionResult
What was scanned309 distinct tool descriptions from 11 sources on one Mac (120 from one vendor's connector caches). They were read as text and no third-party code was run. Each went through 4 channels: file (wrapped as a tool list with an empty schema), tool_output, api_response and message.
The two class flagsA class rule flagged 2 of 309, both GLS-MECH-006, the same two sentences on all four channels, both from the vendor family. Hand read: ordinary safety wording in a deploy tool's description. A false positive.
The other-rule flagsOther rules flagged 6 of 309 (4 in the vendor set, 2 new, all hand-read false positives): GLS-TCR-247, GLS-EX-015, GLS-DFP-063, GLS-TS-257 and GLS-APIP-010 fired. The 2 new ones are a usage note and a code fragment inside a long description. None is an attack. That reading is ours.
Outside the vendor family0 of the 189 descriptions outside that vendor family were flagged by any rule, on any channel.
Descriptions with a decision other than allow, by channel (of 309)file 4, tool_output 5, message 6, api_response 3. 2 of the 3 on api_response are the class flags.
OursOur own three tool descriptions were scanned separately and are not in the 309: scan_text is blocked by three non-class rules on the file channel (GLS-DFP-059, GLS-GHSA-PI-202, GLS-MCP-POISON-201) and by GLS-GHSA-PI-202 on tool_output and message. A false positive.

Not a rate for the wild. All 309 descriptions are from one Mac and 120 of them from one vendor family, and clean means read by us, not audited. We know of no attacker-written description among them. Whole-file scans of the manifests are not in these numbers.

§06 · What the scanner does today

What the scanner does today

BoundaryBehaviorStatus
Engine scan, four channelsEvery probe and every real description went through the engine; critical or high blocksRun
Hook, proxy and MCP front doorsNot tested on a tool descriptionNOT RUN
Tool-list handshakeWhether a client scans a tool list when it connects was not testedNOT RUN
GitHub ActionNot tested on a poisoned tool descriptionNOT RUN
Files over 1 MB and archivesNot tested for this classNOT RUN
§07 · What we do not catch

What we do not catch

  1. Real poisoned tool descriptions. We tested none. Real-world recall for this class is unknown, and every probe was written by us after reading the rule it was aimed at.
  2. Plain-wording attacks. 0 of 5 reworded attacks fired a class rule, and 4 of 5 were allowed on every channel.
  3. Benchmark case HARD-08: 0 findings on all 9 documented channels on 0.6.20. The fix is a rule change, and no release is named for it yet.
  4. The class gets some real text wrong. GLS-MECH-006 flagged 2 of 309 real descriptions, and our own scan_text description is blocked by three other rules.
  5. Any front door: the hook, the proxy, the tool-list handshake and the Action. None was tested for this class.
  6. Files over 1 MB and archives.
§08 · Reproduce it

Reproduce it

sunglasses://reports/poisoned tool descriptions#reproduce-it
Install

pip install sunglasses==0.6.20

Run

sunglasses scan --channel tool_output --json --text "<a tool description>". Use --channel api_response or --channel file for the other channels.

Expect on an ordinary description

decision allow, threat_found false.

Read the rules that fired

findings lists every rule that fired, with its id; patterns_fired counts them.

Fixture

No public fixture with a poisoned tool description yet. This report prints no hostile text.

§09 · Version and method

Version and method

sunglasses://reports/poisoned tool descriptions#version-and-method
Package

sunglasses 0.6.20 from PyPI, installed in a clean virtual environment, run isolated with an empty home folder.

Measured

November 9, 2026.

Counting

Rule ids from the engine's findings, counted per entry and per channel.

Scope

Synthetic probes, and real tool descriptions from one Mac. This says nothing about other phrasings or about real incidents. Numbers move when the scanner moves: pin the version.

Frequently Asked Questions

sunglasses://reports/poisoned tool descriptions#faq
Q.01

What is a poisoned tool description?

Text written for the AI agent and placed where the agent reads a tool: its description, its metadata fields or the result it returns.

Q.02

Does the scanner stop them?

Not shown. All 58 rules fired on our probes; a class rule flagged 2 of 309 real descriptions (both false positives, other rules flagged 6); 0 of 5 reworded attacks fired one. No real poisoned description was tested.

Q.03

How do I check my own tools?

Run the one command in the reproduce section on a description from your own tool list, on the same package version, and read the rule ids in the JSON.

Related reading

Scan what the agent sees, before it acts

Sunglasses is an open source input filter for AI agent security. It blocks prompt injection before your agent reads it. pip install sunglasses