Provides tools for interacting with a Databricks-like toy platform, including versioning, partitions, DAGs, and event-driven workflows, for learning warehouse internals.
Provides tools for interacting with a PostgreSQL-like toy engine, including heap tables, B-tree indexing, query plan selection, and WAL/checkpoint operations, for learning storage and planner internals.
Click on "Install 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., "@Runtime Copilot MCP Server explain the latest regression failure"
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.
Runnable Python and Rust data-system internals with an MCP-native runtime copilot layer.
This repository combines two things:
a local-first engineering lab for PostgreSQL-like and Databricks-like internals,
a Runtime Copilot MCP surface for diagnostics, explainability, regression checks, and operational memory.
Storage and planner internals: heap tables, B-tree indexing, selectivity, and plan choice.
Persistence and replay: WAL/checkpoint style flows and deterministic state transitions.
Workflow and write-path modeling: event-first architecture, idempotency, retry semantics.
Explainable runtime operations: traced runs, failure summaries, regression verdicts, baseline compare.
MCP access: machine-usable operational interface instead of ad hoc shell scripts.
Related MCP server: @us-all/dbt-mcp
Data engineers learning warehouse and query-engine internals.
Platform and infrastructure engineers teaching storage and execution fundamentals.
Teams building onboarding labs, workshops, and demo environments.
Requirements:
Python 3.10+ (tested with Python 3.14)
Setup:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "psycopg[binary]"Run end-to-end flow:
cargo run --bin e2e_flowRun core demos:
.venv/bin/python mini_pg_like.py
.venv/bin/python mini_databricks_clone.py
cargo run --bin mini_pg_like
cargo run --bin mini_databricks_clonemini_pg_like.py: PostgreSQL-like toy engine with heap table, B-tree index, and planner output.
mini_databricks_clone.py: Databricks-like toy platform with versioning, partitions, DAGs, and events.
src/bin/mini_pg_like.rs: Rust PostgreSQL-like demo.
src/bin/mini_databricks_clone.rs: Rust Databricks-like demo.
src/lib.rs, src/common.rs, src/pg.rs: shared Rust core modules.
mcp_engine_server.py: MCP runtime adapter for diagnostics and regression workflows.
Most internals content stops at diagrams. This project stays runnable and inspectable:
compare Python and Rust implementations of the same system ideas,
trace write-path behavior with concrete events and state transitions,
run explainable regression checks through MCP,
turn runtime operations into a discoverable control surface for AI clients.
This repo also includes a minimal MCP server that wraps the lab operations:
mcp_engine_server.py
Cursor config: .cursor/mcp.json
Current MCP tool list for this release (47 tools total):
Engine state and runtime:
init_engine
insert_row
upsert_row
create_index
explain_customer
reindex_project
run_e2e_flow
Explainability and demos:
explain_run
demo_explain_run
demo_explain_run_failure
demo_explain_semantic_failure
demo_explain_idempotency_conflict
demo_explain_concurrency_failure_storm
explain_regression_suite
Trace and retrieval:
record_tool_trace
similar_incidents
refresh_trace_path
refresh_docs_path
memory_upsert
memory_search
SLO and ROI:
health_check
benchmark_calls
scenario_load_test
capture_roi_baseline
report_drift_bug
decision_gate
Schema evaluation (verdict + report via MCP, no external Postgres):
schema_load_tool
schema_explain_tool
schema_evaluate_tool
schema_evaluate_full_tool
Project contract and regression:
project_manifest
project_capabilities
project_tool_catalog
project_get_defaults
project_run_regression
project_capture_baseline
project_compare_baseline
Generic project state:
project_list_entities
project_get_entity
project_upsert_entity
project_delete_entity
project_append_event
project_ingest_trace
project_explain_run
project_export_state
Generic heuristics:
project_list_heuristics
project_run_heuristic
For machine-readable discovery, prefer:
project_tool_catalog
project_get_defaults
Current heuristic profiles available through project_run_heuristic:
pain_structure
naive_bias
price_distribution
liquidity_signals
price_liquidity_matrix
cross_category
sale_format
speed_signals
trust_signals
If Cursor MCP auto-discovery is enabled, restart Cursor and connect mini-data-engine.
Default MCP runtime data paths are under tests/artifacts/mcp/*.
If Cursor keeps asking for MCP or command approval on every call, apply this once:
Enable workspace trust in Cursor user settings:
"security.workspace.trust.enabled": trueIn Cursor, open Settings -> Agents -> Auto-Run and set:
Auto-run mode: Run in Sandbox
MCP Allowlist: add mini-data-engine tools you use often
Command Allowlist: add frequently used safe commands
Keep this repo opened as the same trusted workspace and reload the window once.
Notes:
MCP server approval and per-tool allowlist behavior are enforced by Cursor security settings.
In some Cursor versions, allowlist behavior can be best-effort and still prompt in edge cases.
Fastest way to see the new explainability use case in action through MCP:
demo_explain_runThat single tool call creates a traced run, records step-level events under one run_id,
and returns an explanation with:
ordered timeline
tool path
total elapsed time
failure summary if anything breaks
You can then replay the same explanation directly with:
explain_run(run_id="...")Use explain_regression_suite when you want regression checks to run through MCP and come back as explainable run summaries instead of isolated test output.
The suite drives the current validation surface through the MCP layer, attaches run_id traces, and returns explain output for each check so regressions can be inspected with the same mechanism used for runtime incidents.
It currently runs:
Python unit tests via python -m unittest discover
Rust tests via cargo test, including the current engine_cli integration tests
health_check
benchmark_calls
scenario_load_test
explainability control demos
The explainability demos intentionally include both positive and negative controls:
demo_explain_run as expected_success
demo_explain_run_failure as expected_failure
demo_explain_semantic_failure as expected_failure
demo_explain_idempotency_conflict as expected_failure
demo_explain_concurrency_failure_storm as expected_failure
That means the suite is not only checking that the happy path stays green. It also checks that the explain layer still classifies and summarizes known failure classes correctly.
The current regression surface covers:
happy-path traced execution
runtime/path failures
semantic data validation failures
idempotency conflict failures
concurrency and failure-storm control scenarios
sampled benchmark and scenario SLO regressions
Fastest MCP call for the full regression bundle:
explain_regression_suiteUse it as the top-level MCP regression entrypoint when you want one answer that includes:
which checks passed
which failures were expected controls
explain summaries for each traced run
early signals that a latency or behavior regression appeared
The MCP layer is an access interface, not the core product idea. The core of the repository is the runnable lab itself.
Product note:
PRODUCT_NOTE_RUNTIME_EXPLAINABILITY.md
Short note describing the runtime explainability use case, the required signals, and the explain_run MVP.
PRODUCT_NOTE_RUNTIME_COPILOT.md
Product framing for Runtime Copilot as an MCP-native operational brain.
EXPLAIN_REGRESSION_SUITE_FEASIBILITY.md
Short article describing what this repository validated about explain-first regression suites and where the current denominator still stays narrow.
Use in Codex:
skill package: codex/skills/runtime-copilot/SKILL.md
automation examples: codex/automations
guide: docs/use-in-codex.md
Run persistent engine CLI (productization path):
# Initialize storage
cargo run --bin engine_cli -- init ./tests/artifacts/engine/data orders
# Insert and upsert (WAL append)
cargo run --bin engine_cli -- insert ./tests/artifacts/engine/data orders 1 4242 50
cargo run --bin engine_cli -- upsert ./tests/artifacts/engine/data orders 1 4242 55
# Build index and explain
cargo run --bin engine_cli -- index ./tests/artifacts/engine/data orders
cargo run --bin engine_cli -- explain ./tests/artifacts/engine/data orders 4242
# Write snapshot and truncate WAL
cargo run --bin engine_cli -- checkpoint ./tests/artifacts/engine/data orders
# Transaction simulation: begin/commit/rollback semantics,
# per-table write lock, snapshot read, and conflict detection
cargo run --bin engine_cli -- tx-demo ./tests/artifacts/engine/data orders
# Crash/restart recovery for transaction journals
cargo run --bin engine_cli -- tx-recovery-list ./tests/artifacts/engine/data orders
cargo run --bin engine_cli -- tx-recovery-commit ./tests/artifacts/engine/data orders <tx_id>
cargo run --bin engine_cli -- tx-recovery-rollback ./tests/artifacts/engine/data orders <tx_id>In mini_pg_like.py: selective predicate switches to Index Scan; non-selective stays Seq Scan.
In mini_databricks_clone.py: layer-by-layer demo output, workflow DAG order/metrics, and canonical events count from the single write path.
In mini_pg_like (Rust): same planner behavior with shared core modules.
In mini_databricks_clone (Rust): same layered demo using shared Rust library code.
In engine_cli (Rust): persistent snapshot + WAL replay flow with simple operational commands.
In engine_cli tx-demo: explicit transaction scopes, snapshot reads, per-table write lock, and concurrent upsert conflict detection.
In engine_cli tx-recovery-*: staged transaction operations survive process restarts via per-transaction journal files and can be committed or rolled back explicitly.
In e2e_flow: one command runs write path, checkpoint, bronze->silver transform, planner explain, and DuckDB SQL validation on persisted data.
TECHNICAL_DESIGN_GENERIC.md captures the architectural discipline behind the code:
cross-layer reasoning (Idea -> API -> Runtime -> Storage -> Perf),
deterministic state transitions,
event-first design,
adapter contracts,
DAG-driven orchestration,
measurable go/no-go criteria.
It is not a separate product claim. It is the review and implementation spine used across the lab.
Build the image from this repo so MCP uses your local code (including schema tools) instead of the GitHub image:
./scripts/docker-build-local.shThis builds mini-data-engine:local. To drive another project (e.g. threads) with this MCP, set Cursor MCP to use the local image and mount that project as workspace:
Copy .cursor/mcp.docker.local.json into your project’s .cursor/mcp.json (or merge the mcpServers entry into your Cursor user config).
Open the project you want to drive (e.g. threads). ${workspaceFolder} will be that project; the container gets WORKSPACE_ROOT=/workspace and your project mounted at /workspace, so e.g. schema_path="schema.sql" resolves to that project’s file.
Example local config (uses mini-data-engine:local and mounts current workspace as /workspace):
{
"mcpServers": {
"mini-data-engine": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "WORKSPACE_ROOT=/workspace",
"-v", "${workspaceFolder}:/workspace",
"-v", "${workspaceFolder}/tests/artifacts:/app/tests/artifacts",
"mini-data-engine:local"
]
}
}
}Image is published to GHCR:
ghcr.io/kroq86/data-engineering-runtime-lab:latest
Pull:
docker pull ghcr.io/kroq86/data-engineering-runtime-lab:latestUse in Cursor MCP config (example):
{
"mcpServers": {
"mini-data-engine": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"${workspaceFolder}/tests/artifacts:/app/tests/artifacts",
"ghcr.io/kroq86/data-engineering-runtime-lab:latest"
]
}
}
}MCP surface for loom-ops and ops runbooks. Ecosystem: ECOSYSTEM.md
pip install ops-runtime-mcp
ops-runtime-mcp # stdio MCP; see docs/use-in-codex.mdBenchmark MCP operations with SLO-style summary metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| iterations | No | ||
| root_dir | No | ./tests/artifacts/mcp/bench | |
| table | No | orders | |
| min_success_rate | No | ||
| max_p95_ms | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It only mentions output metrics but does not indicate read-only, destructive potential, or any side effects.
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 extremely concise but under-specified. One sentence of 7 words lacks substantive 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?
With no annotations, no parameter details, and a vague purpose, the description fails to provide complete context for a tool with 5 parameters and an output schema.
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?
The schema has 5 parameters with 0% description coverage and the description adds no parameter details. Parameters like iterations, root_dir, table are not explained.
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 clearly states the tool benchmarks MCP operations and produces SLO-style metrics. It is distinct from sibling tools which focus on demo, project, or explanation tasks.
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?
No guidance on when to use this tool versus alternatives. The description does not mention any context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture baseline KPI snapshot for ROI Phase 0.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/baseline_runtime | |
| table | No | orders | |
| benchmark_iterations | No | ||
| scenario_iterations | No | ||
| output_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It does not disclose whether the tool modifies state, requires permissions, or returns data. The name suggests a read-only snapshot, but this is not confirmed.
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 very concise (one sentence), which is good for brevity but at the expense of essential details. It could benefit from a bit more structure without being verbose.
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 5 parameters with no descriptions and an output schema that is not explained, the description is insufficient for a complete understanding. The context of 'ROI Phase 0' and the baseline snapshot process 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?
The schema description coverage is 0%, meaning the description provides no explanation for any of the 5 parameters. The defaults are present but their meaning and usage remain unclear.
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 it captures a baseline KPI snapshot for ROI Phase 0, which gives a general idea but is vague. The verb 'capture' and the term 'ROI Phase 0' are not elaborated, and it does not distinguish from similar sibling tools like 'project_capture_baseline'.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., 'benchmark_calls', 'project_capture_baseline'). There is no mention of prerequisites, context, or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create customer index for engine table.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/engine_data | |
| table | No | orders |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond creation. Since no annotations are provided, the description is the sole source, yet it omits details about idempotency, side effects, required permissions, or whether it overwrites existing indexes.
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, concise sentence, but it is under-specified for a tool with two parameters and no annotations. It could benefit from additional context without being verbose.
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 lacks completeness given the context: no annotations, 0% schema coverage, and two parameters. It does not explain return values (output schema exists but is not described) or tool behavior, leaving significant gaps for an agent.
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?
The description adds no meaning beyond the input schema. Schema coverage is 0%, and the description does not explain the parameters 'root_dir' (default path) or 'table' (target table), failing to help the agent understand valid inputs.
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 clearly states the tool creates an index for a customer engine table, using specific verb 'Create' and resource 'customer index for engine table', distinguishing it from sibling tools like 'reindex_project' which likely operate on existing indexes.
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?
No guidance is provided on when to use this tool vs alternatives like 'reindex_project'. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate migration triggers and return pass/fail gate.
| Name | Required | Description | Default |
|---|---|---|---|
| trace_db_path | No | ||
| baseline_path | No | ||
| drift_counter_path | No | ||
| need_rust_portfolio | No | ||
| volume_threshold_per_day | No | ||
| regression_threshold_pct | No | ||
| consecutive_regressions_required | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present. The description states the tool evaluates and returns a pass/fail, but does not disclose any behavioral traits such as whether it modifies state, requires authentication, has side effects, or performance implications. The description carries the full burden but adds minimal transparency.
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 brief (one sentence), which is concise but lacks sufficient information. It does not front-load critical details, and while concise, it sacrifices informativeness. Every word earns its place, but more content is needed.
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 tool's complexity (7 parameters, no param descriptions, no output schema details shared), the description is incomplete. It does not explain return format, parameter roles, or usage flow. Sibling tools exist but this description does not situate the tool within a workflow.
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?
The input schema includes 7 parameters (all optional) with defaults and titles, but no descriptions. Schema description coverage is 0%. The description does not explain any parameter's meaning or how they affect behavior, leaving the agent without necessary semantic 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?
The description uses the verb 'evaluate' and specifies the resource 'migration triggers', with a clear output of 'pass/fail gate'. It sufficiently conveys the tool's main function, though 'migration triggers' could be more explicit. It distinguishes from sibling tools that deal with baselines, regressions, and other evaluation tasks.
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?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, context (e.g., before migration), or when not to use it. Explicit usage context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a traced concurrency conflict plus failure-storm scenario.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/explain_demo_concurrency_storm | |
| table | No | orders | |
| trace_db_path | No | ||
| workers | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It states the tool 'Run a ... scenario' but does not disclose whether this modifies state, creates resources, or is safe for repeated execution. A demo tool is likely non-destructive, but this is not explicit. Side effects and safety are unclear.
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 sentence, achieving brevity. However, it sacrifices information: every word must earn its place, and here the sentence is too vague to be useful. Conciseness is present, but clarity and completeness are lacking.
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 tool has 4 parameters with zero descriptions, no annotations, and an output schema (unexplained), the description is insufficient. It does not cover what the scenario involves, how parameters affect execution, or what the output represents. The agent lacks context to use it correctly.
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%, yet the description provides no explanations for any of the four parameters (root_dir, table, trace_db_path, workers). The agent cannot infer their purpose, format, or valid values, making effective invocation impossible.
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 specifies the verb 'Run' and identifies the resource as a 'traced concurrency conflict plus failure-storm scenario'. This clearly indicates the tool's action and focus, distinguishing it from sibling demo tools that cover other scenarios (e.g., idempotency, semantic failure). However, it does not explain what 'traced' means or how it differs from other demos beyond the scenario name.
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?
No guidance is provided on when to use this tool versus alternatives. With multiple sibling demo tools (e.g., demo_explain_idempotency_conflict, demo_explain_run), the agent has no criteria to choose this tool. Prerequisites, typical use cases, or exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a traced idempotency-conflict flow through WriteCore.
| Name | Required | Description | Default |
|---|---|---|---|
| trace_db_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only mentions 'traced' and 'through WriteCore', but does not cover side effects, authentication needs, or what happens when invoked. The behavioral context is minimal.
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 sentence with no extraneous information. Every word contributes to understanding the tool's purpose.
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 tool's simplicity (one optional parameter, demo purpose), the description adequately states the core action. However, it lacks details about the flow's behavior, expected output, or context for when to run this demo, leaving gaps for completeness.
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?
The single parameter trace_db_path has zero schema description coverage (0%). The description does not explain its purpose or usage, failing to add meaning beyond the schema's property definition.
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 clearly states the tool runs a 'traced idempotency-conflict flow through WriteCore', which is a specific verb and resource. It distinguishes itself from sibling demo_explain_* tools by specifying the type of conflict (idempotency vs. concurrency, semantic failure).
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 usage for educational purposes (explaining idempotency conflicts) but provides no explicit guidance on when to use or not use this tool compared to siblings. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a traced demo flow, then explain the run immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/explain_demo | |
| table | No | orders | |
| customer_id | No | ||
| trace_db_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions running and explaining but omits side effects, safety (e.g., destructive vs. read-only), or prerequisites. For a demo tool, safety could be inferred but not explicitly stated.
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 short sentence, which is concise but at the cost of missing critical details. It earns its place by stating the core action but fails to deliver additional value.
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 tool has 4 parameters, many siblings, and an output schema (though not shown), the description is inadequately complete. It does not explain what 'traced demo flow' or 'explain' means, nor the expected output format.
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 description adds no information about the four parameters (root_dir, table, customer_id, trace_db_path). Parameter names alone are insufficient to convey expected values or constraints.
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 clearly states the verb 'Run' and 'explain', specifies the resource 'traced demo flow', and indicates the sequential action. It distinguishes from siblings like demo_explain_run_failure by emphasizing the immediate explanation after running.
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 provides no guidance on when to use this tool versus alternatives. With many sibling tools (e.g., demo_explain_concurrency_failure_storm, demo_explain_idempotency_conflict), the lack of usage context forces the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a traced failing flow, then explain the failed run immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/explain_demo_failure | |
| table | No | orders | |
| trace_db_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears full responsibility for behavioral disclosure. It states the tool runs and explains but omits critical details: side effects (e.g., trace creation), permissions, or what 'explain' entails. The description barely adds beyond the name.
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 sentence, which is concise but under-specified for the tool's complexity (3 parameters, no behavioral context). It is too short to be effective; length does not compensate for missing 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?
Given the tool has 3 undocumented parameters and no annotations, the description is insufficient. It fails to cover parameter meanings, behavioral traits, or usage context. An output schema exists but does not compensate for description 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%, and the description fails to explain any of the three parameters (root_dir, table, trace_db_path). It adds no semantic value beyond the schema, leaving the agent to guess their purpose.
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 clearly states the tool's action: 'Run a traced failing flow, then explain the failed run immediately.' It specifies the verb-resource pair and distinguishes from siblings like demo_explain_run (which handles successful runs) and other demo_explain variants.
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 usage for failing flows but does not provide explicit when-to-use guidance or differentiate from numerous sibling tools like demo_explain_concurrency_failure_storm or demo_explain_idempotency_conflict. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a traced semantic-corruption flow and explain the failed validation.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/explain_demo_semantic_failure | |
| table | No | orders | |
| customer_id | No | ||
| trace_db_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 runs a flow and explains validation, but does not disclose side-effects (e.g., data mutation), resource requirements, or whether it is read-only. The agent cannot infer safety or expected behavior beyond the basic action.
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 sentence, which is concise but lacks structure. It covers the basic purpose without elaboration, leaving out necessary details. While compact, it does not earn its brevity by providing critical 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?
Given the tool's complexity (4 parameters, no param docs, no annotations), the description is incomplete. Although an output schema exists, the missing parameter semantics and behavioral traits leave significant gaps for correct invocation and interpretation.
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%, yet the description does not explain any of the four parameters (root_dir, table, customer_id, trace_db_path). The agent receives no guidance on how these inputs affect the tool's behavior, making parameter selection opaque.
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 specifies the action ('run a traced semantic-corruption flow') and outcome ('explain the failed validation'), providing a clear verb and resource. It implicitly distinguishes from sibling demo tools that handle concurrency or idempotency failures, though the jargon might reduce clarity for an AI agent.
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 offers no guidance on when to use this tool versus alternatives like demo_explain_concurrency_failure_storm or demo_explain_idempotency_conflict. There is no mention of prerequisites, context, or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run EXPLAIN ANALYZE style output by customer filter.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/engine_data | |
| table | No | orders | |
| customer_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavioral traits. It fails to state whether the tool is read-only, destructive, or requires specific permissions, and it does not mention side effects or execution context.
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 sentence, which is concise but under-specified. It lacks critical details about parameters, behavior, and output, making it insufficient for proper tool use.
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 tool has 3 parameters, no annotations, and an output schema (unaddressed), the description is highly incomplete. It provides no information on output format, parameter details, or contextual usage scenarios.
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%, meaning the schema provides no parameter descriptions. The description only implies customer_id via 'by customer filter' but does not explain root_dir or table, leaving their purpose unclear.
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 it runs 'EXPLAIN ANALYZE style output by customer filter,' which indicates a database analysis operation filtered by customer. However, it does not clearly specify what is being explained or the exact output nature, leaving some ambiguity.
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?
No usage guidelines are provided. The description does not indicate when to use this tool over sibling tools like explain_run, demo_explain_run, or others, nor does it mention any prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run regression checks and return explain output for each traced run.
| Name | Required | Description | Default |
|---|---|---|---|
| root_prefix | No | ./tests/artifacts/mcp/explain_suite | |
| trace_db_path | No | ||
| benchmark_iterations | No | ||
| scenario_iterations | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It mentions running regression checks but does not state if it is read-only, modifies state, requires auth, or has side effects.
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?
Single sentence is concise, but it lacks essential details; 'Run regression checks and return explain output for each traced run' is clear but minimal.
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 four parameters, no annotations, and an output schema, the description is incomplete: it fails to explain parameters, return values, or behavioral nuances.
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 0%, and the description adds no information about the four parameters beyond their names and defaults in the schema.
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 the verb 'run' and the resource 'regression checks' with 'explain output', but it does not distinguish from sibling tools like 'explain_run' or 'project_run_regression'.
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?
No guidance on when to use this tool versus alternatives, no prerequisites, and no when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain one recorded run_id from the local trace store.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| trace_db_path | No | ||
| max_timeline_events | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 'explain' but does not disclose whether the tool is read-only, what side effects occur, or any permissions needed. The output schema exists but the description does not reference it.
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 sentence, which is concise but too brief to be effective. It omits necessary details, making it under-specified rather than efficiently communicated.
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 three parameters, no annotations, and no parameter descriptions, the description fails to provide sufficient context. An AI agent would struggle to know how to set parameters like trace_db_path or max_timeline_events appropriately.
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 description does not explain any parameter beyond implying run_id is required. It fails to clarify trace_db_path or max_timeline_events, leaving the agent to guess their meaning.
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 clearly states the tool explains a recorded run_id from the local trace store, indicating a specific verb and resource. However, it does not differentiate from sibling tools like demo_explain_run or project_explain_run, which may have similar purposes.
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?
No guidance on when to use this tool versus alternatives. The description lacks context about prerequisites or situations where this tool is preferred over similar siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a quick MCP smoke flow and summarize status.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/health | |
| table | No | orders |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It mentions 'quick' implying non-destructive and fast, but does not explicitly state whether it modifies state, required permissions, or side effects. The behavioral traits are insufficiently disclosed.
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 sentence, short and to the point. It front-loads the action and output. However, it could benefit from structuring details (e.g., parameters) for clarity.
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?
Despite having an output schema (not shown), the description lacks context about what 'smoke flow' entails, what the output status summary covers, and how parameters affect behavior. Completeness is low for a tool with optional parameters and no parameter explanations.
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%, yet the description adds no explanation for the two parameters (root_dir, table). The defaults are present but not explained. The description fails to compensate for the lack of schema descriptions.
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 clearly states a verb (Run) and resource (MCP smoke flow) with an outcome (summarize status). It distinguishes from sibling tools as the only health_check. However, 'MCP smoke flow' is domain-specific and may be unclear to an AI agent not familiar with the system.
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 provides no information on when to use this tool versus alternatives, no prerequisites, and no exclusion criteria. For a diagnostic tool, guidance on when to invoke it is lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialize persistent engine storage.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/engine_data | |
| table | No | orders |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits such as idempotency, side effects, or destructiveness. An agent cannot assess whether initialization is safe or mutating.
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 sentence, which is concise, but it is under-specified. While brief, the brevity sacrifices necessary information, so it does not fully earn 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 two undocumented parameters, no annotations, and an output schema (not described), the description is severely incomplete. It fails to cover basic aspects needed 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 0%, and the description lacks any explanation of the two parameters (root_dir, table). It provides no added meaning, leaving the agent without guidance on how to set these values.
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 'Initialize persistent engine storage' provides a verb and resource but is vague regarding what initialization entails. It does not distinguish from sibling tools like create_index or upsert_row, which could also involve storage setup.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context that would help an agent decide to use init_engine over other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert one row into the persistent engine.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/engine_data | |
| table | No | orders | |
| order_id | No | ||
| customer_id | No | ||
| amount | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only states 'insert one row' but omits side effects (e.g., what happens on duplicate key), error conditions, or mutation impact. The 'persistent engine' hint is vague.
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 with no waste. It is efficient, though it could reveal more meaning without becoming verbose.
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?
For a tool with 5 parameters, no annotations, and no schema descriptions, the description provides almost no context. Even with an output schema present, the description lacks crucial usage details like error handling and idempotency.
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 0%, and the description adds no explanation for the 5 parameters (e.g., root_dir, table, fields). The agent must rely on default values and parameter names, which is insufficient.
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 'Insert one row into the persistent engine' clearly states the action and resource. It distinguishes from 'upsert_row' by specifying insert-only, but could explicitly contrast with 'upsert_row'.
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?
No guidance on when to use this tool versus alternatives like 'upsert_row' or other database tools. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search memory entries by semantic similarity and metadata filters.
| Name | Required | Description | Default |
|---|---|---|---|
| query_text | Yes | ||
| top_k | No | ||
| min_score | No | ||
| status | No | ||
| tool_name | No | ||
| scenario_id | No | ||
| start_time_utc | No | ||
| end_time_utc | No | ||
| tags | No | ||
| trace_db_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavior. It mentions 'semantic similarity' and 'metadata filters' but does not disclose whether it is read-only, any side effects, or response structure. The description lacks critical behavioral context.
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 sentence of 8 words, which is concise but at the expense of necessary detail. It lacks structure (e.g., no line breaks, no parameter grouping) and does not earn its place by providing sufficient 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?
Given 10 parameters, no schema descriptions, and no annotations, the description is severely incomplete. It does not address parameter semantics, usage context, or behavioral constraints, leaving the agent with insufficient guidance.
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 0% schema description coverage and 10 parameters, the description does not explain the meaning or usage of any parameter. It only broadly hints at filters but fails to clarify fields like 'query_text', 'top_k', 'min_score', etc.
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 clearly states the action ('Search'), the resource ('memory entries'), and the method ('by semantic similarity and metadata filters'). This is specific and distinguishes it from sibling tools like 'similar_incidents' which likely have different purposes.
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 provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. For instance, it does not compare with other search or retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upsert one operational memory entry for semantic recall.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| summary | Yes | ||
| status | No | ok | |
| tool_name | No | memory_entry | |
| error_text | No | ||
| scenario_id | No | memory | |
| tags | No | ||
| memory_id | No | ||
| metadata_json | No | ||
| correlation_id | No | ||
| decision_reason | No | ||
| actual_effects | No | ||
| trace_db_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description offers no behavioral details beyond the action. It does not disclose side effects, idempotency, required permissions, or error handling.
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 very short (one sentence), which is concise, but it is severely underspecified. It lacks necessary details that would make it helpful.
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 13 parameters and no annotations, the description is completely inadequate. While an output schema exists, its content is unknown, and the description does not explain return values or success/failure semantics.
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%, meaning no parameter descriptions exist in the schema. The tool description adds no meaning to the 13 parameters; it only names the two required ones implicitly.
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 clearly states the action ('Upsert') and the resource ('operational memory entry for semantic recall'). It is specific and actionable, though it does not differentiate from sibling tools like memory_search or upsert_row.
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?
No guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a generic project event to the local event log.
| Name | Required | Description | Default |
|---|---|---|---|
| event_type | No | project.event | |
| entity_type | No | generic_entity | |
| entity_id | No | ||
| payload_json | No | {} | |
| root_dir | No | ||
| run_id | No | ||
| decision_reason | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'append... to the local event log' but does not disclose whether events are idempotent, require permissions, or have side effects.
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 sentence, but it is too brief for a tool with 7 parameters and no annotations. It sacrifices necessary detail for brevity.
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 tool's complexity (7 parameters, no parameter descriptions, no annotations) and the presence of an output schema, the description fails to provide essential behavioral and usage context, making it 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%, meaning no parameter descriptions exist in the schema. The tool description does not mention or explain any of the 7 parameters, leaving their purpose entirely unclear.
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 clearly states the verb 'append', object 'generic project event', and target 'local event log', making the purpose understandable. However, it does not differentiate from sibling tools like project_upsert_entity or project_list_entities that might also involve events.
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?
No guidance is provided on when to use this tool versus alternatives. There are no exclusions, prerequisites, or context about the appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return declared runtime capabilities and contract coverage.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The description indicates a read-only operation, but lacks details on potential side effects or special behavior. Given the simplicity of the tool, a 3 is adequate, but it could mention that it's non-destructive or cheap.
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 sentence that starts with the verb 'Return', directly stating the action. Every word is necessary and no redundancy. It is maximally concise.
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 no parameters and an output schema present, the description is minimally sufficient. However, it does not elaborate on what 'declared runtime capabilities' or 'contract coverage' means, leaving room for ambiguity. A more descriptive sentence would improve completeness.
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?
There are no parameters, so the input schema covers everything. Baseline 4 applies: the description does not need to add parameter information, and it doesn't. The tool's simplicity 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?
The description uses a specific verb 'Return' and mentions 'declared runtime capabilities and contract coverage', clearly stating what the tool does. However, without title and given siblings like project_manifest and project_tool_catalog, it does not differentiate from similar tools, so it's not a 5.
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 provides no guidance on when to use this tool versus alternatives. Sibling tools like project_manifest or project_tool_catalog likely have overlapping purposes, but no context is given to help the agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a baseline snapshot and return a unified verdict envelope.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/baseline_runtime | |
| table | No | orders | |
| benchmark_iterations | No | ||
| scenario_iterations | No | ||
| output_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully convey behavioral traits. It only says 'capture a baseline snapshot and return a unified verdict envelope,' failing to disclose whether the tool is read-only, destructive, or what side effects occur (e.g., overwriting existing baselines).
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 sentence, which is concise, but it sacrifices clarity and completeness. It could be expanded to include more useful details without becoming overly long.
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 five parameters, no annotations, and an output schema that is not described, the description is insufficient. It leaves critical gaps about what constitutes a baseline, what a verdict envelope contains, and the overall workflow context.
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 description adds no information about any of the five parameters. Parameters like root_dir, table, iterations, and output_path are undocumented, leaving the agent with no guidance on how they affect tool behavior.
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 'Capture a baseline snapshot and return a unified verdict envelope,' which gives a general sense of the action and result. However, the term 'unified verdict envelope' is jargon and not explained, and the description does not distinguish this tool from siblings like 'capture_roi_baseline' or 'project_compare_baseline'.
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?
No guidance is provided on when to use this tool versus alternatives. There are no prerequisites, context, or examples of appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare current benchmark/scenario results against a stored baseline.
| Name | Required | Description | Default |
|---|---|---|---|
| baseline_path | No | ||
| root_dir | No | ./tests/artifacts/mcp/baseline_candidate | |
| table | No | orders | |
| benchmark_iterations | No | ||
| scenario_iterations | No | ||
| benchmark_regression_pct | No | ||
| scenario_regression_pct | No | ||
| e2e_regression_pct | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description should disclose behavioral traits (e.g., side effects, error states). It only states 'compare', implying no side effects, but nothing about permissions, data source, or failure modes.
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 sentence, extremely concise. However, it sacrifices necessary details for brevity, making it less useful.
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 tool's complexity (8 parameters, output schema) and no annotations, the description is insufficient. It does not explain input, output, or behavior, leaving significant gaps for an agent.
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 description provides no information about any of the 8 parameters. It completely fails to compensate for the schema's lack of descriptions.
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 clearly states the tool compares current benchmark/scenario results against a stored baseline, with a specific verb and resource. It differentiates from siblings like project_capture_baseline, but could be more precise.
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?
No guidance on when to use this tool versus alternatives like benchmark_calls or project_capture_baseline. The description does not mention prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a declared entity from the generic state store.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | No | generic_entity | |
| entity_id | No | ||
| root_dir | No | ||
| dry_run | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It only states 'delete' but does not disclose if the operation is permanent, requires special permissions, or affects related data. The dry_run parameter is not mentioned in the description, missing an opportunity to clarify safety.
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 extremely concise with one sentence, but it sacrifices necessary detail. While it front-loads the action, it fails to earn its place by not adding value beyond a tautology of the name.
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 tool has 4 parameters with no schema description, an output schema exists, and it's a delete operation, the description is grossly incomplete. It does not explain parameters, return value, or behavioral implications like permanence.
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%, yet the description does not explain any of the four parameters (entity_type, entity_id, root_dir, dry_run). The agent gets no semantic help from the description, relying solely on parameter names which are insufficient.
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 clearly states the action 'Delete' and the resource 'a declared entity from the generic state store'. It uses a specific verb and resource, distinguishing it from sibling tools that create, update, or list entities.
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 provides no guidance on when to use this tool versus alternatives like project_upsert_entity or project_get_entity. It lacks context on prerequisites, when not to use, or comparisons with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one run explanation through the generic project explain entrypoint.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| trace_db_path | No | ||
| max_timeline_events | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description says 'Read', indicating read-only operation, but no annotations exist to confirm. No details on side effects, auth, or edge cases, but the verb provides basic transparency.
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?
Single sentence is concise but lacks structure and substantive information; it is underspecified rather than efficient.
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?
Despite having an output schema, the description offers no context about what a run explanation is, how it fits with sibling tools, or any behavioral aspects, leaving significant 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%, and the description does not explain any of the three parameters (run_id, trace_db_path, max_timeline_events) or their semantics.
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?
Description states 'Read one run explanation' which gives a verb and resource, but 'through the generic project explain entrypoint' is vague and doesn't differentiate from sibling tools like 'explain_run' or 'demo_explain_run'.
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?
No guidance on when to use this tool versus alternatives, no exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export generic project state as a JSON snapshot.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ||
| entity_type | No | ||
| output_path | No | ||
| include_events | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation (export) but does not disclose side effects, permissions, or output structure. No annotations exist to compensate.
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 concise sentence, but its brevity sacrifices needed detail.
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?
Despite having an output schema (not shown), the description does not cover return values or explain the 4 parameters adequately. For a tool with multiple parameters, this is insufficient.
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 0% schema description coverage and no parameter explanations in the description, the agent lacks any semantic understanding of the 4 parameters (root_dir, entity_type, output_path, include_events).
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 clearly states the action (Export) and the resource (generic project state) with output format (JSON snapshot). However, it does not differentiate from sibling tools like project_get_entity or project_manifest.
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?
No guidance is provided on when to use this tool vs alternatives. The description lacks context about prerequisites or appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return default workspace, paths, runtime mode, and project metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation by stating it returns data, but does not explicitly disclose side effects, authentication needs, or rate limits. With no annotations provided, the description carries the burden but meets minimum adequacy.
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 covers the key purpose without excess. Every word 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?
Given the tool's simplicity (no parameters, no output schema needed in description), the description sufficiently conveys what it returns. It is complete enough for a getter tool with an output schema.
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?
The tool has no parameters, so schema coverage is 100%. The description adds value by listing the returned fields (workspace, paths, etc.), which compensates for the lack of parameter details. Baseline is 4 for zero parameters.
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 clearly states the tool returns default workspace, paths, runtime mode, and project metadata, providing a specific verb and resource. It distinguishes itself from sibling tools like project_get_entity or project_manifest by focusing on defaults.
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?
No guidance is provided on when to use this tool versus alternatives. There are no prerequisites, context, or exclusions mentioned, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load one declared project entity by identity key.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | No | generic_entity | |
| entity_id | No | ||
| root_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral traits. It only states 'load,' implying a read operation, but fails to disclose what happens if the entity is not found, whether it is idempotent, or any access requirements.
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 sentence, very concise. However, it is under-specified and lacks structure—there is no bullet list or additional context that would help an agent without redundant 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?
Despite having an output schema, the description does not explain return values or error cases. For a tool that loads an entity, the agent needs to know what to expect in response and how to handle missing entities.
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 description adds no clarification for the three parameters (entity_type, entity_id, root_dir). The defaults are self-explanatory, but the semantics are left entirely to the agent to infer.
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 'Load one declared project entity by identity key,' which is a specific verb (load) and resource (project entity). It clearly distinguishes from sibling tools like project_delete_entity, project_upsert_entity, and project_list_entities.
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?
No guidance is provided about when to use this tool versus alternatives. There is no mention of prerequisites, limitations, or scenarios where sibling tools would be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append one normalized trace record through the generic project ingest path.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| tool_name | Yes | ||
| status | Yes | ||
| summary | Yes | ||
| trace_db_path | No | ||
| error_text | No | ||
| scenario_id | No | project_state | |
| correlation_id | No | ||
| attempt | No | ||
| retry_classification | No | not_applicable | |
| decision_reason | No | ||
| actual_effects | No | ||
| source_kind | No | project_state | |
| source_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It only says 'Append one normalized trace record' without disclosing side effects, idempotency, error behavior, or other behavioral traits needed for a write operation.
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 sentence, which is concise but overly brief. It sacrifices necessary information for brevity, making it inadequate rather than efficiently informative.
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 complexity (14 parameters, no schema descriptions, no annotations) and presence of an output schema, the description is incomplete. It does not cover parameter meaning, usage scenarios, or return information, leaving the agent with insufficient context.
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%, yet the description does not mention any of the 14 parameters (4 required). The agent has no guidance on what each parameter means or how to use 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?
The description states the verb 'Append' and resource 'trace record', giving a basic purpose. However, it is vague ('generic project ingest path') and does not differentiate from siblings like 'record_tool_trace', which also records traces.
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?
No guidance on when to use this tool versus alternatives (e.g., record_tool_trace). The description lacks exclusions or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List declared project entities from the generic state store.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | No | generic_entity | |
| root_dir | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It only says 'list', but does not disclose side effects, error conditions, or whether listing is read-only. The limit parameter hints at pagination but not explained.
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?
Extremely concise at 9 words, but this comes at the cost of missing essential information. A single sentence is appropriate but lacks detail.
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 three parameters, no annotations, and an output schema that is not described, the description is incomplete. It does not explain how to use the tool effectively or what the output contains.
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%. The description does not mention any of the three parameters (entity_type, root_dir, limit), failing to add meaning beyond the schema defaults. Without explanation, an agent may misuse parameters.
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?
Description clearly states 'List declared project entities from the generic state store', using a specific verb and resource. However, it does not differentiate from sibling tools like project_get_entity (single entity) or project_list_heuristics (lists heuristics), missing an opportunity to disambiguate.
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?
No guidance on when to use this tool versus alternatives. No mentions of conditions, prerequisites, or comparisons to similar project_* tools are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List declared heuristic profiles available for generic project analysis.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action but lacks details on return format, side effects, or permissions. The behavior is straightforward, so minimal transparency is adequate.
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 clear sentence with no wasted words. It is front-loaded and efficient.
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 tool has no parameters and an output schema, the description is minimally complete. It could add context about what heuristic profiles are, but the current version is acceptable for a simple list 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?
The input schema has zero parameters and 100% coverage, so the baseline is 3. The description adds no parameter details because none exist, which 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?
The description clearly states the tool lists declared heuristic profiles with the context of generic project analysis, using a specific verb and resource. It distinguishes itself from siblings like project_run_heuristic.
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 usage for viewing available heuristics but provides no explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, which is acceptable for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe project state roots, schemas, and supported regression primitives.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It implies a read-only introspection operation by using 'describe', but it does not explicitly state side effects, idempotency, safety, or required permissions. The description adds minimal behavioral context beyond the name.
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 sentence that directly states the tool's function without any extraneous words. It is concise and front-loaded with the key verb and resources.
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?
For a tool with no parameters and an output schema, the description sufficiently lists the three categories of information it provides. It covers the core scope, though a slightly more detailed explanation of what 'state roots' and 'schemas' entail could be beneficial. Still, it is adequate for a simple metadata 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?
The tool has no parameters, and schema coverage is trivially 100%. According to the guidelines, the baseline for 0 parameters is 4, and the description correctly omits parameter information since none exist. No additional meaning is needed.
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 uses a specific verb 'describe' and lists three resources: project state roots, schemas, and supported regression primitives. This clearly indicates the tool's purpose, but it does not distinguish it from sibling tools like 'project_capabilities' or 'schema_explain_tool', so it loses one point for lacking 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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or any context-specific advice, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one declared heuristic profile over a source and persist the analysis through project state.
| Name | Required | Description | Default |
|---|---|---|---|
| heuristic_name | Yes | ||
| source_path | Yes | ||
| source_kind | No | telegram_html_export | |
| root_dir | No | ||
| run_id | No | ||
| persist | No | ||
| max_examples | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must carry full burden. It mentions persistence (mutation) but lacks details on destructive behavior, idempotency, required permissions, or side effects beyond persistence.
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?
Single sentence, 14 words, front-loaded with action. It is concise but overly terse, sacrificing behavioral and parameter detail.
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 7 parameters, no annotations, and an output schema, the description is severely incomplete. It omits explanation of key parameters like source_path, source_kind, persist, and the analysis output format.
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 description adds no parameter information. None of the 7 parameters (e.g., heuristic_name, source_path, persist) are explained, leaving agents without 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?
The description clearly states the tool runs a single heuristic profile and persists analysis to project state. It distinguishes from siblings like project_run_regression by specifying 'one declared heuristic', though it does not explicitly contrast.
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?
No guidance on when to use this tool vs alternatives. Siblings include project_run_regression, but description does not indicate when to choose this over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the explain-first regression bundle and return a unified verdict.
| Name | Required | Description | Default |
|---|---|---|---|
| root_prefix | No | ./tests/artifacts/mcp/project_regression | |
| trace_db_path | No | ||
| benchmark_iterations | No | ||
| scenario_iterations | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose any behavioral traits such as side effects, permissions, or destructiveness. The agent lacks critical safety information.
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 very short but under-specified, omitting essential details. It sacrifices completeness for brevity.
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 presence of 4 parameters with defaults, no annotations, and no output schema details, the description is incomplete. It does not cover prerequisites or side effects.
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?
The description provides no information about parameters. With 0% schema description coverage, the agent gets zero additional meaning beyond parameter titles and defaults.
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 the tool runs an explain-first regression bundle and returns a unified verdict, but it does not differentiate from sibling tools like 'explain_regression_suite' or 'project_run_heuristic'. The purpose is vaguely stated without specific scope.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of when-not or suggested preconditions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full MCP tool catalog with groups, entrypoints, and summaries.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden for behavioral disclosure. It does not mention side effects, authentication, rate limits, or that it is a read-only operation. The description only states what it returns.
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 concise sentence that avoids unnecessary words. However, it could benefit from slight expansion to cover the parameter.
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?
For a simple catalog tool, the description captures the main purpose. However, it is incomplete due to the lack of parameter explanation and usage guidance. The presence of an output schema partially compensates.
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 description does not explain the 'group' parameter beyond mentioning 'groups' in the output. The parameter likely filters the catalog, but no details are given, leaving the agent to infer meaning.
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 clearly states the tool returns a full MCP tool catalog with groups, entrypoints, and summaries. This is a specific verb-resource combination that distinguishes it from sibling tools that perform other operations.
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?
No explicit guidance on when to use this tool versus alternatives. It is implied that this is for browsing available tools, but no exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a declared entity in the generic state store.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | No | generic_entity | |
| entity_id | No | ||
| payload_json | No | {} | |
| root_dir | No | ||
| merge | No | ||
| dry_run | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states the operation (upsert) but fails to disclose behavioral traits like side effects, idempotency, permissions, or what happens on conflict.
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?
Description is a single sentence with no extraneous text, but it is too brief to be truly helpful. It lacks structure and could be expanded without losing conciseness.
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?
Despite having 6 parameters, an output schema, and significant complexity, the description provides no contextual information. It does not explain how the parameters work together, the purpose of the tool, or expected behavior. 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%, and the description does not mention any parameter. It adds no meaning beyond the schema's property names and types. Parameters like 'merge' and 'dry_run' are 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?
Description clearly states the action (create or update) and the resource (declared entity in generic state store). It differentiates from sibling tools like project_delete_entity. However, 'declared entity' could be more specific.
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?
No guidance on when to use this tool versus alternatives (e.g., project_get_entity, project_delete_entity). No conditions for use or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append one MCP tool trace record to local trace store.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| tool_name | Yes | ||
| status | Yes | ||
| summary | Yes | ||
| error_text | No | ||
| elapsed_ms | No | ||
| scenario_id | No | adhoc | |
| correlation_id | No | ||
| attempt | No | ||
| retry_classification | No | not_applicable | |
| decision_reason | No | ||
| actual_effects | No | ||
| trace_db_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states 'append' but does not disclose idempotency, error behavior, permission needs, or side effects beyond the basic action.
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 one efficient sentence with no wasted words. However, it is so brief that it sacrifices necessary detail.
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 complexity (13 parameters, no schema descriptions, no annotations, an output schema not described), this minimal description is insufficient. It does not explain the trace store context or return format.
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 description adds no meaning to any of the 13 parameters (4 required). Parameter names like run_id, tool_name are self-explanatory, but the description does not explain how to use 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?
The description clearly states the verb 'Append' and the resource 'one MCP tool trace record to local trace store', distinguishing it from sibling tools like 'insert_row' or 'upsert_row' which are generic logging tools.
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?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Incrementally ingest project docs, code, and config files.
| Name | Required | Description | Default |
|---|---|---|---|
| source_dir | No | ./docs | |
| trace_db_path | No | ||
| refresh_state_path | No | ||
| scenario_id | No | knowledge | |
| include_extensions | No | .md,.py,.rs,.toml,.json,.yaml,.yml | |
| exclude_dir_names | No | .git,.idea,.pytest_cache,.venv,__pycache__,node_modules,target | |
| exclude_path_parts | No | tests/artifacts | |
| max_file_bytes | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral disclosure. It states 'incrementally ingest', hinting at non-destructive updates, but does not mention side effects, idempotency, required permissions, or error handling.
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 sentence with no filler, achieving brevity. However, it is arguably too terse given the complexity of the tool, sacrificing necessary detail for conciseness.
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 8 parameters and an output schema, the description provides minimal context. It does not mention return values, how incremental ingestion differs from full ingestion, or how parameters affect behavior. Sibling tool descriptions (e.g., 'refresh_trace_path') are not referenced.
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 tool description provides no explanation of any of the 8 parameters (source_dir, trace_db_path, etc.). The agent receives zero guidance on parameter meaning or usage.
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 clearly states the tool's action ('ingest') and scope ('project docs, code, and config files'), and includes the qualifier 'incrementally' which adds nuance. While it does not explicitly differentiate from siblings like 'refresh_trace_path', the resource type (docs vs. traces) implies distinction.
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?
No guidance on when to use this tool versus alternatives such as 'refresh_trace_path' or 'project_ingest_trace'. The description lacks any contextual usage hints or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Incrementally ingest new lines from source path into trace store.
| Name | Required | Description | Default |
|---|---|---|---|
| source_path | Yes | ||
| trace_db_path | No | ||
| refresh_state_path | No | ||
| scenario_id | No | refresh |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It says 'incrementally' but does not disclose effects on existing data, concurrency, or how duplicate lines are handled.
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?
A single sentence, no wasted words. However, it could benefit from more structure (e.g., bulleted parameter roles).
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 4 parameters with 0% schema description coverage and an output schema, the description is too brief. It does not explain return values or usage context.
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 description only mentions 'source path' indirectly. It does not explain trace_db_path, refresh_state_path, or scenario_id parameters.
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 'Incrementally ingest new lines from source path into trace store' uses a specific verb (ingest) and resource (trace store), and distinguishes from siblings like refresh_docs_path by specifying 'trace' and 'incrementally'.
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?
No guidance on when to use this tool vs. alternatives such as refresh_docs_path or project_ingest_trace. The description does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-index this project dataset (engine_cli index).
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/engine_data | |
| table | No | orders |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only says 'Re-index this project dataset' without disclosing whether the operation is destructive, requires specific permissions, or has side effects. The reference to 'engine_cli index' is vague.
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 sentence, which is concise, but it is too minimal to be effective. It could be restructured to include more detail without becoming verbose.
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?
Despite the presence of an output schema (not shown), the description fails to explain the scope of reindexing, potential impacts, or any prerequisites. For a tool that modifies data, this is insufficient.
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?
The schema has two parameters with no descriptions (0% coverage), and the description does not mention or explain them. The agent receives no additional meaning about 'root_dir' or 'table' beyond their names and defaults.
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 clearly states the action (re-index) and the resource (this project dataset). It adds context with '(engine_cli index)' hinting at the underlying command. However, it does not distinguish from the sibling tool 'create_index', which might be a related but different operation.
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?
No guidance is provided on when to use this tool versus alternatives like 'create_index' or other project-related tools. The description lacks context about prerequisites or appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Increment and persist split-logic drift bug counter.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| counter_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'increment and persist', implying mutation, but lacks details on idempotency, permissions, side effects, or behavior with empty parameters.
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 extremely concise (6 words). It is front-loaded and efficient, but could benefit from a bit more detail without becoming verbose.
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 tool has an output schema but the description doesn't mention it or the return value. With only two optional parameters, the description is too minimal to be complete; it omits important context like parameter roles and output.
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 should explain parameters. It mentions 'counter' but doesn't explain 'note' or 'counter_path'. Their purpose is unclear, leaving ambiguity.
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 clearly states the tool's action: increment and persist a counter related to split-logic drift bugs. It's specific and distinguishes it from sibling tools that might handle other types of counters or operations.
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?
No guidance is provided on when to use this tool versus alternatives, nor any conditions or prerequisites. The description simply states what it does without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute full MiniPG + MiniDatabricks + DuckDB end-to-end flow.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/e2e/data |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'execute full ... flow' without disclosing side effects, prerequisites, or behavioral implications. This leaves the agent uninformed about what happens during execution.
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 sentence, which is concise but could benefit from additional detail without becoming verbose. It is not excessively long but lacks structured 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?
The tool has an output schema but no description of return values. With only one optional parameter and no behavioral context, the description is insufficient for an agent to fully understand the tool's role in the sibling tool set.
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?
The single parameter 'root_dir' has no description in the schema or the tool description. With 0% schema description coverage, the agent receives no additional meaning beyond the parameter name and default value.
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 clearly states the tool executes a specific end-to-end flow involving MiniPG, MiniDatabricks, and DuckDB. The verb 'Execute' and the named components distinguish it from sibling tools, though the exact nature of the flow could be expanded.
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?
No guidance is provided on when to use this tool versus alternatives like project_run_heuristic or scenario_load_test. The description lacks context for ensuring correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mixed workload load test: insert/upsert/explain/reindex/e2e and summary metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| iterations | No | ||
| root_dir | No | ./tests/artifacts/mcp/scenario | |
| table | No | orders | |
| min_success_rate | No | ||
| max_overall_p95_ms | No | ||
| max_e2e_p95_ms | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions operations (insert, upsert imply writes) but does not clarify if it modifies state, safety, or idempotency. Behavioral traits are mostly undisclosed.
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 very short but starts with a noun phrase instead of a verb. It lacks a clear action statement and wastes space on a colon without adding necessary details.
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?
Despite having 6 parameters and an output schema, the description provides almost no context about return values, parameter effects, or use cases. Largely 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%, and the description does not explain any of the 6 parameters (iterations, root_dir, etc.). Fails to add meaning beyond the empty schema.
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 lists operations (insert, upsert, etc.) and states it's a mixed workload load test, but lacks an explicit verb (e.g., 'runs', 'executes'). It indicates what it does but is ambiguous compared to siblings like 'benchmark_calls'.
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?
No guidance on when to use this tool vs alternatives like 'benchmark_calls' or 'run_e2e_flow'. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-shot: load schema → run EXPLAIN (from query_profiles_json/seed_sql_json) → evaluate. Generic: you supply queries and optional seed SQL.
| Name | Required | Description | Default |
|---|---|---|---|
| schema_path | No | ||
| ddl_text | No | ||
| schema_entity_id | No | schema_entity | |
| query_profiles_json | No | {} | |
| seed_sql_json | No | [] | |
| query_profile_names | No | ||
| root_dir | No | ||
| artifacts_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose side effects (e.g., mutations, state changes) or behavioral traits like required permissions or resource consumption. It only hints at running EXPLAIN but not whether it modifies anything.
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, but the second sentence is vague ('Generic: you supply queries...'). Could be more informative without much added length.
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 8 parameters, no parameter descriptions, and no output schema details despite an output schema existing, the description is severely incomplete. It fails to guide the agent on using the tool properly.
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?
All 8 parameters have 0% schema description coverage. The description mentions query_profiles_json and seed_sql_json but does not explain their format, purpose, or defaults. No guidance on how to supply queries or seed SQL.
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 it loads schema, runs EXPLAIN, and evaluates, which is a specific sequence of actions. However, 'evaluate' is vague and it doesn't clearly differentiate from sibling tools like schema_evaluate_tool or schema_explain_tool.
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?
No guidance on when to use this tool versus alternatives. The phrase 'One-shot' implies convenience but lacks explicit context for when it's appropriate or when to prefer other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build verdict from schema metadata and EXPLAIN outputs; write evaluation_report.json and verdict.md. If query_profile_names empty, discovers explain_*.txt in artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
| schema_entity_id | No | schema_entity | |
| query_profile_names | No | ||
| root_dir | No | ||
| artifacts_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It mentions file writing (evaluation_report.json, verdict.md) and auto-discovery of EXPLAIN outputs, adding value. However, it omits potential side effects (overwriting files) and safety profile (non-destructive? permissions?), leaving gaps.
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, front-loaded with main action, second adding key conditional. No redundant words; every sentence adds meaning.
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?
Description covers core functionality and a conditional behavior, but lacks details on output contents, role of each parameter, and differentiation from sibling tools. Given output schema exists, some gaps are acceptable, but not fully compensated.
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 0%, so description must compensate. It partially explains query_profile_names (triggering discovery), but other params (schema_entity_id, root_dir, artifacts_dir) are not described beyond their names and defaults, providing minimal added value.
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?
Description clearly states verb 'Build verdict' and resources (schema metadata, EXPLAIN outputs) producing two files. It distinguishes from siblings like schema_explain_tool by focusing on verdict generation, though not explicitly differentiating.
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?
No guidance on when to use this tool vs alternatives (e.g., schema_evaluate_full_tool). Description does not mention context, prerequisites, or exclusions, leaving agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run EXPLAIN for each profile in query_profiles_json (JSON: name -> SQL). Optional seed_sql_json (JSON array of SQL) runs before EXPLAIN. Writes explain_.txt.
| Name | Required | Description | Default |
|---|---|---|---|
| schema_entity_id | No | schema_entity | |
| query_profiles_json | No | {} | |
| seed_sql_json | No | [] | |
| root_dir | No | ||
| artifacts_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the main action (EXPLAIN) and output file creation. However, it omits side effects, permission requirements, error handling, and whether operations are idempotent.
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, front-loaded with the core action, no unnecessary words. Efficient and clear.
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 5 parameters and output schema, the description lacks details on directory variables (root_dir, artifacts_dir), output format, and error states. The output schema exists but its content is not mentioned. More context is needed for safe use.
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 0%, but description explains only query_profiles_json and seed_sql_json. The other three parameters (schema_entity_id, root_dir, artifacts_dir) are not described, leaving their roles unclear.
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 clearly states it runs EXPLAIN for each profile in query_profiles_json and writes output files. However, it does not explicitly differentiate from sibling tools like explain_run, which might be for single queries.
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?
No guidance on when to use this tool versus alternatives. Prerequisites, exclusions, or context for use are missing. The description only states what it does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest DDL from file or raw text, validate with DuckDB, store metadata in project state (schemas/).
| Name | Required | Description | Default |
|---|---|---|---|
| schema_path | No | ||
| ddl_text | No | ||
| schema_entity_id | No | schema_entity | |
| root_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses core behaviors: validation with DuckDB and storage in project state. However, it lacks details on side effects (e.g., overwriting existing schemas), error handling, or required permissions, leaving gaps in transparency.
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 15-word sentence that front-loads the action and includes all key elements (ingest, validate, store). No extraneous words, making it efficient and easy to parse.
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?
While the tool has an output schema (not shown), the description is too brief to cover essential context for a tool with 4 undocumented parameters. It omits details about DuckDB prerequisites, metadata format, and error behavior, leaving the agent with significant unknowns.
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 mentions 'from file or raw text' hinting at schema_path and ddl_text, and 'store in project state' hinting at schema_entity_id and root_dir, but does not explain parameter formats, defaults, or relationships. The description adds only partial meaning beyond parameter names.
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 uses a specific verb ('Ingest') and resources ('DDL from file or raw text'), explicitly stating validation and storage actions. It distinguishes from sibling schema tools like schema_evaluate_tool by focusing on loading rather than evaluation.
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 when to use the tool (to load DDL from file or text) but does not explicitly compare it to alternatives or provide exclusions. Sibling tools like schema_evaluate_tool suggest different use cases, but the description does not clarify when to choose this over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find semantically similar historical incidents.
| Name | Required | Description | Default |
|---|---|---|---|
| query_text | Yes | ||
| top_k | No | ||
| min_score | No | ||
| status | No | error | |
| tool_name | No | ||
| scenario_id | No | ||
| start_time_utc | No | ||
| end_time_utc | No | ||
| trace_db_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description only repeats the tool's purpose. It fails to disclose behavioral traits such as side effects, authentication needs, or what 'semantically similar' entails.
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 sentence that is too minimal to be useful. It lacks structure and does not justify its place beyond restating the tool name.
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 tool's complexity (9 parameters, no schema descriptions, no annotations), the description is severely incomplete. It does not explain how to use parameters or interpret output, even though an output schema exists.
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 9 parameters and 0% schema description coverage, the description adds no meaning beyond the schema. It does not explain what any parameter does, including required query_text.
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 clearly states the tool finds semantically similar historical incidents, using a specific verb and resource. However, it does not differentiate from siblings like memory_search that may also perform semantic search.
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?
No guidance is provided on when to use this tool vs alternatives. The description offers no exclusions or context about use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upsert one row by order_id.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | ./tests/artifacts/mcp/engine_data | |
| table | No | orders | |
| order_id | No | ||
| customer_id | No | ||
| amount | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description fails to disclose behavioral traits like side effects, error handling, or required permissions. Minimal context for a write operation.
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?
Extremely concise (6 words), front-loaded with key info. However, brevity sacrifices completeness; could expand without losing clarity.
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 5 unannotated parameters, 0% schema coverage, and no output schema details, description fails to provide sufficient context 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 0%, and description only mentions order_id. Other parameters (root_dir, table, customer_id, amount) are not explained, leaving agent without usage 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?
Description clearly states 'Upsert one row by order_id', specifying verb (upsert) and resource (row) with a key identifier. Differentiates from sibling 'insert_row'.
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?
No guidance on when to use this tool vs alternatives like insert_row. Missing context on prerequisites or scenarios where upsert is appropriate.
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. Dates show when Glama detected each change.
v0.1.12benchmark_callscapture_roi_baselinecreate_indexdecision_gatedemo_explain_concurrency_failure_stormdemo_explain_idempotency_conflictdemo_explain_rundemo_explain_run_failuredemo_explain_semantic_failureexplain_customerexplain_regression_suiteexplain_runhealth_checkinit_engineinsert_rowmemory_searchmemory_upsertproject_append_eventproject_capabilitiesproject_capture_baselineproject_compare_baselineproject_delete_entityproject_explain_runproject_export_stateproject_get_defaultsproject_get_entityproject_ingest_traceproject_list_entitiesproject_list_heuristicsproject_manifestproject_run_heuristicproject_run_regressionproject_tool_catalogproject_upsert_entityrecord_tool_tracerefresh_docs_pathrefresh_trace_pathreindex_projectreport_drift_bugrun_e2e_flowscenario_load_testschema_evaluate_full_toolschema_evaluate_toolschema_explain_toolschema_load_toolsimilar_incidentsupsert_rowMany tools have overlapping purposes, particularly the multiple 'explain' and 'project_*' tools are hard to distinguish. The demo, benchmark, and schema tools also have unclear boundaries, making selection confusing for an agent.
Naming conventions are inconsistent: some use underscore (benchmark_calls), some use project_ prefix, others schema_ prefix, and demo_explain_*. While groups have internal consistency, the overall pattern is mixed and unpredictable.
47 tools is excessive for a single server. Many tools could be consolidated or split into separate servers. The count feels bloated and hard to navigate.
The tool set appears to cover many areas (benchmarking, demo, schema management, project state) but lacks clear CRUD coverage for key entities and has dead ends (e.g., no delete for most entities). Gaps in lifecycle operations are notable.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
MCP observability. Query live traffic, errors, duration, and alerts from your AI agent.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kroq86/data-engineering-runtime-lab'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
