Metis

Official

by BrightbeamAI

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Report a divergence from procedure

submit_observation

Idempotent

Report observed work done differently from the written procedure so Metis drafts a question for the worker and captures the reply as practice knowledge.

Instructions

Report where a worker's action differed from the written procedure; Metis drafts one short question (a whisper) for you to put to that worker. Use it when you see or are told that work was done differently from the SOP, and relay the worker's reply with answer_whisper; to dispute a stored fragment, use contest_fragment. Metis infers a candidate account (a hypothesis) and stores no fragment until the worker answers. A worker gets at most five whispers in eight hours by default; past that budget the call returns deferred, asks nothing, and spends the id, so report it again later under a new observation_id. A retry with the same observation_id, worker, and work_as_done returns the whisper while it awaits an answer; any other report under a used id is refused. Identities are not verified here, so give the worker's real URI.

Input Schema

TableJSON Schema

Name	Required	Description
`title`	No	A short title for the candidate fragment. Metis drafts one when omitted.
`worker`	Yes	The worker to ask, as their participant URI. Only a person (human:...) is asked.
`context`	Yes	The situation the worker was in when the practice was observed.
`category`	No	The kind of tacit knowledge, from the K1 to K17 taxonomy in the metis://taxonomy resource. Metis infers one when omitted.
`work_as_done`	Yes	What the worker did, in plain words, as observed or reported.
`observation_id`	Yes	Your stable id for this observation, such as a work-order number. Reuse it when you retry, so the worker is asked once; a deferral or an answer spends it.
`work_as_imagined`	No	What the written procedure says should happen, when you know it.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	Yes	What to do next.
`reason`	No	Why the capture was deferred.
`worker`	No	The worker who is asked.
`options`	No	The answers the worker can give.
`deferred`	Yes	True when the worker had reached the whisper budget and nothing was asked.
`question`	No	The question to put to the worker.
`repeated`	No	True when this observation was reported before and its whisper is returned again.
`candidate`	No	The candidate account Metis inferred, for the worker to confirm or correct.
`whisper_id`	No	The whisper's id, for answer_whisper.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.6Oct 5, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: it discloses the at-most-five-whispers-per-eight-hours budget, that exceeding it returns 'deferred' and spends the id, that no fragment is stored until the worker answers, that certain retries are refused, and that identities are not verified here. This is exactly the kind of GIGO/precondition detail annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and alternative, and every sentence carries operational weight (budget, deferral, retry, refusal). It is dense and long, but no sentence is filler; a small trim of the retry/refusal clauses could tighten it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, stateful, side-effecting tool with an output schema, the description covers the full lifecycle: what is stored, when, what is returned (a whisper or deferred), retry semantics, and failure modes. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics on top: observation_id must be reused on retry so the worker is asked once, and worker must be a real human URI because identity is unverified. The other five parameters' meaning is left entirely to the already-verbose schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('report where a worker's action differed from the written procedure') and immediately names the artifact produced (a drafted whisper). It also distinguishes itself from the sibling contest_fragment by naming that alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('when you see or are told that work was done differently from the SOP'), the follow-up tool (answer_whisper), and the boundary case ('to dispute a stored fragment, use contest_fragment'). When-to-use, what-to-do-next, and the alternative are all stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server