pipeline-doctor

diagnose_incident

Diagnose AWS data-pipeline failures from error text, logs, and config facts. Returns ranked candidate root causes with evidence, fix steps, and documentation links for Glue, MWAA, Athena, and Lake Formation.

Instructions

Diagnose a data-pipeline failure from error text, logs, and optional config facts.

service: glue | mwaa | athena | lakeformation (optional). config keys the engine reads:
connection, vpc.s3_endpoint, vpc.nat_gateway, security_group.self_referencing,
mwaa.min_workers/max_workers/running_workers, lakeformation.iam_allowed_principals,
lakeformation.ram_invitation.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "error": "<error>"
    },
    "name": "diagnose_incident"
  }
}

Input Schema

Name	Required	Description	Default
`logs`	No
`error`	Yes
`config`	No
`service`	No
`use_llm`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 3, 2026

TDQS

C2.8/5.0

Behavior2/5

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

No annotations are supplied, so the description carries the full burden. It never says whether the diagnosis is read-only, what the response contains (ranked hypotheses? matched patterns?), how it relates to list_failure_patterns, or what use_llm changes in latency, cost, or determinism. The enumeration of config keys the engine reads is a genuinely useful behavioral disclosure, but it is the only one.

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

Conciseness3/5

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

The purpose statement is front-loaded and waste-free. The follow-on block is compressed into slash-separated fragments ('connection, vpc.s3_endpoint, vpc.nat_gateway, ...') that are hard to scan, and the line break mid-list looks like a formatting artifact rather than deliberate structure.

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

Completeness2/5

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

For a five-parameter tool with no annotations, no output schema, and zero schema description coverage, the description leaves too much open: return shape, whether calling it has any side effects, and the role of use_llm are all absent. An agent can guess it is a read-only diagnostic, but guessing is what the description should prevent.

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

Parameters3/5

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 document the allowed values of 'service' and the recognized keys within 'config', which is real added meaning. But it says nothing about 'use_llm' (present in the schema, undefined anywhere) or about the expected granularity of 'error' vs 'logs'.

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

Purpose4/5

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

The first sentence gives a specific verb and resource: 'Diagnose a data-pipeline failure from error text, logs, and optional config facts.' The service enumerations (glue | mwaa | athena | lakeformation) further scope it as a multi-service counterpart to the per-service siblings. It does not, however, explicitly distinguish itself from diagnose_glue_job_run / diagnose_mwaa_environment / diagnose_athena_query.

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

Usage Guidelines2/5

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

No guidance on when to use this generic tool versus the three service-specific diagnose_* siblings, which is the single most important routing decision here. The only usage hint is that 'service' is optional, with no explanation of what happens when it is omitted.

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

Deploy Server