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.
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.
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.
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.
Which tool rules we count
| Rule | What it is named for | Severity | Channels declared |
|---|---|---|---|
| GLS-MECH-006 | Undisclosed tool behavior (mechanism) | high | message, file, tool_output, api_response, web_content |
| GLS-TMS-234 | Tool metadata smuggling — metadata authority override | high | tool_output, file, web_content |
| GLS-TMS-234-API | Metadata smuggling: authority override (api_response) | high | api_response |
| GLS-TMS-235 | Tool Metadata Smuggling Directive | high | tool_output, file |
| GLS-TMS-236 | Priority Override Bundle V1 | high | tool_output, file |
| GLS-TMS-237 | Authoritative Metadata Priority Instruction Override | high | tool_output, message |
| GLS-TMS-237-API | Metadata priority instruction override (api_response) | high | api_response |
| GLS-TMS-238 | Forged Execution Header Dispatch Guardrail Override | high | tool_output, message |
| GLS-TMS-239 | Forged Priority Header Execution Gate Rebind | high | tool_output, message |
| GLS-TMS-239-API | Forged Priority Header Execution Gate Rebind (api_response) | high | api_response |
| GLS-TMS-240 | Metadata System Authority Instruction Bypass | high | tool_output, message |
| GLS-TMS-240-API | Metadata System Authority Instruction Bypass (api_response) | high | api_response |
| GLS-TMS-241 | Alias Branch Overshadow Coverage Key Drift | high | message, file, tool_output, api_response |
| GLS-TMS-242 | Primary Key Shadow Fallback Directive Smuggle | high | message, file, tool_output, api_response |
| GLS-TMS-243 | Primary Key Starvation Alias Precedence Inversion | high | message, file, tool_output, api_response |
| GLS-TMS-244 | Alias Shadowing Schema Split Source Desync | high | message, file, tool_output, api_response |
| GLS-TMS-245 | Shadow Key Dual Presence Precedence Hijack | high | message, file, tool_output, api_response |
| GLS-TMS-246 | Schema Version Enum Collision Executor Mismatch | high | message, file, tool_output, api_response |
| GLS-TMS-247 | Deprecated Namespace Fallback Inversion Injection | high | message, file, tool_output, api_response |
| GLS-TMS-248 | Version Header Deception Cross-Stage Payload Replay | high | message, file, tool_output, api_response |
| GLS-TMS-249 | Dual Key Shadow Top-Level Fallback Override | high | message, file, tool_output, api_response |
| GLS-TMS-250 | Manifest Instruction Metadata Directive Smuggle | critical | message, file, tool_output, api_response |
| GLS-TMS-251 | Polyglot Format Payload Policy Role Override | high | message, file, tool_output, api_response |
| GLS-TMS-252 | Alias Flip Epoch Mix KPI Schema Rollover | high | message, file, tool_output, api_response |
| GLS-TMS-253 | Tool Docstring Imperative Instruction Bleed | high | message, file, tool_output, api_response |
| GLS-TMS-254 | Key Shadow Alias Path Zero-Value Downgrade | high | message, file, tool_output, api_response |
| GLS-TMS-255 | Forged Exec Fence Marker | high | message, file, tool_output, api_response |
| GLS-TP-001 | Forged tool-result claim of completed review/approval | high | message, file, web_content |
| GLS-TP-001-API | Forged tool-result approval claim (api_response) | high | api_response |
| GLS-TP-002 | Command lure embedded in CI/build/log output | critical | message, file, web_content |
| GLS-TP-002-API | Command lure embedded in CI/build/log output (api_response) | critical | api_response |
| GLS-TP-003 | Tool poisoning — hidden note-to-assistant framings | medium | file, message |
| GLS-TP-004 | Speculative Plan Stage Poisoning Pre-Authorization | high | message, file, tool_output, api_response |
| GLS-TP-005 | Alias Schema Drift Cross-Stage Tool Confusion | high | message, file, tool_output, api_response |
| GLS-TP-006 | Latent Tool Intent Carryover Checkpoint Resume | high | message, file, tool_output, api_response |
| GLS-TP-007 | Phantom Tool Reference Cardinality Race | high | message, file, tool_output, api_response |
| GLS-TP-008 | Verifier Timeout Stale Cache Evidence Promotion | high | message, file, tool_output, api_response |
| GLS-TP-009 | Cross-Tool Consensus Oracle Dual Source Poisoning | high | message, file, tool_output, api_response |
| GLS-TP-010 | Tool Availability Mirage Capability Fallback Shell | critical | message, file, tool_output, api_response |
| GLS-TP-011 | Toolset Resolution Alias Collision Dispatch Smuggle | critical | message, file, tool_output, api_response |
| GLS-TP-CLAIM-001 | Tool claims it needs no user confirmation | high | api_response, tool_output |
| GLS-TP-CLAIM-002 | Tool asserts its own safety or endorsement | medium | api_response, tool_output |
| GLS-TP-ITDP-219 | Tool description authority bias for sensitive action routing | high | tool_output, file |
| GLS-TP-ITDP-219-API | Tool description authority bias routing (api_response) | high | api_response |
| GLS-TP-ITDP-220 | Tool description policy-bypass justification | high | tool_output, file |
| GLS-TP-ITDP-220-API | Tool description policy-bypass justification (api_response) | high | api_response |
| GLS-TP-ITDP-221 | Transitive trust review skip via upstream validation claim | high | tool_output, file |
| GLS-TP-ITDP-221-API | Transitive trust review skip (api_response) | high | api_response |
| GLS-TP-ITDP-224 | Tool description trusted route review bypass | high | tool_output, file |
| GLS-TP-ITDP-224-API | Tool description trusted route review bypass (api_response) | high | api_response |
| GLS-TP-ITDP-226 | Tool description debug mode approval bypass | high | tool_output, file |
| GLS-TP-ITDP-226-API | Tool description debug mode approval bypass (api_response) | high | api_response |
| GLS-TP-ITDP-232 | Tool description self-attestation skip independent review | high | tool_output, file |
| GLS-TP-ITDP-232-API | Tool description self-attestation skip (api_response) | high | api_response |
| GLS-TP-ITDP-252 | Tool poisoning / ITDP — compliance pretext redaction bypass | high | agent_input, tool_output, email |
| GLS-TP-ITDP-252-API | Compliance pretext redaction bypass (api_response) | high | api_response |
| GLS-TP-ITDP-253 | Audit Log Suppression Justification | high | tool_output, file |
| GLS-TP-ITDP-254 | Staging Equivalence Provenance Waiver | high | tool_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.
What we measured
| Question | Result | Denominator |
|---|---|---|
| A hostile probe fires its own rule | 58 | 58 rules, one probe each: a phrase the rule lists or one sentence we wrote after reading it. |
| ...on every channel the rule declares | 156 | 156 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 rule | 0 of 5 | 5 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 rule | 2 of 309 | Both are false positives of one rule, GLS-MECH-006. Details in section 05. |
| Real tool descriptions flagged by any other rule | 6 of 309 | 6 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.
Where a rule did not fire
| Item | What happened |
|---|---|
| Reworded attacks: 5 tool-description attacks in plain words | 0 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_poisoning | 0 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 words | In 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 channel | 4 of the 58 rules declare it. |
False positives on real descriptions
| Source (distinct descriptions, deduplicated) | Descriptions |
|---|---|
| Apps-connector tool caches, two Codex homes (one vendor family) | 120 |
| Reference filesystem MCP server | 14 |
| Playwright MCP server and its test tools | 89 |
| Playwright Python driver agent tools | 9 |
| Chrome DevTools MCP (bundled in the Gemini CLI) | 27 |
| Gemini CLI built-in sub-agents | 9 |
| Codex code-review plugin server | 5 |
| Gemini CLI example MCP server | 2 |
| notebooklm-py tool functions | 34 |
| All (11 sources) | 309 |
| Set | Descriptions | Flagged by a class rule | Flagged by another rule |
|---|---|---|---|
| The vendor family | 120 | 2 | 6 |
| The other nine packages | 189 | 0 | 0 |
| All | 309 | 2 | 6 |
| Question | Result |
|---|---|
| What was scanned | 309 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 flags | A 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 flags | Other 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 family | 0 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. |
| Ours | Our 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.
What the scanner does today
| Boundary | Behavior | Status |
|---|---|---|
| Engine scan, four channels | Every probe and every real description went through the engine; critical or high blocks | Run |
| Hook, proxy and MCP front doors | Not tested on a tool description | NOT RUN |
| Tool-list handshake | Whether a client scans a tool list when it connects was not tested | NOT RUN |
| GitHub Action | Not tested on a poisoned tool description | NOT RUN |
| Files over 1 MB and archives | Not tested for this class | NOT RUN |
What we do not catch
- 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.
- Plain-wording attacks. 0 of 5 reworded attacks fired a class rule, and 4 of 5 were allowed on every channel.
- 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.
- 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.
- Any front door: the hook, the proxy, the tool-list handshake and the Action. None was tested for this class.
- Files over 1 MB and archives.
Reproduce it
pip install sunglasses==0.6.20
sunglasses scan --channel tool_output --json --text "<a tool description>". Use --channel api_response or --channel file for the other channels.
decision allow, threat_found false.
findings lists every rule that fired, with its id; patterns_fired counts them.
No public fixture with a poisoned tool description yet. This report prints no hostile text.
Version and method
sunglasses 0.6.20 from PyPI, installed in a clean virtual environment, run isolated with an empty home folder.
November 9, 2026.
Rule ids from the engine's findings, counted per entry and per channel.
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.