Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Data Engineering MCP Server what went wrong with the orders ETL job this morning?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A small, runnable Model Context Protocol server for data-engineering investigation workflows. It uses the official MCP Python SDK, Pydantic validation, SQLite synthetic data, and a service/repository architecture that is easy to study and replace with production adapters.
MCP is an open protocol that lets an AI host discover and use external context and capabilities through a standard server interface. This project demonstrates all three primitives:
Primitive | Meaning | Example |
Tool | An operation the model may invoke |
|
Resource | Read-only context addressed by a URI |
|
Prompt | A reusable interaction template |
|
The MCP client discovers capabilities, chooses a tool from its schema, sends structured arguments, and receives structured content. MCP is complementary to function calling: function calling is usually a model/API feature, while MCP standardizes how tools and context are exposed by an external server and reused by many hosts.
Related MCP server: Claude MCP Data Engineer Server
Data engineers repeatedly inspect ETL status, logs, schemas, incidents, runbooks, and read-only data. This server exposes those operations once so an MCP-compatible AI client can use them without a custom integration for every application.
flowchart TD
A[AI Client / MCP Host] -->|stdio MCP protocol| B[FastMCP Server]
B --> C[Tools]
B --> D[Resources]
B --> E[Prompts]
C --> F[Application Services]
F --> G[Repository]
G --> H[(Synthetic SQLite)]get_job_status(job_name): latest status, run time, duration, and records.
get_job_logs(job_name, run_id, severity, limit): bounded structured logs.
get_job_history(job_name, days): recent executions.
get_database_schema(table_name): columns, types, nullability, keys, and indexes.
validate_sql(sql): accepts one SELECT or WITH statement only.
execute_readonly_sql(sql, limit): validates and executes a bounded read-only query.
search_documentation(query, top_k): searches synthetic runbooks.
search_incidents(query, limit): searches historical synthetic incidents.
analyze_job_failure(job_name, run_id): deterministic evidence gathering, not an autonomous agent.
All tool errors are structured and internal stack traces are kept in server logs. Audit logs include request ID, tool, status, duration, and non-sensitive argument metadata.
Resources: resource://jobs, resource://incidents, resource://database/schema, and resource://documentation. A resource provides contextual read-only data; it does not perform an action or decide how the data should be used.
Prompts: investigate_etl_failure(job_name, run_id) and analyze_sql(sql). A prompt is a reusable workflow instruction for an MCP host. It guides tool selection but does not itself execute the investigation.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python scripts/init_db.py
python -m data_engineering_mcp.serverThe server uses stdio, so it should be launched by an MCP host rather than opened in a browser. Run the real MCP client demo with:
python -m data_engineering_mcp.client_demoThe demo initializes an MCP session, lists tools/resources/prompts, and invokes three tools. The core project requires no LLM API key.
docker compose up --buildThe compose service is intentionally stdio-oriented. An MCP host that supports launching container commands can run the container as its MCP server process. An HTTP transport can be added later when a deployment target requires a remotely reachable server.
Copy .env.example to .env for local overrides. Only synthetic data is included. Credentials are never returned by schema tools and .env/SQLite files are ignored by Git.
SQL execution is defense-in-depth: it accepts only a single SELECT or WITH, rejects write and administrative keywords, uses parameterized repository queries for application operations, and enforces a row limit. The demo uses SQLite and a short connection timeout; production should add a dedicated read-only database identity and a database-enforced statement timeout.
The seed creates 10 ETL jobs, 120 executions, 360 logs, 35 incidents, 10 documents, and relational sample tables (customers, products, orders, order_items).
python -m pytest -qThe 20 evaluation scenarios are in evaluation/scenarios.json. They cover status, failure analysis, schema, searches, safe SQL, bounded queries, invalid input, and error cases. A full production evaluation would also measure tool-selection accuracy, argument accuracy, latency, and false-positive SQL rejection.
The MCP decorators are adapters only. The path is MCP tool -> service -> repository -> database, so replacing synthetic SQLite with PostgreSQL, a monitoring API, Confluence, Jira, or Azure adapters does not require rewriting the MCP layer. The current integrations are synthetic; no real vendor integration is claimed.
Production improvements would include authentication at the host boundary, per-tool authorization, a real read-only database role, rate limiting, query cancellation, distributed audit logs, metrics/traces, secret management, and contract tests against each adapter.
60-second explanation: This is an official-SDK MCP server for data-engineering support. An MCP host discovers nine typed tools, four read-only resources, and two reusable prompts over stdio. Tools call Pydantic-validated application services backed by synthetic SQLite. SQL is restricted to bounded read-only queries, errors are structured, and audit logs capture request metadata.
Five-minute architecture: The host starts the stdio server and initializes an MCP session. FastMCP publishes schemas and capability metadata. The host selects a tool and sends JSON arguments. The tool adapter calls a service, which validates policy and delegates to a repository. The repository uses SQLite. Results return as structured JSON content. Resources expose catalogs by URI, while prompts provide reusable workflows. In production, adapters can target monitoring, warehouse, documentation, and incident systems independently.
Common interview answers: MCP is a reusable protocol boundary, not an LLM; a server exposes capabilities and a client/host consumes them; tools are action-oriented, resources are contextual, and prompts are workflow templates. Security comes from narrow schemas, authorization, read-only identities, limits, timeouts, validation, and audit logs. If a tool fails, the client receives a safe structured error while detailed diagnostics stay server-side. Scale by making services stateless, moving state to managed stores, adding connection pooling and rate limits, and horizontally scaling transport workers. MCP is not needed for a single internal function call or when a stable ordinary API already fully solves the integration.
Difficult questions to practice: How is tool discovery different from REST documentation? Where should authorization run? How do you prevent prompt injection from tool output? How do you handle pagination? How do you version schemas? How do you cancel long queries? How do you test host compatibility? How do you trace one request across tools? How do you isolate tenants? How do you handle partial failure? How do you select a read replica? How do you prevent data exfiltration? How do you rotate secrets? How do you cache resources safely? How do you roll out a breaking tool change?
Scenario questions: diagnose a timeout, explain a schema mismatch, reject an unsafe query, handle an unknown run, select between a resource and a tool, investigate an incident with evidence, control a high-cost query, recover from a downstream outage, explain a failed prompt workflow, and migrate SQLite to PostgreSQL.
git init
git add .
git commit -m "Build data engineering MCP server"
git branch -M mainResume bullets: built an official MCP Python server exposing typed data-engineering tools, resources, and prompts; implemented read-only SQL policy, bounded execution, structured errors, and audit logging; generated deterministic synthetic ETL data and an MCP stdio client with pytest coverage and Docker packaging.
This is a local portfolio and interview project. It does not provide real cloud, warehouse, Jira, Confluence, authentication, or LLM integrations. SQLite is suitable for study and deterministic tests, not a high-concurrency production control plane.
Prepare deterministic evidence for a failed ETL run.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| job_name | Yes |
| 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 behavioral burden. It hints at determinism but does not disclose whether the tool is read-only, whether it executes anything, what side effects it has, or how 'evidence' is produced.
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, front-loaded sentence with no wasted words. It is concise and readable, though 'deterministic evidence' is somewhat jargon-heavy and could be clarified without losing 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?
With an output schema present, return values are likely covered. However, the absence of usage guidance, behavioral details, and parameter explanation leaves meaningful gaps for an agent trying to decide when and how to invoke this tool 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%, and the description does not explain job_name or run_id. It adds only the context that the run is a failed ETL run, which helps interpret run_id, but leaves parameter formats and semantics mostly to inference from the property titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Prepare deterministic evidence') and a clear resource ('a failed ETL run'). It differentiates from siblings like get_job_status and get_job_logs by focusing on failure evidence, though it could be more explicit about what 'evidence' includes.
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 phrase 'for a failed ETL run' implies a context, but the description gives no guidance on when to choose this over get_job_logs, get_job_status, or get_job_history. 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.
Execute a bounded SELECT or WITH query against the synthetic database.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| limit | 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 behavioral disclosure burden. It discloses that the query is bounded and restricted to SELECT/WITH constructs, which strongly implies no mutation, but it does not describe failure behavior, pagination, or the exact effect of the limit.
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?
One clear, front-loaded sentence with no filler. Every word contributes: the action, the SQL constraint, and the target database are all present.
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 is simple, has an output schema, and only two parameters, so the description covers many essentials. But it leaves multi-dimensional gaps open: no mention of the synthetic environment, how validate_sql fits, or what constitutes a 'bounded' query in terms of the actual limit.
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 only mentions 'bounded', which hints at the limit parameter, but it doesn't explain the sql parameter content, the role of limit, or how limits are applied. This is minimal additional meaning over the raw 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 names the specific action ('Execute'), the resource ('synthetic database'), and the exact SQL scope ('SELECT or WITH'), which clearly differentiates it from siblings such as validate_sql and get_database_schema. The read-only intent is explicit and tied to the query type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the appropriate usage context: run a bounded, read-only SELECT/WITH query against the synthetic database. However, it does not explicitly mention when not to use it or point to alternatives like validate_sql for pre-flight validation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return table columns and indexes without credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | Yes |
| 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. It discloses a useful behavioral trait: no credentials are needed, which suggests a read-only, low-risk operation. However, it does not state explicitly that it is read-only, nor does it describe error behavior, performance implications, or what happens if the table does not exist. The disclosure is minimal but not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and resource, with no filler. It is front-loaded and efficient, conveying the core purpose in ten words. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the existence of an output schema, the description might be adequate for basic invocation. However, it lacks any mention of prerequisites, error cases, or how the output relates to the parameter. It also does not provide usage context, such as when this tool is preferred over reading schema from elsewhere. For a schema-retrieval tool, the absence of any limitation or format details makes it only minimally complete.
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 for explaining the parameter. The only parameter, table_name, is not mentioned in the description at all. The description says 'Return table columns and indexes' but does not clarify that the table_name parameter identifies which table to query. This leaves the agent to infer the mapping. The description adds no value beyond the bare 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 clearly states the verb 'Return' and the resource 'table columns and indexes', which is specific and distinguishes this from sibling tools like get_job_status or validate_sql. It also adds 'without credentials', which clarifies the access requirement. However, it doesn't explicitly mention that it operates on a single table, though the required parameter table_name implies that. It is slightly less precise than the 'List ALL calls' example, but still strong.
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 any conditions for use, exclusions, or relationships to siblings such as execute_readonly_sql or validate_sql. The only context is 'without credentials', which implies a safe, low-privilege operation but does not explain why one would choose this over other schema-related tools. No alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return recent executions for an ETL job.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| job_name | Yes |
| 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 of behavioral disclosure. It only states 'return recent executions' and does not describe any side effects, limitations, or operational characteristics (e.g., read-only, pagination, cost). This is a minimal statement that leaves behavior largely opaque.
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 with no redundancy, front-loading the core purpose. However, its brevity comes at the cost of missing essential context, but for conciseness alone it is effective and avoids wasted words.
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 two parameters, no annotations, and an output schema (which is unknown), the description is incomplete. It fails to explain parameter usage, any behavioral nuances, or how the output relates to the tool's purpose. An agent would need to infer too much to call this 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 does not compensate by explaining job_name or days. It does not mention that job_name is required or that days controls the lookback period. The description adds no meaning to the parameters beyond the schema's bare structure.
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 recent executions for an ETL job, using a specific verb and resource. It is distinct from sibling tools like get_job_status (current status) and get_job_logs (logs), so an agent can differentiate without further information.
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 get_job_status or get_job_logs, nor when one would prefer history over status or logs. There is no exclusions or context that would help an agent pick this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return bounded structured logs for an ETL job execution.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| run_id | No | ||
| job_name | Yes | ||
| severity | 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 mentions 'bounded' but does not explain default limit behavior, ordering, whether all runs are included if run_id is null, or the output format beyond 'structured'. The lack of pagination or filter details leaves significant ambiguity.
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 fluff. It efficiently conveys the core purpose without repetition, making it appropriately sized and structured.
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 an output schema exists (reducing the need to explain return values), the description still omits critical usage context: how to filter by run or severity, the effect of the limit, or how this differs from job history. The tool's utility is compromised without these details.
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 does not mention any of the four parameters (job_name, run_id, limit, severity) or their meanings. The agent must infer everything from the schema, which lacks 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 states a specific verb ('Return') and resource ('bounded structured logs') tied to 'ETL job execution', clearly distinguishing it from sibling tools like get_job_status or get_job_history. The qualifiers 'bounded' and 'structured' add precision.
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 given on when to use this tool versus siblings such as get_job_history or analyze_job_failure. There is no mention of scenarios where logs are needed versus status or history, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the latest execution status for an ETL job.
| Name | Required | Description | Default |
|---|---|---|---|
| job_name | Yes |
| 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 only says 'Return' which implies read-only, but it does not explicitly state safety, side effects, or any constraints. It also omits any details about the response beyond the existence of an output schema.
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 fluff, and the core action is front-loaded. However, it is overly terse given the missing behavioral and usage details, though that is a completeness issue rather than a conciseness one.
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 a single parameter, no annotations, and many sibling tools, this description is inadequate. It does not explain when to prefer it, what job_name should contain, or any behavioral caveats. The presence of an output schema covers return values, but that is the only completeness provided.
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 0% description coverage, and the description only hints that job_name refers to an ETL job. It does not explain the format, expected values, or how to obtain a valid job_name, so it fails to compensate for the missing schema documentation.
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 (return) and the resource (latest execution status for an ETL job). It is distinct from siblings like get_job_logs or get_job_history, but it does not explicitly differentiate itself from them, so it stops short of 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?
There is no guidance on when to use this tool versus alternatives such as get_job_logs or get_job_history. No context is provided about prerequisites 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.
Search synthetic data engineering runbooks.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | 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 of behavioral disclosure. It does not mention whether the search is read-only, whether it returns snippets or full documents, how top_k affects results, or any rate limits. The description is too thin to inform an agent about the tool's behavior beyond the basic search 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, short sentence that is front-loaded with the key action and resource. It is appropriately concise, though it could add a bit more context 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?
Given the tool has an output schema, the return format is covered, but the description lacks guidance on query formulation, top_k behavior, and the scope of the runbooks. With no annotations and 0% schema description coverage, the description is not complete enough for an agent to use the tool effectively in all cases.
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 for the schema's lack of parameter documentation. The description only mentions 'search' and 'runbooks' but does not explain what the query parameter should contain, how top_k influences results, or any constraints. The schema provides only names and types, leaving the agent to guess at 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?
The description states a specific verb ('Search') and a clear resource ('synthetic data engineering runbooks'), which distinguishes it from siblings like get_job_status or validate_sql. It is concise and unambiguous, though it does not explicitly name a sibling alternative.
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: use this tool to search runbooks. It does not explicitly state when to use it versus alternatives like search_incidents or analyze_job_failure, but the resource type ('runbooks') provides enough context for an agent to infer the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search historical synthetic incidents.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden of behavioral disclosure. It reveals only that incidents are 'historical synthetic' data but does not state whether the operation is read-only, how matching works, or how results are ordered; the output schema may cover return shape, but behavior beyond that is 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 sentence is extremely concise and front-loads the resource, with no filler words. However, it is under-specified for an AI caller: it omits usage guidance and parameter semantics, so the brevity comes at the cost of completeness.
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 2-parameter search tool with an output schema, the description is not completely inadequate because it names the resource. Yet it leaves usage, matching behavior, and parameter semantics unspecified, forcing the agent to guess how to construct a valid query.
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 compensate. It does not explain what the required 'query' means, whether 'limit' caps the result count, or any format expectations. The only available parameter information comes from type/default fields 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 uses a specific verb ('Search') and a clear resource ('historical synthetic incidents'), which distinguishes it from the job-, database-, and documentation-focused siblings at a high level. It does not explicitly contrast itself with search_documentation, but the resource noun alone largely disambiguates.
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 given about when to use this tool versus alternatives, what scenarios it fits, or when it should not be used. The agent must infer domain fit solely from the resource name, with no exclusion criteria or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether SQL is a single safe read-only query.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes |
| 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 of disclosing behavior. It only says 'check whether' but does not describe what happens on validation failure (e.g., error vs. boolean return), whether the tool has side effects (it likely doesn't), or what the output structure looks like. The description is too sparse to convey behavioral expectations.
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 waste, but it is under-specified. It omits crucial details about validation behavior and output, making it too terse to be useful. While conciseness is valued, this goes beyond brevity into incompleteness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists but its content is unknown, and the description does not explain what the tool returns (e.g., boolean, validation messages). For a validator, it's critical to know the result format and how failures are reported. The description lacks this context, making it incomplete for an agent to use effectively.
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 description coverage for the single 'sql' parameter. The description adds no information about the parameter's format, constraints, or examples. It merely mentions 'SQL' without elaborating on what constitutes a valid input, so the agent gets no additional semantic value beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Check') and resource ('SQL'), and indicates it validates safety and read-only nature. However, it doesn't clarify what 'safe' or 'single' means precisely, nor does it distinguish itself from sibling tools like execute_readonly_sql. The purpose is understandable but lacks specificity.
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 that this might be a pre-execution validation step for execute_readonly_sql, nor does it state any conditions or exclusions. The intended usage must be inferred by the agent.
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.
v0.1.0analyze_job_failureexecute_readonly_sqlget_database_schemaget_job_historyget_job_logsget_job_statussearch_documentationsearch_incidentsvalidate_sqlScored across 9 tools
Most tools target distinct resources and actions: job status, logs, history, schema, SQL validation/execution, documentation, incidents, and failure analysis are clearly separated. The only mild overlap is get_job_status versus get_job_history, since both relate to recent execution state, but the descriptions clarify that one returns the latest status and the other returns a list of executions.
All tool names follow a consistent verb_noun pattern using lowercase snake_case, such as get_job_status, validate_sql, search_incidents, and analyze_job_failure. The verb varies based on the action, but the structure is uniform and predictable.
Nine tools is well-scoped for a data engineering support server. Each tool serves a clear purpose across job inspection, read-only database access, documentation and incident lookup, and failure analysis without unnecessary redundancy.
The tool surface covers the core diagnostic workflow: inspect job execution, analyze schema, validate and run read-only SQL, search runbooks and incidents, and assemble failure evidence. A minor gap is the lack of a way to list all available jobs or tables directly, but search and schema tools help compensate.
List datasets, schemas, run APL queries, and use prompts for exploration, anomalies, and monitoring.
Agentic CI operations for build inspection, failure diagnosis, and runner troubleshooting.
Give your AI agents the tools to build, manage, and run automation workflows.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
