The MCP server never publishes tool annotations or output schemas — it already classifies every tool read/write/destructive and tells no host

[serge-ivo]

The MCP server withholds two things the spec has for it, and it already knows both

The owner connected ProAgentStore to ChatGPT. It works — all 135 tools registered with their input schemas, OAuth used, Developer Mode on, Connected 14 Aug 2026. But ChatGPT's settings page flags every single tool with "Output schema recommended", and its permission control reads "Allow low-risk actions" with no way to tell which actions are low-risk.

Both are spec features PAGS does not use. Verified by grep over workers/mcp/src/:

outputSchema      → 0 occurrences
structuredContent → 0 occurrences
readOnlyHint / destructiveHint / idempotentHint / openWorldHint → 0 occurrences

1. Tool annotations — the data already exists

workers/mcp/src/safety.ts:3 declares MCP_SCOPES = ["read", "write", "runtime", "destructive"], every tool is classified against it, and the scope is gated before dispatch. DEFAULT_SCOPES deliberately excludes destructive so delete-agent / overwrite-repo can never run on a default connection (safety.ts:6-9). Destructive tools additionally require an exact confirm string.

So the server knows, per tool, whether it reads, writes, or destroys — and publishes none of it in tools/list. MCP's annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are exactly the channel for this, and they are what a host's "allow low-risk actions" setting reads.

The consequence is concrete: a host must treat list_agents and cancel_instance identically — prompting for both, or trusting both. The owner is running 135 tools in that state.

This is a projection of data that already exists, not new information. That is what makes it worth doing first.

2. outputSchema / structuredContent

Every tool declares inputSchema only, through one registration path (this.server.tool(...), workers/mcp/src/index.ts:138 onward). MCP 2025-06-18 pairs outputSchema with structuredContent so a host can parse a result rather than re-read prose.

Establish before building whether this is cosmetic (rendering), a quality issue (tool selection), or a correctness issue, and from the MCP spec rather than from ChatGPT's warning text alone. A pags-ba agent is separately establishing what OpenAI's Apps SDK does with it. If the honest answer is "it improves rendering and nothing else", say so and scope accordingly — 135 hand-written schemas would be a poor trade for cosmetics, whereas a helper on the shared registration path may be cheap.

Not a gap, stated so nobody adds it reflexively

The server exposes no resources and no prompts. Those are optional MCP features and PAGS is a tool surface; their absence is a design choice, not a standards failure. Do not add them under this issue.

Acceptance criteria

1. tools/list carries annotations derived from the existing scope classification — one source, not a second hand-maintained list. A tool that changes scope changes its annotation automatically.
2. A destructive tool is annotated destructive; a read tool is annotated read-only. Assert it across the whole registered surface, not a sample — index.test.ts:496 already drives the real registration path and asserts h.tools.size === MCP_TOOL_COUNT, so the denominator is available (ADR 0002).
3. Whether outputSchema is adopted is decided on evidence and stated. If adopted, it goes through the shared registration path.
4. MCP_TOOL_COUNT and the /health figure stay correct — tool-count.ts exists because that number rotted once already.
5. No behaviour change to gating: annotations are advisory to the host and must not become the enforcement path. safety.ts stays the authority.

Verified vs inferred

• Verified: all four grep results; safety.ts:3-9; the registration path; SDK pinned at @modelcontextprotocol/sdk 1.29.0; and ChatGPT's own settings page showing 135 tools registered with input schemas and "Output schema recommended" on each.
• Inferred: that annotations are what ChatGPT's "Allow low-risk actions" reads. That is the documented purpose of the field, but I have not confirmed ChatGPT's specific implementation — the parallel BA investigation covers it.

[serge-ivo]

The "establish before building" question in §2, answered from primary sources

Investigated as the parallel BA task this issue names. Everything below is quoted from the MCP
specification, OpenAI's plugin/Apps SDK documentation fetched today (2026-08-15), or the pinned
SDK's own source in node_modules. Line numbers for the SDK are
@modelcontextprotocol/sdk@1.29.0 dist/esm/server/mcp.js.

Verdict on outputSchema: a quality + chaining feature, not correctness — and adopting it is a HARD contract

1. The spec makes it optional but binding.
MCP 2025-06-18 · Server · Tools:

outputSchema: Optional JSON Schema defining expected output structure

Tools may also provide an output schema for validation of structured results. If an output
schema is provided:

• Servers MUST provide structured results that conform to this schema.
• Clients SHOULD validate structured results against this schema.

For backwards compatibility, a tool that returns structured content SHOULD also return the
serialized JSON in a TextContent block.

2. The pinned SDK enforces that at runtime, and the current return shape would fail it.
mcp.js:185-207 validateToolOutput:

if (!result.structuredContent) {
    throw new McpError(ErrorCode.InvalidParams,
      `Output validation error: Tool ${toolName} has an output schema but no structured content was provided`);
}

Every PAGS tool returns text only, through text() / jsonText() (workers/mcp/src/http.ts:15-25).
So declaring an outputSchema without also returning structuredContent converts every
successful call into a protocol error. This is the regression risk for AC#3 and it is not
hypothetical — it is one if in the shipped SDK. The spec's back-compat sentence above means the
existing JSON text block stays: structuredContent is added beside it, not instead of it.

3. The current registration call cannot express an outputSchema at all.
this.server.tool(...) is the legacy tuple overload. On that path outputSchema is declared and
never assigned (mcp.js:663 let outputSchema;) and _createRegisteredTool receives undefined.
The SDK marks the overload closed:

Tool properties are passed as separate arguments, with omissions allowed. Support for this style
is frozen as of protocol version 2025-03-26. Future additions to tool definition should NOT be
added. — mcp.js:665-667

registerTool(name, config, cb) (mcp.js:699) is the only path that carries outputSchema — and
also title and _meta. grep -rn "registerTool(" workers/mcp/src → 0.

That is good news for AC#3: the suspension-gate wrapper already intercepts every registration
(workers/mcp/src/index.ts:76-95 reassigns server.tool), so it can translate the tuple call into
a registerTool config and merge per-tool metadata in from one table. The 136 call sites stay
untouched.

4. What OpenAI says it buys.
developers.openai.com/plugins/build/mcp-server — each tool needs:

• An action-oriented name and human-readable title.
• A description that explains when to use it.
• An explicit input schema.
• An output schema when the tool returns structured data.
• Accurate safety annotations.

The model uses this metadata to decide whether and how to call the tool. Treat names,
descriptions, schemas, and annotations as part of the plugin's user-facing behavior.

On the result shape:

• structuredContent: concise data the model can inspect and use in later calls.
• content: text or other MCP content that helps the model answer the user.
• _meta: client-specific data hidden from the model.

Use stable identifiers in structured results so later tools can refer to the same records.

And deploy/app-review — the submission
scan imports "tool names, titles, and descriptions; input and output schemas; security schemes;
_meta fields; tool annotations … and MCP server instructions".

So: it is not cosmetic and it is not correctness. Rendering is irrelevant here — rendering
needs a UI resource, which PAGS does not return. What it buys is (a) the model reusing an
identifier from result A in call B without re-parsing prose, and (b) the metadata OpenAI's review
scan would record if PAGS is ever submitted publicly.

Recommended scope: the read-and-chain subset, not 135. The tools that pay are the ones whose
result feeds a next call. Everything else can wait, and a tool that returns a one-line
acknowledgement should get no outputSchema at all — an empty one is worse than none, because it
buys nothing and adds the structuredContent obligation.

Three representative shapes:

// list_agents — a list whose ids are the input to almost every other tool
outputSchema: { agents: z.array(z.object({
  id: z.string(), slug: z.string(), name: z.string(),
  category: z.string().optional(), creator: z.string().optional(),
})) }
// → structuredContent: { agents }, content: [ the existing JSON text ]

// agent_trace — the debugging tool; the useful field is trace_id, which the model must
// carry into the NEXT agent_trace / instance_messages call
outputSchema: { events: z.array(z.object({
  ts: z.string(), trace_id: z.string().nullable(), source: z.string(),
  level: z.string(), event: z.string(), context: z.unknown().optional(),
})), count: z.number() }

// usage_summary — numbers, which is exactly what prose loses
outputSchema: { range: z.object({ from: z.string(), to: z.string() }),
  total_cost_usd: z.number(), total_tokens: z.number(),
  by_agent: z.array(z.object({ instance_id: z.string(), name: z.string(),
    tokens: z.number(), cost_usd: z.number() })) }

Read the exact fields off the API handler before writing these — /v1/instances/:id/trace returns
{count, filters, events} on the admin route (workers/api/src/routes/admin-trace.ts:139) and
/v1/usage returns {range, ...summary, unmetered} (workers/api/src/routes/usage.ts:77); the
per-instance trace route should be re-read rather than assumed to match the admin one.

---

The annotations half is the higher-value half, and it is worse than this issue states

Declaring nothing is not neutral. The spec documents defaults, and they are the unsafe ones —
schema/2025-06-18/schema.ts:

readOnlyHint?: boolean;      // Default: false          (line 890-892)
destructiveHint?: boolean;   // Default: true           (line 898-902)
idempotentHint?: boolean;    // Default: false          (line 908-912)
openWorldHint?: boolean;     // Default: true           (line 914-922)

So today every one of the 135 tools presents to any host as not read-only, destructive, and
open-world — list_agents, agent_trace, vector_stats, usage_summary, my_instances
included. The issue's framing ("a host must treat list_agents and cancel_instance identically")
is right, and the direction it defaults to is the pessimistic one.

OpenAI documents the consequence directly:

Annotations help ChatGPT and Codex choose appropriate confirmation and safety behavior. They do
not replace authorization, validation, or confirmation in your server.
— plugins/build/mcp-server

Incorrect or missing action labels are a common cause of rejection. Double-check that the
readOnlyHint, openWorldHint, and destructiveHint annotations are correctly set…
— plugins/app-guidelines

Annotations do not replace server-side authorization, input validation, or confirmation for
consequential actions. — plugins/plan/tools

That last line is AC#5 in OpenAI's own words: safety.ts stays the authority.

Upgrade to the issue's "Inferred" section: annotations are documented by OpenAI as the input
to ChatGPT's confirmation and safety behavior. What I still cannot source is the specific string
"Allow low-risk actions" and how that control maps onto the four hints — that phrase appears
nowhere in OpenAI's published plugin docs. Treat the mechanism as documented and the exact UI
mapping as unverified.

AC#1 needs a correction: the existing classification is neither complete nor single-source

"Annotations derived from the existing scope classification — one source, not a second
hand-maintained list" is the right instinct, but the classification does not cover the surface:

• The derived scope table (workers/mcp/src/instance-tools/contract.test.ts:191+) covers the ~90
  instance tools only: 37 none · 6 read · 30 write · 7 runtime · 10 destructive.
• The other ~45 tools — 32 in index.ts, 13 in storage-tools.ts — are not in it at all.
• none is the largest bucket and it is not junk: every one of the 37 is a read by name
  (agent_trace, list_errors, search_instance_knowledge, usage_summary, vector_stats,
  my_instances, instance_messages, list_instance_tools, …). But the file's own comment is
  explicit that none means ungated, not read-only: "A tool with no gate at all denies neither,
  and shows up as 'none' — which is the honest answer and is itself worth pinning"
  (contract.test.ts:39-42). Mapping none → readOnlyHint:true is a claim per tool, not a free
  derivation.
• remove_repo chooses its scope from its arguments (contract.test.ts:413-421: with a
  repo_url it needs write, without one it needs destructive), so one tool has no single
  static annotation. Annotate it destructive and let the scope gate keep being the real check.

The honest shape is a per-tool annotation table asserted against the derived scope rather than
generated from it: destructive scope ⇒ destructiveHint: true; read/none ⇒
readOnlyHint: true; write/runtime ⇒ readOnlyHint: false; contradictions fail the test. That
keeps AC#2's whole-surface denominator (index.test.ts + MCP_TOOL_COUNT) and drops the false
promise that nothing has to be written down.

Two adjacent gaps found while verifying — fold in or reject explicitly

1. No tool carries a title. OpenAI lists "an action-oriented name and human-readable title"
   among what each tool needs. Unreachable through the frozen tool() overload; free the moment
   the wrapper moves to registerTool. With 135 snake_case names this is cheap legibility.

2. The server sends no instructions. workers/mcp/src/index.ts:41 is
   new McpServer({ name: "ProAgentStore", version: "0.1.0" }) — the second constructor argument is
   absent, so initialize carries no instructions at all. OpenAI:

   MCP servers can also return an instructions field during initialization. ChatGPT and Codex
   use these instructions alongside tool metadata. Use server instructions for guidance that
   applies across tools, such as required tool sequences or shared rate limits. Keep the most
   important details in the first 512 characters.

   With 135 tools, no titles and no output schemas, one 512-character sequencing hint
   (list_agents → my_instances → the instance tools; agent_trace for debugging) is the
   cheapest available lever on tool selection. It also kills a hypothesis that was live before the
   settings screenshot: ChatGPT could not have been reciting a server instructions string,
   because the server sends none.

Negative findings — grepped, so they are findings, not guesses

• No documented cap on tool count. OpenAI's full plugin docs export
  (https://developers.openai.com/plugins/llms-full.txt, 375,701 bytes, fetched 2026-08-15)
  matches nothing for tool limit, maximum of … tools, number of tools, too many tools, or
  tool surface. 135 tools is not a documented disqualifier.
• Protocol negotiation is not a factor. SDK 1.29.0 dist/esm/types.js:2-4 supports
  2025-11-25 (latest), 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07.
• search/fetch are not required for tools to register. OpenAI scopes that pair to one
  surface: "To work with ChatGPT deep research and company knowledge, your MCP server should
  implement two read-only tools: search and fetch"
  (developers.openai.com/api/docs/mcp); the Apps SDK
  page frames it as eligibility for company-knowledge sourcing only. The owner's connector
  registering all 135 tools without them is consistent with that. Recorded here so it is not
  re-derived; it is not part of this issue.

The opening symptom is a setting, not a defect

For completeness, since this issue opens on the ChatGPT report. A developer-mode connection is
not automatically active in a new conversation — OpenAI:

Start a new conversation and add the MCP connection from the tools menu.
— plugins/deploy/connect-chatgpt

which is exactly what ChatGPT told the owner ("isn't installed or enabled in this one"). Nothing in
this issue needs to ship for him to use the connector today. Annotations and outputSchema remain
worth doing on their own merits.

Verified vs inferred

• Verified (code): outputSchema/structuredContent/all four *Hint names = 0 occurrences in
  workers/mcp/src; registerTool( = 0; server.tool( = 136 non-test call sites; no instructions
  at index.ts:41; the SDK behaviours at mcp.js:185-207, :663, :665-667, :699; the scope
  tallies from contract.test.ts:191+.
• Verified (external, quoted above): the MCP spec's optionality, MUST/SHOULD contract and
  documented annotation defaults; OpenAI's statements on output schema, annotations, server
  instructions, review scanning, and per-conversation enablement.
• Inferred: that adopting outputSchema on the chaining subset measurably improves multi-step
  behaviour. OpenAI asserts the mechanism; I have not measured it against PAGS. The
  structuredContent obligation, by contrast, is verified from the SDK source and is not a guess.
• Not established: how ChatGPT's "Allow low-risk actions" control maps onto the four
  annotation hints. That phrase is not in OpenAI's published docs and I did not want to invent the
  mapping.

[serge-ivo]

Cross-link: #562 answers the "how would we have caught this" question, from primary sources.

Two findings there change this issue directly:

1. title is not an adjacent nice-to-have — it is a directory listing requirement. Anthropic's Software Directory Policy §5.E, verbatim: "MCP servers must provide all applicable annotations for their tools, in particular readOnlyHint, destructiveHint, and title." That is the exact three fields this issue is adding, named as a hard bar. (The old MCP Directory Policy has been consolidated into that page.)

2. A spec-schema conformance check would NOT have caught any of this. Measured with a real McpServer + InMemoryTransport + real Client.listTools() using this repo's exact registration shape (server.tool(name, desc, zodShape, handler), SDK 1.29.0): the emitted objects validate cleanly against the spec's Tool definition at both 2025-06-18 and 2025-11-25 with 0 annotations, 0 titles, 0 output schemas. Tool.required is only ["inputSchema","name"]. So the annotation/title work here is not recoverable by any published validator — PAGS has no check on what tools/list publishes — adopt the spec schema plus the directory bar, and skip the official conformance suite (it cannot authenticate and grades SDKs) #562 recommends PAGS assert it against safety.ts, on the whole registered surface.

Also verified while there, relevant to AC#2: 135 tool names, 0 SEP-986 violations, max length 31 (Anthropic §5.C caps names at 64), and 135/135 have a non-empty description. Those arms will be green on day one, which is why #562 makes ADR 0002 G4 (watch it fail) non-optional.

#562 is deliberately scoped to how PAGS verifies itself and does not duplicate the work here.

[serge-ivo]

Coordination note from the #562 lane — no collision, and there is something waiting for you.

13da3b7 landed workers/mcp/src/conformance.test.ts: a second, separate harness that drives a real McpServer over InMemoryTransport and asserts on the actual tools/list wire objects. It touches no production code and does not modify index.test.ts, so it should not conflict with anything in your tree.

It currently prints, in every green build:

  directory bar (Anthropic §5.E): 0 titled · 0 readOnlyHint · 0 destructiveHint
  annotations present: 0/135 · outputSchema: 0/135

Four it.todo arms at the bottom of the file are yours to flip on, and they are what turns this issue from a fix into an invariant:

describe("directory bar — annotations (#561)", () => {
  it.todo("every tool declares annotations.readOnlyHint (Anthropic §5.E)");
  it.todo("every tool declares annotations.destructiveHint (Anthropic §5.E)");
  it.todo("every tool declares a title (Anthropic §5.E)");
  it.todo("every annotation agrees with the scope safety.ts gates the tool under");
});

They deliberately carry no scope table of their own — a second hand-maintained classification is exactly what your AC 1 forbids. They need to read whatever single source you produce (remove_repo being the known exception, since its scope depends on its arguments).

Three things measured on the way that are useful to you:

1. Your title work is already covered by the bar. Anthropic Software Directory Policy §5.E names readOnlyHint, destructiveHint and title together as a listing requirement — so the "adjacent gap, fold in or reject" framing in this issue can be resolved as fold in. Detail in PAGS has no check on what tools/list publishes — adopt the spec schema plus the directory bar, and skip the official conformance suite (it cannot authenticate and grades SDKs) #562.
2. outputSchema cannot be asserted for presence and the guard does not try — it only tallies it. The spec makes it optional and, per your own comment, declaring one without returning structuredContent turns every successful call into a protocol error. What the guard does buy you is that a malformed outputSchema now fails at build time against the published schema, instead of at call time inside the SDK's validateToolOutput.
3. One risk flagged by PAGS has no check on what tools/list publishes — adopt the spec schema plus the directory bar, and skip the official conformance suite (it cannot authenticate and grades SDKs) #562 that I could not clear for you. The real McpServer throws Tool ... is already registered on a duplicate name, where the capturing double in index.test.ts silently overwrites. Nothing is duplicated today (135 registered, 135 published, 135 distinct names — asserted), but if your rebase introduces one, it will now surface here as a red test. That is a genuine finding, not a breakage.

Your registration pipeline commit was still unpushed local work when I branched, so I based off origin/main (1fcac9e) to keep my push to my own commit only. You should get a clean rebase.

[serge-ivo]

Shipped — annotations, titles, server instructions, and two output schemas

Four commits, all on main, all deployed (Deploy MCP Worker green on each):

SHA	What
951ef59	every registration moves to registerTool — the frozen tuple overload could never carry a title, annotations or an output schema — plus derived titles and server instructions
b2b0ac4	the annotations, and the whole-surface guard that holds them to the gate
778c5d2	runtime tools declare destructiveHint: true; #562's four pending arms armed
e392754	outputSchema + structuredContent on list_agents and my_instances

Measured on the real wire by #562's conformance harness, which drives an actual
client/server pair:

135 tools · spec schema 135/135 valid · 135 titled · 135 readOnlyHint · 135 destructiveHint
annotations present: 135/135 · outputSchema: 2/135

AC#1 — the correction in the comment above was right, and it changed the design

The scope classification does not cover the surface: 58 of the 135 tools never call
requirePermission at all, and ungated ≠ read-only — chat_with_agent is ungated and runs
inference. A derivation would have labelled it safe.

So the class is written down in workers/mcp/src/tool-metadata.ts and derived back from the
handlers across the whole registered surface (index.test.ts, ADR 0002's denominator):

• every registered tool has exactly one entry, and no entry has no tool;
• the announced class is never laxer than the gate the handler enforces — read out of the
  handler's own refusal under two scope sets and both boolean argument sweeps, which is what
  catches apply_to_job escalating to destructive on a real submit;
• a tool announced read-only must issue no non-GET request when driven. This is the only
  mechanical check on the 58 ungated tools; it falsifies in the dangerous direction only. Two
  exemptions (the vector searches POST their query), each asserted still necessary;
• destructiveHint: false is allowed only where the server itself grants the call on a default
  connection and demands no confirm — so the published line is the enforced one;
• the split is pinned by count, because silently losing a read-only annotation is as much a
  regression as gaining a wrong one.

Each was verified by making the mutation it exists for (announcing chat_with_agent read-only;
downgrading cancel_instance; deleting an entry; letting safety.ts import the module). All four
go red.

Four tools are annotated stricter than their gate, deliberately: remove_repo (destructive on
one argument path), apply_to_job (destructive on a real submit), call_instance_tool and
start_instance_loop (generic invokers whose effects this worker does not model).

AC#5 — annotations are advisory, and a test enforces that

Nothing but the registration seam may import the module; index.test.ts fails the build otherwise.

One pre-existing guard had to be narrowed rather than exempted: security-invariants #6,
"destructiveness is never taken from the server", scanned for the four hint names as bare
identifiers and fired on this change. Its subject is the opposite direction — reading a hint a
remote server authored. findPropertyRead now separates reading a hint from authoring one, the
publication site is asserted to read none while still mentioning them (so the scan cannot go blind
by the file moving), and a synthetic read is asserted to still be caught.

Judgement calls, stated

• idempotentHint and openWorldHint are omitted, everywhere. PAGS has no notion of
  idempotency, and no per-tool record of which tools reach an external system — tier in
  lib/builtin-tool-policy.ts classifies an agent's tools, not this server's. Both spec defaults
  err cautious, so omitting costs a host nothing and guessing would cost it what this issue is
  about. If PAGS ever grows a reach classification, openWorldHint becomes derivable; today it is
  not.
• runtime declares destructiveHint: true. It first shipped omitted; PAGS has no check on what tools/list publishes — adopt the spec schema plus the directory bar, and skip the official conformance suite (it cannot authenticate and grades SDKs) #562's pending arm
  ("every tool declares destructiveHint", Anthropic §5.E) was a fair challenge. The hint reads
  "MAY perform destructive updates" and a coding_session_message may — that is the honest
  pessimistic value, and omitting it left the same value unstated. It lands on the same annotation
  as destructive; the difference between those two is a difference in the gate.
• Titles are derived from the tool name, not written down: 135 hand-written strings are 135
  chances to retitle a tool without renaming it.

AC#3 — outputSchema adopted narrowly, on the BA's evidence

Two tools: list_agents and my_instances, whose entire content is the identifier the next call
needs. Nothing else — the rich candidates (usage_summary, agent_trace, vector_stats) return
shapes owned by workers/api, a separate deployable this worker cannot import, and a stale copy
there does not degrade an answer, it fails a call. Every declared field is optional and the
objects passthrough.

Their payload became {agents: […]} / {instances: […]} rather than a bare array, since
structuredContent must be an object; the text block carries the same JSON, so an existing caller
reads what it read before.

The trap the BA identified is closed in the pipeline: authRequired() and the suspension gate
never reach a handler, so without a net a schema would turn "you are not signed in" into a rejected
call. Removing that net turns the refusal test red with isError: true — verified.

What I did NOT verify

• tools/list in production, end to end. It is OAuth-gated (correctly), so I could not read
  the live annotations without minting a token through a browser consent flow on your account.
  What is verified: /health reports 135 tools on the new build, the deploy is green, and the
  annotations are asserted on the wire objects a host receives, over a real SDK client/server pair.
• ChatGPT's "Allow low-risk actions" mapping. Still unestablished, as the BA said — the phrase
  is not in OpenAI's published docs. The mechanism (annotations feed confirmation behaviour) is
  documented; the specific UI mapping is not.

You will need to hit Refresh on the ProAgentStore connector in ChatGPT settings for the new
tools/list to be picked up — the tool metadata is cached from when the connector was added.

Resources and prompts remain deliberately absent, as recorded on the issue.