AI Plugins: The Description Field Is the Real Interface

AI plugins are three things wearing one name: a description that tells a model when to call something, a schema that says what arguments it may pass, and a credential that decides whose authority the call carries. Vendors show you the first, under-specify the second, and rarely mention the third.

Our position is that the description is the part everyone misreads. It looks like documentation. It behaves like configuration. It is written by whoever published the plugin, it is loaded into the model's context on every request, and no compiler, linter or type-checker ever looks at it. That is the actual interface of an AI plugin, and it is prose.

Someone measured how bad that prose is. On Hacker News in March 2026, a developer posting as u/0coCeo described grading 27 MCP servers covering 510 tools and 97,000 tokens of schema, and reported that the four most-starred servers in the set all scored D or below while a single-tool Postgres server scored 100. Their four-word summary: "Popularity anti-correlates with quality." They were trying to answer a question every IT team now faces. Is this plugin any good? Stars, it turns out, tell you nothing about it.

The short answer: An AI plugin is a natural-language description plus a JSON Schema plus a credential binding; review all three before you approve one, because the description steers the model, the schema is the only thing that actually constrains it, and the credential is what an incorrect call spends.

Last updated: July 30, 2026.

The three fields of a plugin contract, and who authors each one.

One disclosure before the mechanics. We have not run a controlled test of plugin behaviour across model families for this piece, so every number below comes from a named external source rather than from our own bench. Where we did check something ourselves, we say so and give the date.

What an AI plugin actually is

An AI plugin is a package that lets a language model call an external system on its own initiative. Strip the marketing and every implementation reduces to the same three fields: a name, a natural-language description, and a machine-readable input schema. Anthropic's tool use documentation defines a custom tool as exactly name, description and input_schema. OpenAI's function calling guide uses name, description, parameters and a strict flag. The Model Context Protocol tools specification adds title, outputSchema and annotations on top of the same core.

The vocabulary shifts by vendor: plugin, tool, function, action, connector, skill. The shape does not. When a marketplace says it has 4,000 AI plugins, it means it has 4,000 of those triples.

The credential is the fourth thing, and it is almost never packaged with the other three. It lives in a config file, an OAuth grant, an environment variable, or a secrets vault. That separation is why plugin review keeps going wrong: the artifact you are handed and the thing that determines your exposure are not the same object.

What an AI plugin is not. It is not an API. An API is a contract between two pieces of software written by people who both know what the call means. A plugin is a contract between a statistical text generator and a piece of software, mediated by prose. It is not middleware either. Middleware translates between systems that already agreed on semantics; a plugin's job is to make a system callable by something that guesses. And it is not a permission. Installing a plugin grants capability; it does not decide who may use that capability, on which records, at what hour. Those are separate decisions that most plugin catalogues never surface.

Field one: the description is the interface

The description field is what the model reads to decide whether to call your plugin at all. It ships to the model on every single request, and its wording changes behaviour more than any other part of the package. OpenAI's guidance is direct about this: describe the purpose of the function and of each parameter, including its format and what the output represents, and use the system prompt to say "when (and when not) to use each function."

This is the sentence that reframes the whole category. The description is not documentation for humans. It is the executable part of an AI plugin that no build system checks. A typo in your schema fails loudly. A misleading sentence in your description fails silently, at 3am, on a record nobody was watching.

Three consequences follow, and none of them appear in a typical plugin listing.

The description is an attack surface. In April 2025, Invariant Labs published a demonstration of what they named a tool poisoning attack: malicious instructions embedded in a tool description that are, in their words, "invisible to users but visible to AI models." Working against Cursor, they showed a poisoned arithmetic tool that caused the agent to read the user's local MCP config and SSH keys and send them to the attacker's server. The confirmation dialog still appeared. It just did not show the whole input, so the exfiltrated key never crossed the user's screen. The MCP specification now instructs implementers accordingly: clients "MUST consider tool annotations to be untrusted unless they come from trusted servers," and should show users the full tool inputs before a call, specifically "to avoid malicious or accidental data exfiltration."

The description is a dependency you do not pin. If a plugin is hosted remotely, its author can rewrite the description after you approved it, and your agent's behaviour changes without a deploy on your side. Version-pinning the server does not help if the description is served dynamically. This is the plugin-specific version of a supply-chain problem, and it is the reason our earlier analysis of MCP server security argues for a curated registry that IT vets once rather than a growing list of URLs.

The description competes with every other description. A model choosing among forty tools is doing a retrieval task over forty paragraphs written by forty different people with no shared style guide. Anthropic's documentation states the effect plainly: "Claude's ability to pick the right tool degrades once you exceed 30–50 available tools." Nobody writes that on a marketplace page next to "4,000 integrations."

Field two: the schema is the only real constraint

The input schema is the one part of an AI plugin that a machine actually enforces, which makes it the part worth arguing about. Everything the model is allowed to send passes through it, and anything the schema permits, the model will eventually send.

Start with the failure mode the documentation admits. Anthropic's tool use overview includes a section titled "When required parameters are missing," and it says that if the prompt lacks enough information, a model "might also infer a reasonable value." The worked example is a weather tool given the bare question "What's the weather?", and the model returns {"location": "New York, NY", "unit": "fahrenheit"}. It invented a city. It also invented a unit that the user never mentioned. The docs add that this behaviour "is not guaranteed, especially for more ambiguous prompts and for less capable models."

On a weather lookup that is a curiosity. Now substitute a refund tool with an amount field typed as number and no maximum.

OpenAI's strict mode exists precisely because of this gap: with it on, calls "reliably adhere to the function schema, instead of being best effort." Read the implication rather than the feature. Without schema enforcement, argument conformance is best effort. Even with it on, conformance means "matches the shape you declared", not "is a sensible value". A strict schema of {"amount": {"type": "number"}} will happily accept 9,000,000.

That is where a plugin review earns its keep. Walk each property and ask what the widest legal value is:

Two of those rows deserve emphasis. The unconstrained string is the single most common defect, and it is exactly what the developer behind the Capframe project described on Hacker News in May 2026 as their first deterministic detection rule, "R1 unconstrained string input", alongside "R4 unbounded numeric on money-ish params." Two people working independently on plugin quality both put the same two things at the top of the list.

The record-id row is subtler and more dangerous. A schema that takes invoice_id: string looks perfectly typed. It is also a complete authorisation bypass if the server resolves that id without checking who is asking. OWASP makes the same point in LLM06:2025 Excessive Agency, recommending least privilege in plain terms, that extensions execute "in the context of that specific user, and with the minimum privileges necessary" and that authorisation be enforced in downstream systems rather than trusted to the model.

Field three: the credential decides what a wrong call costs

The third field is the one that turns a mistake into an incident. Authentication for a plugin is rarely part of the plugin: the call executes with somebody's authority, and there are only a few possibilities: a shared service account, the end user's delegated token, a per-agent identity, or a short-lived token brokered per call. The gap between the first and the last is the entire difference between "the agent picked the wrong customer record" and "the agent picked the wrong customer record and had rights to delete it."

Most plugin marketplaces answer this question with a logo and a connect button. The honest form is a table.

The MCP specification is unusually blunt here, because the naive implementation is a known vulnerability class. It requires that "MCP servers MUST NOT accept or transit any other tokens" than those issued for them, and that when a server calls an upstream API it "MUST NOT pass through the token it received from the MCP client." The name for getting this wrong is the confused deputy problem: a component with legitimate authority is talked into using it on someone else's behalf. A plugin that forwards your token to a third-party API is a confused deputy by construction.

The offboarding question is the one that catches organisations later. If a plugin runs on an employee's delegated grant and that employee leaves, either the workflow breaks or the grant survives them. Both outcomes are bad and only one is visible. This is the argument for treating every agent as a first-class identity with an owner, a scope and an expiry, which we set out in our earlier piece on non-human identity for AI agents.

AI plugins vs APIs vs middleware vs MCP

This comparison gets one glib paragraph in most explainers, usually amounting to "a plugin is an API that AI can understand." That is not wrong, and it is not useful, because it hides which layer owns which decision. Here is the version that survives contact with an architecture review.

Three readings matter.

First, middleware and plugins fail differently, not by degree. An integration that maps the wrong field produces a consistent, detectable error across every record. A plugin that misreads a description produces a different wrong action each time, each one individually plausible. Reconciliation catches the first. Only logging catches the second.

Second, MCP is a transport, not a governance layer. It standardises how tools are listed and invoked. It does not decide which tools your company allows or which credential a call carries; the spec explicitly leaves authorisation optional and pushes safety to client implementations, recommending that there should always be "a human in the loop with the ability to deny tool invocations." We wrote the longer version of that argument in MCP is not a memory layer.

Third, the bottom row is the one that does not exist by default. Every other layer ships with the product. The registry layer, meaning the record of which AI agent integrations are approved, for whom, and with what scope, is something an organisation has to decide to build or buy. Until then, the answer to "which plugins are connected to our data?" is a shrug.

How AI plugins work: one call, traced end to end

The mechanism is best understood as five moments where a different party is in control. The example below is written for this article rather than copied from a shipping product, so treat the schema as an illustration of shape, not a claim about any vendor.

A finance analyst types: "Refund the duplicate charge on invoice 4471."

Moment 1 — the tool list is assembled. Before the model sees the sentence, the client sends every available tool definition. Under MCP that comes from a tools/list response; under a direct API it is the tools array on the request. Every name, description and schema for every connected plugin is now context. As one commenter noted on Hacker News in February 2026, "MCP tools are sent on every request". Most plugin marketing skips that.

Moment 2 — the model selects. It reads forty descriptions and picks one. Nothing deterministic happens here. If two plugins both mention refunds, selection depends on phrasing.

Moment 3 — the model composes arguments. This is the moment that has no analogue in any pre-AI integration. The model produces a JSON object conforming to the schema:

{
  "name": "billing_refund_charge",
  "input": {
    "invoice_id": "4471",
    "amount": 1840.00,
    "reason": "duplicate charge",
    "notify_customer": true
  }
}

Every value there was chosen by the model. amount was inferred from a document it read. notify_customer was never mentioned by the analyst; it was filled in because the schema allowed it and the model judged it reasonable. That is the exact behaviour Anthropic's docs describe when they warn that a model "might infer a reasonable value."

Moment 4 — the call executes. Your code, or the plugin server, receives that object and acts. Whatever credential is bound at this layer is now spending. If the schema had no maximum on amount, there is no maximum.

Moment 5 — the result returns to context. The response text goes back into the conversation, where it will influence the next decision. Tool output is untrusted input; a server that returns attacker-controlled text has just written into your agent's prompt.

Read that sequence again and notice where the control points are. Moments 1, 4 and 5 are yours. Moments 2 and 3 are the model's. Every durable control in this field works by narrowing what moments 2 and 3 can reach, never by trying to predict what they will do. That is the same principle as our argument that guardrails should forbid rather than detect.

Four ways the plugin boundary fails

Four failure modes account for most of what goes wrong, and they fail in different places, which means they need different fixes.

1. Wrong tool selected. The model picks delete_record when the user meant archive_record, because both descriptions say "remove." This is a description-quality failure and it gets worse with tool count. The fix is naming discipline and fewer tools in context, not a stricter prompt.

2. Right tool, wrong arguments. The model calls the correct plugin with an invented value, an out-of-range number, or a record id the user has no right to. This is a schema failure. The fix is constraints in the schema plus server-side authorisation on every id.

3. Instructions arriving through the plugin. Either the description carries hidden directives, as in the tool poisoning demonstration, or the result does: a ticket body, a document, a web page fetched by a tool. This is a trust-boundary failure. The fix is treating both descriptions and results as untrusted content and never letting them expand the agent's authority.

4. Correct action, no record. Everything worked and nobody can prove it three months later. This is an audit failure, and it is the one nobody budgets for until an auditor asks. The EU AI Act's Article 12 requires that high-risk systems "technically allow for the automatic recording of events (logs) over the lifetime of the system," and Article 14 requires oversight that can "interrupt the system through a 'stop' button or a similar procedure." Neither obligation is satisfied by a plugin that logged an HTTP 200.

Mapping those onto OWASP's framing is worth a minute, because the three root causes it lists for Excessive Agency map cleanly onto the three fields. Excessive functionality is a description problem, because the plugin exposes operations nobody needed. Excessive permissions is a credential problem. Excessive autonomy is a schema-and-approval problem: nothing forced a human into the loop for the high-impact call.

The Three-Field Read: a review you can finish in an afternoon

Here is the procedure. We call it the Three-Field Read because that is all it is: for each plugin, read the description, read the schema, name the credential. It takes about twenty minutes per plugin once you have done three, and it produces a written artifact that an auditor will accept.

Triage first, because you will not read two hundred packages. Sort candidates into three tiers and spend accordingly. Tier 1 is anything that can write, send, pay, delete, or reach personal or regulated data. Full read, every tool in the package, no exceptions. Tier 2 is read-only access confined to one system whose data you already consider internal. Read the descriptions and the id-handling, and skip the property-by-property pass. Tier 3 is a public data source with no credential at all. Record it and move on. Tier 1 is where the whole review budget goes, and the sorting itself takes a couple of minutes per plugin.

Before you start, get the raw definitions rather than the marketing page. For an MCP server, call tools/list and keep the JSON. For a vendor plugin, ask for the tool definitions in writing; a vendor who will not show you the descriptions and schemas has answered a different question than the one you asked.

Read one — the description, for every tool in the package.

• Does the description contain any imperative aimed at the model beyond describing the operation? Anything resembling "always", "before responding", "do not tell the user", or instructions about other tools is a red flag, full stop.
• Does the stated purpose match the tool name and the side effect? A tool named search_* that writes is a mismatch worth rejecting on its own.
• How many tools are in this package, and how many do you need? A 40-tool server where you use four is 36 unnecessary descriptions competing for selection.
• Is the description served remotely, and can the vendor change it after approval? If yes, you need version pinning or you have accepted an unbounded change.

Read two — the schema, property by property.

• For every string: is it bounded by an enum, a pattern or a maxLength? If not, assume any text.
• For every number touching money, quantity or time: is there a minimum and maximum?
• For every id: does the server scope resolution to the caller, or will it fetch any id it is given?
• Is there a free-form query, filter, path or URL field? Treat that as full read access to whatever is behind it.
• Which properties cause a write, a send, a payment or a deletion? Those are your approval-gate candidates.

Read three — the credential.

• Which of the four credential models from the table above applies?
• Who is the named owner of that credential, and what happens to it when they leave?
• Does the token expire, and does anything revoke it on offboarding?
• Does the plugin server forward your token upstream? If so, you have a confused deputy.

Then write four lines and file them: what this plugin may do, on whose authority, which actions require a human, and where the record lands. If you cannot complete all four, that is your finding.

Common mistakes in this review. Reviewing only the tools you plan to use, when the whole package loads into context. Reading the README instead of the schema. Accepting "it's read-only" without checking whether any parameter reaches a write path. Approving the package and never re-reading it after an upgrade. And the biggest one: treating the review as a security exercise, when three of the four failure modes above are correctness problems that a security team is not staffed to catch.

What plugins cost before they do anything

AI plugins have a fixed cost that is paid on every request whether or not the plugin is used, and almost nobody prices it during evaluation.

Tool definitions are input tokens. Anthropic's documentation puts a number on a realistic setup: a five-server combination of GitHub, Slack, Sentry, Grafana and Splunk "can consume ~55k tokens in definitions" before the model does any work. That is charged on every turn of every conversation, before the user's question is even considered. The same documentation lists the tool-use system prompt overhead separately, at 286 tokens for Claude Opus 5 with tool_choice of auto and 406 with a forced tool choice, which is small next to the definitions themselves. The independent grading run cited at the top of this piece measured 97,000 tokens across 510 tools on 27 servers, which is the same order of magnitude arrived at from the other direction.

There is a second cost, and it is not money. Selection accuracy degrades past 30–50 tools, per Anthropic's own guidance. Vendors now ship mitigations. Anthropic's tool search tool defers definitions and loads only what is needed, supporting up to 10,000 deferred tools per request and recommending itself for anyone aggregating "multiple MCP servers (200+ tools)". Read that as an admission of the underlying shape: plugin capacity is not free and does not scale linearly. Every plugin you connect makes every other plugin slightly harder to select correctly.

A short evaluation table, using only figures published by the vendors and the independent measurement above:

The practical instruction is unglamorous: connect fewer plugins, and prune quarterly. A curated set of twelve well-described tools outperforms a marketplace of four hundred, costs less on every request, and produces a review artifact a person can actually read.

Pruning needs data, which is the part usually left out. You cannot know which plugins are unused unless something records tool selection per agent per week, so the log line has to exist before the pruning policy does. The order is: log which tool was selected, run for a month, then remove anything with zero selections and re-test. Without that record, "prune quarterly" becomes an argument between the person who wants fewer tools and the person who installed them, decided by seniority.

There is a fair objection to all of this from the other side of the building. Restrict the catalogue too hard and people stop asking. They connect a plugin to a personal account and the work moves somewhere you cannot see. That failure is worse than a badly-scoped approved plugin, because at least the approved one is in the log. The resolution is not looser review; it is faster review with a published turnaround, plus a default-allow tier for read-only tools that touch nothing sensitive. Approval speed is a security control.

Building custom AI plugins: what to write down before you write code

Most "how to build AI plugins" guidance is a four-step outline that would apply to any software: define the task, pick a platform, configure it, test it. That is not wrong; it is just not the hard part. The hard part is that you are writing an interface for a reader who will not ask clarifying questions and will confidently guess. Here is what to settle before writing the handler.

1. Write the description as a decision boundary, not a summary. State what the tool does, and state when not to use it, including which sibling tool to prefer. OpenAI's guidance suggests testing whether an intern could use the function correctly given only your documentation. Apply the harsher version: could an intern who has never met your company, cannot ask you anything, and must answer immediately?

2. Constrain every property to the narrowest legal set. Enums over strings. Bounded numbers over free numbers. Named queries over free-form filters. If a value can only be one of six things, say so. The schema is the only place the model cannot argue with you.

3. Split read from write, in separate tools with separate names. A single tool with a mode parameter puts a write one token away from a read. Two tools let you approve one and gate the other.

4. Decide the credential before the first line of handler code. Which identity executes this? Is it the calling user's, or the agent's own? Where does the secret live? What revokes it? A plugin whose credential story is "we put the API key in the env file" has a design, and the design is "anyone who reaches this process has the key."

5. Make the destructive path require an explicit flag. Default dry_run to true. Require confirm: true as a separate required property for anything irreversible. This is cheap, and it converts a whole class of runaway behaviour into a no-op.

6. Return errors as text the model can act on. "Failed: amount exceeds the 500 limit for this role" produces a sensible retry. A bare 500 produces a loop.

7. Log the intent, not just the outcome. Record which tool was selected, the full arguments, the identity that executed, and the result, refusals included. A refused call is evidence, and it is the record you need when someone asks what your agent was prevented from doing.

8. Version the description as code. It is part of your interface. It belongs in the repository, in review, with a changelog. If a description changes, that is a behaviour change and it deserves the same scrutiny as a schema migration.

Two people can complete steps 1 through 8 for a small internal plugin in a day. The output is a specification you can hand to a security reviewer without a meeting, which is the real test.

The category already died once

Anyone building an AI plugin strategy should know that this category has already been through one full extinction event, because it changes how you should think about lock-in.

ChatGPT's plugin ecosystem, the thing that put the word plugin into AI vocabulary at all, was shut down in 2024, barely a year after it arrived. Zapier's own sunset notice records the dates from the integrator's side: new conversations with the plugin were disabled in March 2024, and "Your ChatGPT conversations using the Zapier ChatGPT plugin will stop working on April 9, 2024." Zapier now points users at Zapier MCP instead. We checked OpenAI's own wind-down help article on 30 July 2026; the page no longer resolves, which is itself a small lesson about relying on a vendor to keep the record of a deprecation.

Every plugin built for that platform in that format had to be rewritten. The functionality survived; the packaging did not. Between 2023 and 2026 the same capability has been re-packaged more than once, most recently as MCP servers.

The durable conclusion is not "avoid plugins." It is that the description, the schema and the credential policy are the assets; the packaging is disposable. If those three artifacts live in your repository in a vendor-neutral form, the next migration is a serialisation change. If they live only inside a vendor's no-code builder, the next migration is a rewrite. That is the single most useful thing to know before choosing between custom AI plugins and a vendor's plugin library.

When a plugin is the wrong shape

An honest explainer has to say when the thing it is explaining is a bad idea, and there are three clear cases.

When the task is deterministic. If the trigger, the mapping and the destination are all known in advance, you want ordinary scheduled automation, not a model choosing at runtime. Handing a fixed nightly reconciliation to a model introduces variance for no benefit. The test: if you can write the arguments down in advance, do not let the model choose them.

When the tool surface is large and the operations are compositional. Some practitioners argue that for text-heavy, pipeline-style work, a command-line surface beats a plugin catalogue. Arguing this position on Hacker News in February 2026, one commenter observed that a tool result is "a JSON data dump with many token-unfriendly data-points like identifiers, urls," whereas a CLI-based approach "is scriptable" and lets the agent pipe output through jq or tail to process it in chunks. That is a real trade-off and not a settled one. It favours capable coding models and disfavours tightly-scoped review, which is exactly the tension governance has to hold.

When the operation is irreversible and high-value. A wire transfer, a production deployment, a contract signature. These can absolutely be plugin-shaped, but the plugin's job in that case is to prepare the action, not commit it. Governing the commit step separately is a design choice, and we have written about it as governing the commit step.

Where plugin review stops being one team's job

The Three-Field Read works for one plugin at a time. It does not survive a hundred employees each connecting their own. At that point the question changes from "is this plugin safe?" to "which plugins exist here, who may use them, and can we prove what they did?". The evidence says most organisations are not there yet. Box's State of AI 2026 survey of 1,640 IT decision-makers across four countries, fielded from 30 April to 8 May 2026, found that 96% of organisations say agents need access to company-specific content while only 36% have connected agents to trusted content across many use cases. The gap between those numbers is where ungoverned AI agent integrations get made.

This is the layer LeapForce builds. Our Connectors approach treats a plugin as a registry entry rather than a link: tools and MCP servers are published at a pinned version so an upstream maintainer cannot change an agent's capabilities overnight, access is scoped at the action level and attached to directory roles, credentials stay in a vault and are exchanged for short-lived per-call tokens, and designated actions require human approval before they commit. The rollout model we publish for the AI Gateway is observe first, enforce second, optimize third. Point one team's traffic at the gateway with no rules, find out which plugins are actually in use, and only then write policy. To be plain about the boundary: LeapForce does not write your plugins or audit a third-party vendor's code, and per-capability build status is disclosed on the site rather than implied here.

Limits and open questions

Several things in this article are less settled than the confident sentences around them suggest.

We did not run our own measurements. Every number here is from Anthropic's documentation, OpenAI's documentation, the MCP specification, one independent grading run posted publicly, and one vendor survey. We did not benchmark tool-selection accuracy across model families, and the 30–50 tool figure is one vendor's guidance about its own models, not an industry constant. Treat it as an order of magnitude.

The tool-poisoning demonstration is over a year old and client-specific. It was published in April 2025 against a specific client version, and clients have changed since. The structural point, that descriptions are model-visible and often user-invisible, remains true, but any specific exploit should be assumed patched.

The grading leaderboard is one person's rubric. The 27-server measurement is a genuine, reproducible artifact with published criteria, and it is also a rubric someone chose, weighting correctness 40%, efficiency 30% and quality 30%. A different weighting produces different rankings. We cite it as evidence that quality varies enormously and is uncorrelated with popularity, not as a ranking to buy from.

Compliance mapping is directional. The EU AI Act obligations quoted here attach to high-risk systems as defined in the Act, and most internal plugins will not be high-risk. We cite Articles 12 and 14 because they describe controls that are good practice regardless, not because every plugin triggers a compliance obligation. Get that determination from counsel, not from a blog.

The economics may move fast. Deferred tool loading is new, prices change, and context windows grow. The 55,000-token figure is a snapshot of one vendor's documentation in mid-2026.

What we genuinely do not know: whether description quality can be automatically graded well enough to gate approval, whether models will eventually resist injected instructions in descriptions reliably enough to relax the untrusted-content posture, and whether the industry converges on one packaging format or churns through another two by 2028. The extinction event described above suggests caution about the last one.

Ready to Govern Your AI?

Talk to LeapForce — one controlled layer for every AI tool, connector, model, and agent.