You can run proactive triage, document compliance, grounded retrieval, human approval, and cost enforcement for autonomous agents via MCP tools.
Claim unprocessed events under time-boxed leases; complete, release, or push events.
Evaluate document compliance with missing-field, regex, confidence, and risk reporting.
Query an in-repository TF-IDF corpus for ranked knowledge with grounding verdict.
Request human approval tickets and verify single-use HMAC-SHA256 confirmation codes.
Track token spend and enforce per-session USD budgets server-side.
Select the active session charged by the budget guard.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@proactive-agent-mcp Poll the event queue for unhandled high-severity alerts and summarize them."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server in Python that exposes a proactive triage queue, document compliance validation, grounded knowledge retrieval, and server-enforced guardrails for autonomous agents. Speaks JSON-RPC 2.0 over stdio.
Proactive triage with leases. poll_event_queue claims unprocessed events and takes a time-boxed
lease on each. If the agent dies mid-triage the lease lapses and the event returns to the queue.
complete_event and release_event settle or hand back work explicitly.
Document compliance evaluation. evaluate_document_compliance checks extracted document fields
against a declared schema, reporting missing fields, regex violations, a confidence score, and a
risk level.
Grounded retrieval. query_rag_knowledge ranks an in-repository corpus with sparse TF-IDF
vectors and cosine similarity, returning measured latency and an explicit grounding verdict.
Human-in-the-loop gates. request_human_approval parks a sensitive action behind an
HMAC-SHA256 signed ticket. verify_approval_token checks a supervisor's confirmation code.
Cost enforcement. track_cost_budget books token spend, and the server refuses further tool
calls for any session that has exhausted its budget.
Related MCP server: agentbus
+--------------------------------------------------+
| Client (Claude Desktop / Cursor / IDE) |
+----------------------+---------------------------+
|
| JSON-RPC 2.0 over stdio
v
+--------------------------------------------------+
| proactive-agent-mcp |
| |
| server.py dispatch, negotiation, budgets |
| protocol.py JSON-RPC + MCP primitives |
| validation.py pydantic argument enforcement |
| |
| tools/ triage, compliance, knowledge, |
| guardrails (HITL + cost) |
| resources/ system://health, compliance://standards
| prompts/ autonomous_triage_loop, |
| compliance_audit_brief |
+--------------------------------------------------+The event queue and knowledge corpus are in-memory reference implementations. They reset on restart and are not shared between replicas.
git clone https://github.com/MishaelOliva/proactive-agent-mcp.git
cd proactive-agent-mcp
pip install -e ".[dev]"
python -m proactive_agent_mcp.serverTo watch a full triage session, including the human-approval round trip and budget enforcement:
python examples/run_client_demo.py{
"mcpServers": {
"proactive-agent": {
"command": "python",
"args": ["-m", "proactive_agent_mcp.server"],
"env": {
"PYTHONUNBUFFERED": "1",
"MCP_SIGNING_SECRET": "generate-with-openssl-rand-hex-32"
}
}
}
}.cursor/mcp.json){
"mcpServers": {
"proactive-agent": {
"command": "python",
"args": ["-m", "proactive_agent_mcp.server"],
"env": {
"MCP_SIGNING_SECRET": "generate-with-openssl-rand-hex-32"
}
}
}
}Variable | Purpose | Default |
| Key for HMAC-SHA256 approval codes. Set this. An unset value produces a random per-process secret and logs a warning, so tokens do not survive a restart. | random, per process |
| Default per-session spend ceiling. |
|
| Log level for the stderr stream. |
|
| Flush stdout so responses are not buffered. |
|
Tool | Purpose |
| Claim events under a lease. |
| Settle a claimed event. |
| Return a claimed event to the queue. |
| Record an observation onto the queue. |
| Validate extracted document fields. |
| Rank the corpus by TF-IDF cosine similarity. |
| Park a sensitive action for human authorization. |
| Verify a supervisor's confirmation code. |
| Book token spend against a session. |
| Choose which session the budget guard charges. |
The human-in-the-loop gate is a worked pattern, not a production authorization system. What it does guarantee:
Approval codes are full 256-bit HMAC-SHA256 values, base32-encoded for legibility. They are not truncated.
The signed payload binds the ticket id, action name, a SHA-256 digest of the action parameters, and the absolute expiry. A code cannot be re-pointed at a different action, swapped for different parameters, or replayed after expiry.
The code is recomputed at verification time rather than read from a stored expected value, so a tampered ticket record invalidates its own code.
Tickets are single-use, compared in constant time, and garbage-collected once settled.
The confirmation code is never returned by request_human_approval. It must arrive through a
channel the agent cannot reach.
The signing secret has no hardcoded default. With MCP_SIGNING_SECRET unset, a random secret
is generated at start-up, so a code cannot be derived from knowledge of this repository.
What it does not guarantee, and what a real deployment must add:
Binding approvals to an authenticated human principal. The gate proves a holder of the secret approved, not who.
Surviving a restart or spanning replicas. Tickets live in process memory.
An authenticated delivery channel for the confirmation code.
Protection against a sufficiently privileged caller with in-process access.
The budget guard enforces rather than advises: once a session exceeds its ceiling, the server refuses non-guardrail tool calls. Accounting tools stay reachable so the agent can report honestly rather than dead-ending.
python -m unittest discover -s tests -t .116 tests covering protocol conformance (initialization gating, notification suppression, version negotiation, batching, pagination, error codes), tool behaviour, the HITL security properties, budget enforcement, and an end-to-end stdio session against a real subprocess.
Several tests are explicit regression guards for defects fixed in v1.1.0: a confidence score that capped a perfect document at 0.571, a hardcoded retrieval latency, a forgeable approval secret, a mid-session budget change that was silently ignored, and an event queue that stranded work when an agent crashed.
CI runs the suite on Python 3.10-3.12 with and without MCP_SIGNING_SECRET set, lints with ruff,
verifies the wheel installs in a clean environment, and smoke tests the container entrypoint.
Single process. State is in memory, so the event queue, tickets, and budget ledger reset on restart and are not shared across replicas.
stdio only. Streamable HTTP transport is not implemented.
Lexical retrieval. TF-IDF cosine matches vocabulary, not meaning. Paraphrased queries retrieve poorly. Dense embeddings would be the natural upgrade; the interface would not change.
Deterministic compliance. Field and regex validation only. It says nothing about whether extracted values are truthful.
Illustrative pricing. MODEL_PRICING in tools/guardrails.py is a static table that needs
periodic refreshing. Treat it as configuration.
MIT.
Built by Mishael Oliva • LinkedIn
Settle a claimed event with an outcome and an optional note. Use this once triage of an event has finished.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| outcome | No | PROCESSED | |
| event_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the mutation profile is known. The description adds the precondition that the event must be 'claimed' and that the note is optional, but says nothing about what happens to the event afterward, required permissions, or whether triage state is discarded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler; the what and the when are front-loaded in that order. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and annotations cover idempotency. However, for a state-transition tool the description omits enum semantics and the post-settle state of the event, leaving meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It names both 'outcome' and 'optional note', which is useful, but it never explains the enum values (PROCESSED, ESCALATED, DISCARDED) or the meaning/format of event_id, leaving the most consequential parameter semantics undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('settle') and resource ('a claimed event') with the two inputs (outcome, optional note). It is clearly distinct in intent from siblings like poll_event_queue or release_event, though it never names or contrasts them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this once triage of an event has finished' gives a clear triggering condition, so an agent knows the lifecycle stage at which to call it. No alternative (e.g. release_event vs. settling) or exclusion is mentioned, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check an extracted document against a declared schema. Reports missing required fields, pattern violations, a confidence score, and a triage verdict. This is deterministic field validation over regex rules, not document understanding.
| Name | Required | Description | Default |
|---|---|---|---|
| schema_type | No | asset_handover | |
| strict_mode | No | When true a pattern violation fails the document; when false it is downgraded to a warning. | |
| document_payload | Yes | Key-value fields extracted from the document. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds valuable context beyond that: the check is deterministic field validation over regex rules rather than semantic document understanding, which sets agent expectations about false negatives on unseen formats. No pagination or input-size limits are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with what it does, followed by returns and a scope caveat. Every sentence carries distinct information; nothing is redundant with the name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, yet the description still summarizes them usefully. Combined with the safety annotations and the determinism caveat, an agent has enough to invoke it correctly; only the schema_type enum semantics remain unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: strict_mode and document_payload are described in-schema, but schema_type's enum has no description. The description references the schema selection and pattern behavior generically but adds no detail on schema_type choices or how strict_mode interacts with the reported verdict. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Check an extracted document against a declared schema') and enumerates the concrete outputs (missing required fields, pattern violations, confidence score, triage verdict). The sibling tools are unrelated domains (event queue, RAG, approvals), so no differentiation is needed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'Check an extracted document against a declared schema' but there is no explicit when-to-use/when-not guidance or routing to an alternative. The closing sentence scopes what the tool is not ('not document understanding'), which helps avoid misuse but stops short of usage directions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim unprocessed events from the proactive triage queue and take a time-boxed lease on each. Events whose lease lapses return to the queue automatically, so a crashed agent does not strand work.
| Name | Required | Description | Default |
|---|---|---|---|
| max_items | No | ||
| queue_name | No | default | |
| lease_seconds | No | ||
| filter_severity | No | all |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations give the safety profile (readOnlyHint=true, idempotentHint=false, destructiveHint=false), and the description adds genuinely new behavioral detail: leases are time-boxed and auto-return on lapse so a crashed agent doesn't strand work. It doesn't explain what 'claimed' state means for other consumers, so not a 5. Note the mild tension between 'claim' (a state change) and readOnlyHint=true, but the auto-expiring lease makes this defensible rather than contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the core action, followed by the one piece of behavioral nuance an agent needs. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described. However, with zero schema description coverage, the agent cannot learn the meaning of the four input parameters from the definition or the schema, leaving a real gap for a tool with filtering and batching controls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for four parameters (max_items, queue_name, lease_seconds, filter_severity), so the description must carry the load — but it names none of them. 'Time-boxed lease' loosely gestures at lease_seconds, yet max_items, queue_name, and the severity filter are entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: 'Claim unprocessed events from the proactive triage queue'. It also names the scoping mechanism (time-boxed lease), which cleanly separates it from siblings like push_event, complete_event, and release_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (pulling work off the queue) and explains lease-lapse behavior, but never states when NOT to use it or which sibling to prefer (e.g., release_event vs complete_event). Usage is inferable but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record an observation the agent made onto the triage queue so it becomes visible to other workers. Rejected when the queue is full.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | agent_proactive_runtime | |
| payload | Yes | ||
| severity | Yes | ||
| event_type | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply idempotentHint=false and destructiveHint=false, so the description carries real extra weight: it discloses the propagation effect (visible to other workers) and a failure mode (rejection when the queue is full). It does not connect the non-idempotent hint to duplicate risk on retry, which would have earned a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the action and its effect, with the failure condition appended. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need no explanation, and the queue-full behavior is covered. But with 0% schema description coverage and a nested payload object, the agent gets no guidance on what to put in the four parameters, leaving a substantial gap for a 3-required-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 4 parameters, and the description mentions none of them: event_type, severity (with its enum), payload, or the source default. The word 'observation' only loosely gestures at payload, so the description fails to compensate for the documentation gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Record') and resource ('observation ... onto the triage queue') plus the effect (visible to other workers). This clearly separates it from siblings like poll_event_queue and complete_event, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage ('an observation the agent made') and gives one constraint ('Rejected when the queue is full'), but never states when to prefer this over poll_event_queue, complete_event, or release_event, nor any prerequisite or conflict conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank the built-in knowledge corpus against a query using sparse TF-IDF vectors and cosine similarity. Lexical rather than semantic: it matches vocabulary, so paraphrased queries retrieve poorly. Returns measured retrieval latency and an explicit grounding verdict.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No | ||
| min_score_threshold | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), so the bar is lower. The description adds meaningful behavioral context beyond that: it discloses the lexical matching limitation and mentions that the response includes retrieval latency and a grounding verdict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action, then the important limitation, then the return shape. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema means return values need not be fully explained, and the description usefully notes latency and grounding verdict. But with 0% schema coverage, it should have described the tuning parameters (top_k, min_score_threshold) to make invocation unambiguous — that omission leaves a real gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and there are three parameters, yet the description only indirectly references 'query' and says nothing about 'top_k' or 'min_score_threshold'. An agent gets no guidance on what these parameters do or how to set them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (rank), resource (built-in knowledge corpus), and method (sparse TF-IDF vectors, cosine similarity). This clearly distinguishes it from the sibling tools, which handle events, compliance, approvals, and budgets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies intended usage (querying the corpus for lexical matches) and warns that paraphrased queries retrieve poorly, which is useful context for deciding when to use it. However, it never explicitly states when to choose this tool over alternatives or what prerequisites exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a claimed event to the unprocessed pool without settling it, so another worker can pick it up immediately instead of waiting for the lease to lapse.
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by explaining that the event returns to the unprocessed pool without settlement and becomes immediately available to another worker, which is meaningful beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action, effect, and benefit without any wasted words. It is appropriately sized for a simple one-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter schema, existing annotations, and an output schema, the description is largely complete for purpose and behavior. The main gap is the lack of detail about the event_id parameter and any error conditions, but no major operational information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single required parameter event_id has no documented format, constraints, or meaning in the description. While the name implies a claimed event identifier, the description adds no semantic detail beyond what the schema already shows.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: returning a claimed event to the unprocessed pool. It also distinguishes itself from settling tools like complete_event by saying 'without settling it,' so an agent can identify its distinct role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use: release a claimed event so another worker can pick it up immediately instead of waiting for the lease to lapse. It does not explicitly name when to use a sibling like complete_event instead, but the implied alternative is clear from 'without settling it.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Park a sensitive action behind a human decision and return an authorization ticket. The confirmation code is never returned here: it must be supplied by an authorized human over an authenticated out-of-band channel, otherwise the gate proves nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| urgency | No | normal | |
| rationale | Yes | ||
| ttl_hours | No | ||
| action_name | Yes | ||
| action_parameters | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, and the description does not contradict them: it explicitly frames the tool as not executing the action. Beyond the annotations it adds a genuinely non-obvious behavior, that the confirmation code is never returned here and must arrive over an out-of-band channel. It stops short of describing ticket lifetime or reuse behavior, which ttl_hours and idempotentHint=false leave open.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no padding, with the purpose front-loaded and the security caveat second. The second sentence is doing real work by preventing an agent from believing the code comes back in the response.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so ticket contents need not be spelled out, and the description usefully clarifies what is NOT returned. But for a five-parameter tool with a nested object, zero schema description coverage is a real hole, and the missing link to verify_approval_token leaves the overall approval workflow incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across five parameters, including a nested action_parameters object and the urgency enum, so the description carries the full burden. It mentions no parameter at all, offering only the abstract notion of a 'sensitive action'. An agent must open the schema to learn that action_name, action_parameters and rationale are required, and ttl_hours/urgency are not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: parking a sensitive action behind a human decision and returning an authorization ticket. That is far more than a restatement of the name. However, it never distinguishes itself from the sibling verify_approval_token, which an agent must know is the downstream counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (use this to gate sensitive actions) but never stated as explicit when/when-not guidance, and no alternative or follow-up tool is named. With verify_approval_token sitting among the siblings, the omission of the two-step workflow leaves the agent to infer the sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Select which session the server's budget guard charges. The server refuses non-guardrail tool calls for any session that has exhausted its budget.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as non-read-only but idempotent and non-destructive, and the description corroborates that by describing a server-side selection. Beyond the annotations it adds genuine context: the chosen session is what the budget guard charges, and budget-exhausted sessions cause the server to refuse other tool calls. It omits persistence/lifetime of the selection and whether the session_id must be validated as existing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the primary action is front-loaded ahead of the consequence. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. The description covers the core behavioral effect on other calls, which is what an agent most needs. Minor gaps remain around session_id provenance and whether the setting persists across calls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single parameter, so the description must carry meaning for session_id. It does partially: it defines the session as the one the budget guard charges, which is more than the bare string/maxLength schema says, but it gives no format, source, or lookup guidance (e.g., how to obtain a session_id).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: selecting the session whose budget the server's guard charges. This is distinct from every sibling tool (event queue, compliance, RAG, approvals, cost tracking), so an agent can identify it without opening the schema. It stops short of 5 only because the title is null and the phrasing 'select which session' leaves the write-to-server-state aspect slightly implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the second sentence conveys the consequence of the selection (budget-exhausted sessions block non-guardrail calls), which gives context for when this matters. However it names no alternative, no prerequisite (e.g., whether the session must already exist), and no explicit when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Book token spend against a session budget. Once a session exceeds its budget the server refuses further tool calls for it until the budget is raised; enforcement is server-side, not advisory.
| Name | Required | Description | Default |
|---|---|---|---|
| model_name | No | gemini-2.0-flash | |
| session_id | Yes | ||
| prompt_tokens | Yes | ||
| completion_tokens | Yes | ||
| session_budget_usd | No | Session ceiling in USD. Applies immediately, including mid-session. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are thin (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries real weight. It discloses the critical behavioral trait: enforcement is server-side and blocking, refusing further tool calls until the budget is raised, and is 'not advisory.' That is exactly the kind of consequence an agent cannot get from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, and the enforcement consequence is front-loaded right after the core purpose. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be explained, and the behavioral consequence is well covered. However, the near-total absence of parameter semantics for a 5-parameter tool leaves a material gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only session_budget_usd is documented). The description mentions no parameters at all, so session_id, prompt_tokens, completion_tokens and model_name remain undocumented in both places, leaving the agent without token-accounting guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Book token spend against a session budget.' It is unambiguous and, since no sibling tool touches budgets, the agent can identify it immediately without needing sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the bookkeeping role and explains the consequence of exceeding budget, but never says explicitly when to invoke it (e.g., after each model call) or names any alternative or prerequisite. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a supervisor's confirmation code against a ticket and consume the ticket on success. The code is bound to the action name, a digest of the action parameters, and the expiry, and each ticket is single-use.
| Name | Required | Description | Default |
|---|---|---|---|
| ticket_id | Yes | ||
| confirmation_code | Yes | Hyphen grouping is optional; the code is case-insensitive. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses critical behavior: the ticket is consumed on success, each ticket is single-use, and the code is bound to the action name, a digest of action parameters, and the expiry. These details are essential for safe invocation and are not available elsewhere.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences front-load the primary action and then add essential binding and single-use constraints. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, annotations, and output schema together make the tool's behavior clear enough. It covers the main mutation and its ticket-consuming effect, though explicit failure behavior and prerequisite guidance are not stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 50% schema description coverage, the description compensates by clarifying that ticket_id represents a ticket and that confirmation_code is validated against the action name, parameter digest, and expiry. It adds substantial meaning, though ticket_id format details remain unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (verify), resource (supervisor's confirmation code against a ticket), and the post-success side effect (consume the ticket). It is immediately distinguishable from sibling tools like request_human_approval and complete_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the mechanics of verification but gives no explicit guidance on when to call this tool versus alternatives. It does not mention prerequisites such as first obtaining a ticket via request_human_approval or what happens when a ticket is invalid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.0complete_eventevaluate_document_compliancepoll_event_queuepush_eventquery_rag_knowledgerelease_eventrequest_human_approvalset_active_sessiontrack_cost_budgetverify_approval_tokenScored across 10 tools
The tools cluster into four clear domains: event-queue lifecycle (poll/complete/release/push), approval (request/verify), budget (track/set_active_session), and two standalone capabilities (compliance, RAG). complete_event vs release_event could be momentarily confused, but the descriptions clearly distinguish settling from returning to the pool. set_active_session and track_cost_budget are related but have distinct roles.
Every tool follows a consistent verb_noun snake_case pattern (poll_event_queue, complete_event, verify_approval_token, track_cost_budget, etc.). No mixed conventions or vague verbs anywhere in the set.
Ten tools is well within the sweet spot for a triage/guardrail agent, and each tool earns its place by covering a distinct operation rather than duplicating another. No bloat or thin coverage.
The event queue has full lifecycle coverage (push/poll/complete/release), approval has request+verify, and budget has tracking plus session selection. Minor gaps like inspecting queue depth or listing pending events exist, but agents can work around them via polling.
Connect, monitor, and control AI agents — tasks, approvals, schedules, and governance.
Deterministic compliance and vertical knowledge bases for autonomous agents. Free 24hr trial.
Tenant-scoped control layer for agent-to-agent systems: governed routing, approvals, evidence.
Register every AI agent, log every action, prove it. EU AI Act compliance built in.
