Skip to main content
Glama
joy7758

titmas-agent-action-gate

by joy7758
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

TITMAS Agent Action Gate

这是一个真正会阻止不可靠代码变更合并的证据闸门。

It is an evidence gate that returns a non-passing required check when tests, exact-head evidence, policy, or required approval do not hold.

Contract checks

TITMAS Agent Action Gate is an experimental competition demo candidate for the GOAI 2026 Agent Infra track. It separates uncertain agent analysis from deterministic authorization, evidence verification, policy evaluation, and human approval.

Current product status: PUBLICLY_REPRODUCIBLE_MERGE_BLOCKING_PRODUCT for the bounded GitHub reference surface. The 8/8 acceptance proof is retained in demo/evidence/merge-blocking-public-proof-20260812.json: a public required check blocks commit-A evidence against pull-request head B while ordinary CI passes, then passes after the evidence subject is corrected, with receipts, summaries, and an approximately 90-second public recording. This does not prove production readiness, large-scale agent concurrency, agent-to-agent production governance, certification, compliance, or complete M4 autonomy. The historical bounded Alibaba Cloud official Skill sub-milestone remains COMPLETE, while full M4 remains INCOMPLETE and is outside the current work scope.

The deterministic Action Gate, append-only state store, pinned agent-evidence adapter, authenticated native MCP boundary, six-role target topology, and allowlisted in-memory GitHub provider adapter are implemented in the current worktree. A bounded public sandbox run previously created a branch and Draft PR. On 2026-08-02, a historical isolated deployment of official AgentTeams v1.2.0 started one Manager and five Workers; it remains operator-supervised negative evidence. A separate disposable cloud-context-inspector ran one native Qwen Worker turn: it resolved the externally installed official Alibaba Cloud Resource Center Skill, verified the source-lock digest, invoked the frozen typed read-only adapter, and returned EMPTY_RESULT as NOT_ASSESSED_NO_VISIBLE_RESOURCE. The retained chains and canonical agent-evidence receipt validate, while Worker decision records and Resource Center write calls remain zero. This proves only the bounded specialist turn, not a complete cloud inventory, broader autonomous M4 completion, or deployment authorization.

This repository is not submitted to, endorsed by, or affiliated with GOAI, and it makes no certification, compliance, production-readiness, or security guarantee.

Merge-blocking PR check

The new bounded path is:

exact PR head + task-bound test command
  -> test and negative checks
  -> pinned agent-evidence verification
  -> deterministic policy and approval evaluation
  -> ActionGate ALLOW | BLOCK | REQUIRE_APPROVAL
  -> public required-check state + receipt + summary

The public projection does not change internal Action Gate authority:

Public check state

Internal basis

Process exit

PASS

ALLOW

0

FAIL

BLOCK for an invalid, denied, failing, tampered, or mismatched input

nonzero

INCOMPLETE

BLOCK / EVIDENCE_MISSING

nonzero

REVIEW_REQUIRED

REQUIRE_APPROVAL

nonzero until a scoped approval verifies

Every normal invocation in a fresh job writes artifacts/titmas/receipt.json and artifacts/titmas/summary.md, including repository, PR, exact head SHA, frozen-input digests, execution identity reference, test result, negative checks, authorization scope, evidence digest and verifier, risk, approval reference, internal decision, public state, reasons, time, and tool/policy versions. Empty create-only, no-follow output inodes and their directory identity are reserved before the test; ancestor symlinks, inode identity, regular-file metadata, link count, timestamps and empty content are checked independently for both outputs after the test. Trusted writes truncate and verify length, content and SHA-256 through the reserved descriptor before committing. Pre-existing, replaced or in-place contaminated paths fail closed and relocate trusted FAIL outputs instead of being overwritten or consumed.

titmas-action-gate verify-pr \
  --task .titmas/task.json \
  --evidence .titmas/evidence.json \
  --policy policies/github-merge-gate-low-risk-demo.v0.1.json \
  --test-command 'python -m unittest discover -s tests -v'

The task must be an existing action-request.v0.1 for github.pull_request.merge. Its parameters bind pull_request, head_sha, execution_identity, and the direct-exec test_command array; its resource reference is refs/pull/<number>/head@<sha>. The evidence must be produced by a trusted earlier step and bind that exact request. Before the untrusted test starts, the gate validates and freezes task, policy, evidence, optional approval, repository identity, pull-request number, exact head and relevant Action configuration in parent-process memory. It also requires the tracked index and worktree to equal that exact HEAD, permits only declared untracked inputs and output paths, and rejects effective repository/worktree Git credential or command configuration without retaining its values. Every already-initialized submodule and nested submodule is discovered from safe stage-zero gitlinks, audited recursively without initialization, update or network access, and its value-free configuration and state digests are frozen for a post-test comparison. The final decision consumes only frozen objects; any input, exact-head, effective Git configuration, initialized-submodule configuration or relevant Git-state drift during the test fails closed. A post-test security or Git observation that errors, times out, is incomplete, cannot be parsed or becomes unknown forces the policy fact to DENY before the deterministic Action Gate evaluates it.

The test command does not run through a shell. It receives only a minimal environment with PATH, locale, CI, a fresh temporary HOME and TMPDIR, and non-interactive Git controls. GitHub command files, OIDC, SSH, cloud and package-registry credentials are not inherited. Persisted effective repository/worktree/submodule Git authentication or command configuration and a pull_request_target event fail before the test. User-controlled gate paths reject empty, dot-traversal, outside-workspace absolute and symbolic-link ancestor paths before resolution; no-follow descriptor walks bind input reads and create-only outputs, and ancestor identities are rechecked after the test. Stdout and stderr share one server-owned 1 MiB aggregate capture budget; overflow terminates the process group and fails closed. The process boundary does not claim container, virtual-machine or production sandbox isolation. TEST_PROCESS_ISOLATION_NE_PRODUCTION_SANDBOX=true.

Consumer workflows must use a least-privilege exact-head checkout:

permissions:
  contents: read

steps:
  - uses: actions/checkout@<immutable-full-sha>
    with:
      ref: ${{ github.event.pull_request.head.sha }}
      fetch-depth: 0
      persist-credentials: false
  - uses: joy7758/titmas-agent-action-gate@<immutable-full-sha>

The root action.yml is the reusable composite Action. Consumers must pin an immutable full commit SHA and configure its job as a required check; PASS does not bypass any other GitHub rule. Run the no-network regression matrix with:

python scripts/replay_merge_gate_scenarios.py

It covers valid low-risk, failing-test, missing-evidence, high-risk unapproved, high-risk approved rerun, and commit-A-evidence/commit-B-head mismatch. The baseline gap list and its bounded closure record are in docs/P0-MERGE-BLOCKING-GAP-LIST.md.

Related MCP server: governed-mcp

Competition positioning

AI coding is moving from one assistant toward populations of agents operating across repositories at machine speed. The systemic risk is not that an agent can make one mistake, but that a mistaken task interpretation, unstable behavior, or unsupported claim can be handed onward and replicated quickly.

TITMAS answers with task, identity, authority, and evidence verification before effect. The current real proof is deliberately smaller than that long-term vision: one AI-generated code change is bound to its task, actor, authorization, exact commit, and evidence, and a mismatched change is genuinely blocked before merge.

GitHub manages repositories, workflows, tests, reviews, and merge rules. TITMAS uses those enforcement surfaces while checking a different question: whether the AI action is actually covered by the current task authorization and evidence. The GitHub merge gate is the first reference surface, not the final identity of TITMAS. Large-scale concurrency, production agent-to-agent governance, and prevention of error propagation at scale remain UNPROVEN.

我们不是防止 AI 犯错，而是防止 AI 把错误规模化。

Why this exists

Agents are useful at interpreting ambiguous requests, decomposing work, and explaining uncertainty. They should not be the component that silently grants their own authority. This project uses:

  • AgentTeams v1.2.0 for transparent Manager/Leader/Worker collaboration;

  • agent-evidence 0.6.0 as the canonical evidence packaging and verification dependency;

  • versioned JSON contracts and a deterministic Action Gate for ALLOW, BLOCK, and REQUIRE_APPROVAL;

  • a human approval record for scoped, high-risk actions;

  • provider MCP servers, such as GitHub MCP, only after an ALLOW decision.

AgentTeams team

AgentTeams Worker

Responsibility

Cannot do

workflow-lead

Route tasks and preserve handoffs

Decide authorization or execute GitHub writes

request-analyst

Normalize requests, risk signals, and uncertainty

Grant permission or validate its own output

evidence-verifier

Invoke the pinned agent-evidence verifier and return its receipt

Rewrite evidence or decide policy

github-operator

Execute an exact GitHub action after a matching ALLOW

Bypass the gate or approve releases

cloud-context-inspector

Request one typed, current-account Resource Center search and return sanitized context

Receive credential bytes, run arbitrary CLI/cloud operations, write cloud state, or decide the gate

release-steward

Assemble post-execution evidence and request the release decision

Merge, tag, or release without a new decision

Agent identities and intended tool boundaries are machine-readable in agents/registry.json. The reviewable deployment template is deploy/agentteams/team.v1.2.0.yaml; the non-idempotent macOS Docker Desktop smoke profile is deploy/agentteams/team.native-smoke.v1.2.0.yaml.

Native local smoke boundary

The retained machine-readable evidence is demo/evidence/agentteams-native-20260802.json. It records both the verified chain and the failures that prevent a stronger claim:

  • Qwen qwen3.8-max-preview specialist Workers invoked the real six-tool MCP endpoint; preview model availability is not a stable runtime contract;

  • agent-evidence 0.6.0 returned VALID, after which the deterministic gate returned a five-minute ALLOW that expired without execution;

  • the leader did not complete the workflow autonomously, one unrelated request entered the global store during concurrent prompts, and github-operator called a tool outside its declared registry allowlist;

  • all Workers shared the same MCP endpoint, so prompts described role boundaries but the smoke did not enforce per-Worker tool ACLs;

  • repository Skill names were declared in resources, but the run did not independently prove that those Skill packages were materialized inside the Workers.

This is native local orchestration evidence, not a persistent deployment, autonomous-workflow proof, least-privilege proof, or production-readiness evidence.

Deterministic decisions

Outcome

Meaning

ALLOW

The exact action, target, evidence, policy, and any required approval match. Execution may be attempted; success is not implied.

BLOCK

The request is malformed, denied, unsupported, missing required evidence, or has invalid/tampered evidence or approval.

REQUIRE_APPROVAL

Evidence and policy inputs are otherwise valid, but the risk class requires a scoped human approval before re-evaluation.

The decision contract and precedence rules are in specs/action-gate-decision-v0.1.md.

GitHub demo path

Agent request
  -> request analysis
  -> pre-action evidence verification
  -> deterministic Action Gate
  -> exact GitHub action after ALLOW
  -> official Alibaba Cloud read-only context preflight before a deployment-related release request is evaluated
  -> post-action evidence generation
  -> agent-evidence verification
  -> deterministic release decision
  -> human approval when required

The end-to-end scenario and retained public evidence are documented in docs/GITHUB-WORKFLOW-DEMO.md. The repository contains four reproducible runtime cases: valid execution, missing evidence, tampered evidence, and a high-risk release action requiring approval.

The historical adapter-only Alibaba Cloud evidence is demo/evidence/alibabacloud-resourcecenter-preflight-20260802.json. The later native Worker-turn evidence is demo/evidence/agentteams-native-alibabacloud-skill-20260802.json. The frozen four-file evidence set is demo/evidence/alibabacloud-evidence-set-freeze-20260802.json. Together they retain exact external Skill source verification, pinned CLI/plugin digests, same-profile live STS identity binding, the complete one-policy RAM attachment set, sanitized invocation trace, CLI exit 0, native AgentTeams Worker and Matrix receipts, replayable VALID agent-evidence, and scoped zero-write accounting. The Worker ZIP contains reference metadata but no upstream Skill bytes.

Run and validate

Python 3.11 or newer is required.

python3 -m pip install -e '.[dev]'
python3 scripts/validate_milestone.py
python3 scripts/validate_governance.py
python3 scripts/validate_alibabacloud_runtime_evidence.py
python3 scripts/validate_alibabacloud_evidence_set.py
python3 scripts/validate_native_agentteams_cloud_skill_evidence.py \
  demo/evidence/agentteams-native-alibabacloud-skill-20260802.json
python3 scripts/replay_merge_gate_scenarios.py
python3 -m unittest discover -s tests -v
python3 -m titmas_action_gate.cli evaluate-fixtures
python3 -m titmas_action_gate.cli demo --state-dir artifacts/runtime/local-demo
python3 -m titmas_action_gate.cli validate-install

Run a future real Alibaba Cloud preflight only through the runner's internal same-run RAM readback. It generates an unpredictable run ID and atomically reserves the evidence path before any provider call. It does not accept an external observation or credential bytes:

python3 scripts/run_alibabacloud_skill_evaluation.py \
  --control-profile '<RAM-readback-profile-label>' \
  --profile '<read-only-profile-label>' \
  --role-name '<read-only-role-label>' \
  --output '<new-evidence-path>' \
  --confirmation-ref '<explicit-user-confirmation-reference>'

The tests execute the deterministic engine, pinned agent-evidence validator, append-only chain, MCP stdio protocol, all six tools, AgentTeams-compatible local handoffs, in-memory provider workflow, native-smoke manifest/evidence checks, and negative boundaries. They do not prove persistent AgentTeams deployment, autonomous orchestration, production security, or operational readiness.

Start the MCP server over stdio:

TITMAS_ACTION_GATE_STATE_DIR='artifacts/runtime/mcp' \
TITMAS_ACTION_GATE_CALLER_TOKEN='replace-with-agent-token' \
TITMAS_ACTION_GATE_APPROVER_TOKEN='replace-with-distinct-approver-token' \
TITMAS_ACTION_GATE_DEMO_MODE='true' \
TITMAS_ACTION_GATE_MCP_TRANSPORT='stdio' \
  titmas-action-gate-mcp

The real GitHub runner requires a separately provisioned sandbox repository and exact local worktree. It is intentionally not part of default CI. See docs/RUNBOOK.md.

Repository map

Truth boundaries

AGENTTEAMS_ORCHESTRATION_NE_ACTION_AUTHORITY=true
AGENT_ANALYSIS_NE_POLICY_DECISION=true
EVIDENCE_NE_TRUTH=true
EVIDENCE_VERIFICATION_NE_ACTION_AUTHORIZATION=true
PUBLIC_CHECK_STATE_NE_INTERNAL_AUTHORITY=true
ALLOW_NE_EXECUTION_SUCCESS=true
MCP_TOOL_AVAILABILITY_NE_PERMISSION=true
SPECIFICATION_NE_IMPLEMENTATION=true
TEST_PASS_NE_PRODUCTION_READINESS=true
LOCAL_HANDOFF_HARNESS_NE_NATIVE_AGENTTEAMS_RUNTIME=true
NATIVE_LOCAL_SMOKE_NE_PERSISTENT_OR_PRODUCTION_DEPLOYMENT=true
OPERATOR_SUPERVISED_NE_AUTONOMOUS_END_TO_END=true
HASH_CHAIN_VALID_NE_SEMANTIC_ORCHESTRATION_CLEAN=true
PROMPT_ROLE_BOUNDARY_NE_ENFORCED_PER_WORKER_ACL=true
CLOUD_CONTEXT_NE_DEPLOYMENT_AUTHORIZATION=true
CLOUD_READ_SUCCESS_NE_COMPLETE_INVENTORY_OR_READ_ONLY_POLICY_PROOF=true
GITHUB_PR_CREATED_NE_GITHUB_PR_MERGED=true
COMPETITION_REPOSITORY_NE_COMPETITION_SUBMISSION=true
TITMAS_CORE_PROTOCOLS_CHANGED=false

License

Original project code is Apache-2.0. See LICENSE.

The externally installed third-party alibabacloud-resourcecenter-search subtree has SPDX-License-Identifier: NOASSERTION in this repository's source lock because upstream has no applicable license file and its README contains conflicting Apache-2.0 and MIT statements. Installation and byte provenance do not establish redistribution, derivative-work, commercial-use, or compatibility clearance. The subtree is absent from the repository, Worker packages, wheel, and sdist; it must not be included in a public commit or release. See governance/alibabacloud-resourcecenter-search-source-lock.json.

Available Tools

6 tools
attach_evidenceA

Attach an immutable in-scope evidence profile reference; does not verify or authorize it.

ParametersJSON Schema
NameRequiredDescriptionDefault
request_idYes
caller_tokenYes
profile_pathYes
evidence_typesYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It discloses that the attachment is immutable and that verification/authorization are not performed, which is useful. However, it does not explain side effects, error behavior, or the role of caller_token, leaving significant gaps for a mutation tool.

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

Conciseness5/5

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

The description is a single sentence that is front-loaded with the action and adds key limitations, with no wasted words.

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

Completeness2/5

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

Despite having an output schema, the description lacks details about prerequisites, error handling, or workflow integration. The four required parameters are only partially explained, and with no annotations, the tool is not fully understandable for an agent.

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

Parameters2/5

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

The schema has 0% description coverage, so the description must compensate. It provides some meaning (evidence profile reference implies profile_path) but leaves request_id and caller_token entirely unexplained. This is insufficient for a 4-parameter tool.

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?

The description uses a specific verb ('Attach') and resource ('immutable in-scope evidence profile reference'), clearly stating the action. It also differentiates from siblings by explicitly noting that it does not verify or authorize, contrasting with verify_evidence and evaluate_action_gate.

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

Usage Guidelines4/5

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

The description gives clear context for when to use this tool (to attach a reference without verification/authorization) and implicitly indicates when not to use it (if verification or authorization is needed). However, it does not explicitly name alternative tools like verify_evidence, so it falls 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.

evaluate_action_gateC

Compute deterministic ALLOW, BLOCK, or REQUIRE_APPROVAL from retained versioned inputs.

ParametersJSON Schema
NameRequiredDescriptionDefault
request_idYes
caller_tokenYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/5.0
Behavior2/5

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

The description discloses that the computation is deterministic and based on retained versioned inputs, giving some insight into its state-dependency. However, it does not disclose side effects, error conditions, or data requirements beyond those inputs, and with no annotations, this is insufficient.

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

Conciseness5/5

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

The description is a single compact sentence that conveys the core function without redundancy. It is front-loaded with the action verb and is appropriately sized.

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

Completeness2/5

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

While the output schema exists, the description lacks workflow context (e.g., prerequisite steps) and does not explain terminology like 'retained versioned inputs' or how the parameters map to these inputs. This makes it incomplete for a tool in a multi-step action gate workflow.

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

Parameters2/5

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

The description makes no reference to request_id or caller_token, and since the schema has 0% coverage, the agent must rely on the parameter names alone. This leaves interpretation to guesswork.

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

Purpose4/5

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

The description uses a specific verb 'Compute' and specifies the output values 'ALLOW, BLOCK, or REQUIRE_APPROVAL', which distinguishes it from siblings like submit_action_request or get_action_state. However, it does not clarify what 'retained versioned inputs' refers to, limiting full precision.

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

Usage Guidelines2/5

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

No use-case context is provided; there is no mention of when this should be called relative to other tools, or any alternatives. The description only states what it computes, not when to invoke it.

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

get_action_stateA

Read append-only action state and integrity results; performs no mutation.

ParametersJSON Schema
NameRequiredDescriptionDefault
request_idYes
caller_tokenYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior4/5

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

No annotations are provided, so the description carries full behavioral burden. It explicitly discloses side-effect-free behavior ('performs no mutation') and the append-only data model, which adds meaningful context. However, it does not discuss auth requirements, error conditions, or scope of the state read.

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

Conciseness5/5

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

One short, front-loaded sentence where every clause adds value: read operation, append-only state, integrity results, and no mutation. No filler or redundancy.

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

Completeness2/5

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

The tool requires two mandatory parameters and has no annotations; the description covers purpose and safety but leaves parameter semantics and invocation prerequisites unexplained. Although an output schema exists, it does not compensate for missing parameter guidance.

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

Parameters1/5

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

Schema has two required parameters with 0% description coverage. The description does not mention request_id or caller_token at all, leaving their meaning and relationship to the tool's behavior entirely to guesswork.

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?

Description uses specific verb 'Read' and names the resource 'append-only action state and integrity results', which clearly distinguishes it from sibling write/action tools like submit_action_request and record_human_approval. The no-mutation clause reinforces purpose.

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

Usage Guidelines3/5

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

The description implies read-only inspection ('performs no mutation') but does not explicitly state when to use this tool versus alternatives or when not to use it. Sibling names give context, but the description itself offers no direct usage guidance.

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

record_human_approvalB

Create and append a scoped signed human approval, denial, or revocation input.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusYes
subjectYes
request_idYes
approver_tokenYes
identity_providerYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations, the description carries full burden for behavioral disclosure. It communicates that the tool appends a signed, scoped record, but it does not explain auth requirements, side effects, or what the output contains. As a mutation tool, this is a significant gap.

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

Conciseness5/5

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

The description is a single, well-structured sentence that directly states the tool's action and object with zero wasted words. It front-loads the verb and keeps the purpose immediately understandable.

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

Completeness2/5

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

Despite having an output schema and five required parameters, the description is minimal. It lacks details about when to use this tool, the meaning of the parameters, any prerequisites, or what the output represents. The tool is a write operation, so more context is necessary for correct invocation.

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

Parameters2/5

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

Schema description coverage is 0%, and the description does not elaborate on any of the five parameters. Although the parameter names (request_id, approver_token, etc.) offer some hints, the description adds no meaning beyond the schema's field names.

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?

The description clearly states a specific verb ('Create and append') and a distinct resource ('scoped signed human approval, denial, or revocation input'). This distinguishes it from sibling tools like submit_action_request or evaluate_action_gate by focusing on recording human decisions.

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

Usage Guidelines3/5

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

Usage is implied by the name and description—it's for recording a human's approval/denial/revocation—but there is no explicit guidance on when to prefer this over siblings or any prerequisites. The description does not mention alternatives or exclusions.

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

submit_action_requestC

Validate and append one normalized action request; grants no authority.

ParametersJSON Schema
NameRequiredDescriptionDefault
caller_tokenYes
action_requestYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses that the tool validates and appends and does not grant authority, but it omits details about the required caller_token, what validation entails, side effects, or failure behavior. The minimal disclosure is insufficient for a mutation tool.

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

Conciseness5/5

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

The description is a single sentence, front-loaded with the verb and resource, and every word adds value. The caveat 'grants no authority' is a meaningful behavioral note. It is appropriately sized, though thin on content.

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

Completeness2/5

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

Given the nested action_request object, required caller_token, and output schema, the description is incomplete. It doesn't clarify the expected format of a normalized action request, the token's origin or purpose, or the tool's role in the broader workflow with siblings like evaluate_action_gate or record_human_approval.

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

Parameters1/5

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

Schema description coverage is 0% and the description provides no parameter information. It does not explain the structure of 'action_request' or the purpose of 'caller_token', leaving the agent to guess from parameter names alone. The tool has only two parameters, so the description should have easily compensated, but it doesn't.

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

Purpose4/5

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

The description clearly states the tool's function with a specific verb ('Validate and append') and resource ('one normalized action request'), and adds a distinguishing behavioral note ('grants no authority'). It distinguishes from sibling tools focused on evidence and approval, though it doesn't explicitly name alternatives.

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

Usage Guidelines2/5

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

No explicit guidance is given for when to use this tool versus siblings. The 'grants no authority' hint implies it's not for authority-granting, but there is no clear 'use when' or 'instead of' guidance, leaving the agent to infer usage from the name and context.

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

verify_evidenceC

Invoke pinned agent-evidence 0.6.0 and retain its structured receipt.

ParametersJSON Schema
NameRequiredDescriptionDefault
request_idYes
caller_tokenYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It states the tool invokes a pinned version and retains a structured receipt, which gives some behavioral context (reproducibility, output retention), but it does not disclose side effects, permission requirements, or whether this is a read-only operation.

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

Conciseness3/5

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

The description is a single concise sentence with no filler, but it is under-specified. It is short enough to be front-loaded, yet it leaves out critical semantics, so it is not efficiently informative.

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

Completeness2/5

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

The existence of an output schema covers return values, but the description lacks context about the tool's role in the evidence workflow, when to call it, or what the receipt contains. Combined with zero parameter descriptions, the overall context is incomplete.

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

Parameters1/5

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

Schema coverage is 0%, and the description offers no explanation of what request_id or caller_token represent. The description adds no value beyond the parameter names, leaving the agent without sufficient information to populate them correctly.

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

Purpose3/5

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

The description says "Invoke pinned agent-evidence 0.6.0" which gives a verb and resource, but it does not explicitly state that the tool verifies evidence. The purpose is implied by the tool name, not clearly described. It also does not distinguish from sibling tools like attach_evidence or evaluate_action_gate.

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

Usage Guidelines1/5

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

There is no guidance on when to use this tool or when to use alternatives. The description provides no context signal such as prerequisites, workflow steps, or exclusions.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.1.0
    • First observedattach_evidence
    • First observedevaluate_action_gate
    • First observedget_action_state
    • First observedrecord_human_approval
    • First observedsubmit_action_request
    • First observedverify_evidence
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a distinct phase of the action gate workflow: submitting a request, attaching evidence, verifying evidence, evaluating the gate, reading state, and recording human approval. There is no overlap in purpose or ambiguity about which tool to use.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with clear, domain-specific verbs (submit, attach, verify, evaluate, get, record). The naming is uniform, predictable, and free of mixed styles or vague terms.

Tool Count5/5

With six tools, the server is well-scoped for an action gate domain. Each tool maps to a core step in the process, avoiding both bloat and a thin surface.

Completeness5/5

The tool set covers the complete action gate lifecycle: request intake, evidence attachment and verification, gate evaluation, human approval input, and state inspection. Given the append-only and integrity-focused design, there are no obvious missing operations.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • gov-mcp

    liuhaotian2024-prog
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enforces runtime governance on AI agent actions — file access, command execution, delegation chains, and permission escalation.
    MIT

  • governed-mcp

    rsiraj0
    F
    license
    Not graded
    quality
    C
    maintenance
    MCP server that enforces governance on agentic decisions with auditable evidence records, providing tools for understanding, calibrating confidence, and navigating handoffs based on policy.
    1
    -

  • ceco proof gate

    RileyBetts
    F
    license
    Not graded
    quality
    C
    maintenance
    MCP server that evaluates agent actions against a Policy State Machine, emits a tamper-evident audit trail, and dispatches approved transitions to internal or federated handlers.
    -

  • velvet-rope

    paulchum
    A
    license
    Not graded
    quality
    B
    maintenance
    An MCP server for agent authorization that tests the full effect surface and enforces control over consequential actions before dispatch, emitting verifiable execution evidence.
    2
    Apache 2.0