The Apache Airflow MCP Server enables AI agents (Claude, Cursor, VS Code Copilot, etc.) to monitor, debug, and manage Apache Airflow deployments. Key capabilities include:
Instance Management
List and describe configured Airflow instances (dev/staging/prod, secrets never exposed)
Resolve Airflow UI URLs (e.g., from PagerDuty/Datadog alerts) into structured identifiers (instance, dag_id, dag_run_id, task_id, try_number)
DAG & Run Inspection (Read)
List DAGs with pause state, UI links, and pagination
Get detailed DAG metadata and list/retrieve DAG runs with state filtering and ordering
Task Instance Inspection (Read)
List and inspect task instances (state, retries, timings, rendered templates, per-attempt log URLs)
Fetch logs with advanced filtering: by log level (error/warning/info), tail last N lines, context lines around matches, byte caps, and truncation metadata — optimized for LLM context windows
Dataset/Asset Events (Read)
Query dataset (Airflow 2) or asset (Airflow 3) events for a given URI
DAG & Run Management (Write — require approval)
Trigger DAG runs with optional config, logical date, custom run ID, and notes
Clear task instances across runs (with filters for task IDs, date ranges, upstream/downstream, dry-run support)
Clear all tasks in a specific DAG run (with dry-run support)
Pause/unpause DAG scheduling
Safety & Usability
Read-only mode (AIRFLOW_MCP_READ_ONLY=true): write tools are never registered
Destructive annotations: write tools prompt clients for confirmation before executing
Multi-instance support: one server manages multiple clusters with per-instance credentials
SSRF guard: unknown hosts in UI URLs are rejected
Airflow 2 & 3 compatibility: supports REST API v1 and v2, including JWT auth for Airflow 3
Request tracing: every response includes a request_id for log correlation
Provides tools to interact with Apache Airflow instances to inspect DAGs, monitor DAG runs, retrieve task logs, and perform write operations such as triggering DAGs and clearing task instances.
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., "@Apache Airflow MCP Server show me the logs for the failed task in the daily_etl DAG"
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.
Independent community project; not affiliated with or endorsed by the Apache Software Foundation.
Published through PyPI, GHCR, and the official MCP Registry. Reproducible scan reports, dependency audits, SBOMs, and provenance are attached to each immutable release.
Connect Claude, Cursor, VS Code, or another MCP client to your Apache Airflow deployments and help agents diagnose failed DAGs.
Paste an Airflow UI link from a PagerDuty/Datadog alert and ask "why did this fail?" — the agent resolves the URL, finds the failed tasks, pulls log errors filtered and bounded before the MCP response, and can re-trigger or clear runs. Write tools carry destructive-operation annotations that MCP clients can use to request confirmation.
🔍 Incident-response first — resolve Airflow UI URLs straight to the failing task, filter logs by error level with context lines, follow try_number semantics correctly (sensors included)
🏢 Multi-instance — one server for same-API-family dev/staging/prod targets, with per-instance credentials and an SSRF guard that rejects unknown hosts
🔒 Safety controls — opt-in read-only mode (AIRFLOW_MCP_READ_ONLY=true) that never registers write tools; write tools annotated as destructive; configured credentials are redacted from instance responses and operation logs
📉 Token-efficient — log tailing, level filtering, byte caps, and truncation metadata designed for LLM context windows
🧭 Airflow 2 and 3 — API v1/v2 adapters with live E2E against Airflow 2.11 and 3.3, including JWT auth
📎 Traceable — every response carries a request_id that matches the structured server logs
Related MCP server: Airflow MCP
uv tool install apache-airflow-mcp-server \
--with 'apache-airflow-client==3.3.0' # replace 3.3.0 with your Airflow versionAirflow 2.11? Use
--with 'apache-airflow-client==2.10.0'instead; 2.10.0 is the final generated v1 client and targets Airflow 2's stable API. See Airflow compatibility before using a different release.
The fastest path is a single instance configured entirely with environment variables — no config file needed.
claude mcp add airflow \
--env AIRFLOW_MCP_HOST=https://airflow.example.com \
--env AIRFLOW_MCP_USERNAME=admin \
--env AIRFLOW_MCP_PASSWORD=your-password \
--env AIRFLOW_MCP_READ_ONLY=true \
-- uvx --from apache-airflow-mcp-server \
--with apache-airflow-client==3.3.0 airflow-mcp --transport stdioAdd to claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"airflow": {
"command": "uvx",
"args": ["--from", "apache-airflow-mcp-server", "--with", "apache-airflow-client==3.3.0", "airflow-mcp", "--transport", "stdio"],
"env": {
"AIRFLOW_MCP_HOST": "https://airflow.example.com",
"AIRFLOW_MCP_USERNAME": "admin",
"AIRFLOW_MCP_PASSWORD": "your-password",
"AIRFLOW_MCP_READ_ONLY": "true"
}
}
}
}Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"airflow": {
"command": "uvx",
"args": ["--from", "apache-airflow-mcp-server", "--with", "apache-airflow-client==3.3.0", "airflow-mcp", "--transport", "stdio"],
"env": {
"AIRFLOW_MCP_HOST": "https://airflow.example.com",
"AIRFLOW_MCP_USERNAME": "admin",
"AIRFLOW_MCP_PASSWORD": "your-password",
"AIRFLOW_MCP_READ_ONLY": "true"
}
}
}
}Add to .vscode/mcp.json:
{
"servers": {
"airflow": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "apache-airflow-mcp-server", "--with", "apache-airflow-client==3.3.0", "airflow-mcp", "--transport", "stdio"],
"env": {
"AIRFLOW_MCP_HOST": "https://airflow.example.com",
"AIRFLOW_MCP_USERNAME": "admin",
"AIRFLOW_MCP_PASSWORD": "your-password",
"AIRFLOW_MCP_READ_ONLY": "true"
}
}
}
}Run the server yourself and point the client at the endpoint:
AIRFLOW_MCP_HOST=https://airflow.example.com \
AIRFLOW_MCP_USERNAME=admin AIRFLOW_MCP_PASSWORD=your-password \
AIRFLOW_MCP_READ_ONLY=true \
airflow-mcp --transport http --host 127.0.0.1 --port 8765{ "mcpServers": { "airflow": { "url": "http://127.0.0.1:8765/mcp" } } }Health check: GET /health → 200 OK.
"Why did the latest run of
etl_pipelinefail?""https://airflow.example.com/dags/etl_pipeline/grid — what happened here, and is it safe to clear?"
"Show the failed task's error context and tell me the smallest recovery action."
The server talks to Airflow through the generated apache-airflow-client.
For Airflow 3, match the client release to your Airflow release: generated
models can change within a major version, and a newer client is not guaranteed
to deserialize an older server's responses correctly. Airflow 2.11 uses the
final v1 client release, 2.10.0, against Airflow 2's stable API.
Your Airflow | REST API | Install | Live E2E status |
3.3 | v2 |
| ✅ 3.3.0 |
2.11 | v1 |
| ✅ Airflow 2.11 + final v1 client 2.10.0 |
3.0–3.2 | v2 | Pin the client to the deployed Airflow 3 version | 🧪 Not in the current live matrix |
2.5–2.10 | v1 | Use the final v1 client, | 🧪 Not in the current live matrix |
When api_version isn't set, the server assumes the API matching the installed
client (v1 for a 2.x client, v2 for 3.x). Set
AIRFLOW_MCP_API_VERSION (or api_version: in the registry) explicitly to
catch a major-version mismatch early.
One server process can currently load only one generated client major. All instances in a registry must therefore use the same API family; run separate MCP server processes for Airflow 2 and Airflow 3. Mixed-version support requires a future client-adapter change and is not advertised as working today.
Airflow 3 notes:
Auth: bearer tokens are passed through as JWTs; basic credentials are automatically exchanged for a JWT via POST /auth/token and refreshed periodically (AIRFLOW_MCP_TOKEN_REFRESH_SECONDS, default 3600 — keep it below your deployment's JWT expiry, and note there is no automatic re-auth on 401 yet).
execution_date ordering maps to logical_date, datasets map to assets, and UI links use the Airflow 3 route scheme. Tool names and the core workflow stay stable; documented fields and options can differ by API family.
Clear options that no longer exist in Airflow 3 (include_subdags/include_parentdag, and the include_*/reset_dag_runs options of airflow_clear_dag_run) are rejected with INVALID_INPUT rather than silently narrowing a destructive operation.
Both client families are exercised on relevant pull requests and main pushes. Bug reports from real Airflow deployments are very welcome!
Variable | Required | Description |
| ✅ | Airflow base URL, e.g. |
| ✅* | Basic auth credentials |
| ✅* | Bearer/JWT token (used instead of basic auth) |
|
| |
| Verify TLS certificates (default |
* provide either username+password or a token.
Point AIRFLOW_MCP_INSTANCES_FILE at a YAML registry (it takes precedence over the single-instance env vars). Values may reference environment variables with ${VAR}:
data-stg:
host: https://airflow.data-stg.example.com/
api_version: v1 # Airflow 2
verify_ssl: true
auth:
type: basic
username: ${AIRFLOW_DATA_STG_USERNAME}
password: ${AIRFLOW_DATA_STG_PASSWORD}
data-prod:
host: https://airflow.data-prod.example.com/
api_version: v1 # Keep one client/API family per server process
auth:
type: bearer
token: ${AIRFLOW_DATA_PROD_TOKEN}Every tool accepts either an instance key (data-stg) or a ui_url — a full http(s) Airflow UI URL whose host is resolved against the registry, with unknown hosts rejected (SSRF guard). ui_url also auto-fills dag_id/dag_run_id/task_id when the link contains them. If both instance and ui_url are passed and disagree, the call fails with INSTANCE_MISMATCH rather than guessing.
Kubernetes tip: mount the registry from a Secret at /config/instances.yaml and set AIRFLOW_MCP_INSTANCES_FILE=/config/instances.yaml.
Variable | Default | Description |
| Default instance key (also names the env-var instance) | |
|
| Don't register write tools at all |
|
| HTTP transport bind |
|
| Airflow API timeout |
|
| Airflow 3: JWT refresh interval for basic-auth instances |
| Optional log file path | |
|
| Enable |
|
| Return 405 for |
The quickstarts set AIRFLOW_MCP_READ_ONLY=true: write tools (trigger, clear,
pause/unpause) are never registered. This prevents MCP mutations, but read tools
can still disclose sensitive logs, configuration, rendered fields, and DAG-run
data; use least-privilege Airflow credentials.
To enable recovery operations deliberately, set AIRFLOW_MCP_READ_ONLY=false.
Write tools then carry MCP destructiveHint annotations that clients can use
when deciding whether to request confirmation. Annotations are advisory, so do
not enable writes unless the Airflow credentials and MCP client's approval
behavior are appropriate for the target environment.
Discovery & URL utilities
Tool | Description |
| List configured instance keys and the default |
| Host, API version, auth type (secrets redacted) |
| Parse an Airflow UI URL into instance + dag/run/task identifiers |
Read
Tool | Description |
| DAGs with pause state and UI links |
| DAG details |
| Runs with state filters and ordering (latest first by default) |
| Single run details |
| Task attempts for a run; filter by |
| Task metadata, retries, timings, optional rendered template fields |
| Logs with level filtering, tailing, context lines, and byte caps |
| Dataset (Airflow 2) / asset (Airflow 3) events |
Write (annotated destructive so clients can require approval; hidden entirely in read-only mode)
Tool | Description |
| Trigger a run with optional conf/logical date/note |
| Clear task instances across runs ( |
| Clear a whole run ( |
| Toggle DAG scheduling |
Every success payload includes a request_id for log correlation; failures raise a structured ToolError with {code, message, request_id, context}.
This is the flow the tools were designed around — going from an alert link to a diagnosis in four calls:
# 1. Alert contains an Airflow UI link → resolve it
airflow_resolve_url("https://airflow.example.com/dags/etl_pipeline/grid?dag_run_id=...")
# → {instance, dag_id, dag_run_id, ...}
# 2. Which tasks failed in this run?
airflow_list_task_instances(dag_id="etl_pipeline", dag_run_id="scheduled__2026-01-01",
state=["failed"])
# 3. Get attempt metadata (authoritative try_number, retries, timings)
ti = airflow_get_task_instance(dag_id="etl_pipeline",
dag_run_id="scheduled__2026-01-01",
task_id="transform_data")
# 4. Pull only the error lines, with context, capped for the LLM
airflow_get_task_instance_logs(dag_id="etl_pipeline",
dag_run_id="scheduled__2026-01-01",
task_id="transform_data",
try_number=ti["attempts"]["try_number"],
tail_lines=500, filter_level="error", context_lines=5)Log responses include truncated, auto_tailed (logs >100MB tail automatically), match_count, and byte/line stats so the agent knows exactly what it's looking at. Host-segmented logs are flattened with --- [worker-1] --- headers; Airflow 3 structured logs are rendered as plain lines.
Note on
try_number: reschedule-mode sensors could increment it on every reschedule through Airflow 2.9; Airflow 2.10+ no longer does. Always read it fromairflow_get_task_instancerather than guessing—the derivedretries_consumed/retries_remainingfields are heuristics.
docker run -p 127.0.0.1:8765:8765 \
-e AIRFLOW_MCP_HOST=https://airflow.example.com \
-e AIRFLOW_MCP_USERNAME=admin \
-e AIRFLOW_MCP_PASSWORD=your-password \
-e AIRFLOW_MCP_READ_ONLY=true \
ghcr.io/madamak/apache-airflow-mcp-server:latestOr build locally with docker build -t airflow-mcp .
The release image contains the lockfile's Airflow 3.3 client and serves
streamable HTTP on :8765 (/mcp endpoint, /health for probes). The MCP HTTP
endpoint has no built-in caller authentication: keep it loopback-bound or place
it behind an authenticated private proxy. Mount a same-API-family registry YAML
for multi-instance setups. Airflow 2 deployments should use the pinned local
installation path above until a separate v1 image is published.
CI audits the exact image's installed Python dependencies and scans both the read-only and write-enabled MCP tool surfaces with a pinned Cisco MCP Scanner release's YARA analyzer. The security workflow fails on incomplete scans or any untriaged YARA finding. Starting with v1.0.1, release assets include the machine-readable scan reports, and release image manifests carry attached SBOM and provenance attestations covering their broader package inventory. These are automated checks, not a security certification or substitute for deployment-specific review.
A fastmcp.json is included so FastMCP-aware tooling can auto-discover the entrypoint and deployment defaults.
uv sync # install dependencies
uv run pytest # unit tests (no real network; the Airflow client is mocked)
uv run ruff check . # lint
uv run ruff format . # format
uv run airflow-mcp --transport stdio # run locally
./scripts/e2e.sh af2 # end-to-end against Airflow 2.11
./scripts/e2e.sh af3 # end-to-end against Airflow 3.3
# Both seed failures/noisy logs and drive every tool
# through MCP. Set E2E_KEEP=1 to keep the instance up.CI runs the unit suite against both apache-airflow-client families on Python 3.10–3.13. Relevant pull requests, main pushes, nightly runs, and releases also exercise live dockerized Airflow 2.11 and 3.3. See CONTRIBUTING.md for guidelines and AGENTS.md if you're pointing a coding agent at this repo (it's written for that).
Issues and PRs are welcome — especially:
Reports from real Airflow incident-response workflows and version combinations
Bounded-log, diagnosis-safety, and URL-first workflow improvements
Client setup recipes for more MCP hosts and deployment types
If this server saves you a debugging session, a ⭐ helps other Airflow teams find it.
Apache 2.0 — see LICENSE.
Apache Airflow and Airflow are registered trademarks of The Apache Software Foundation. This independent project is not affiliated with or endorsed by the ASF.
Destructively clear all task instances within one specific DAG run.
Parameters
instance: Instance key (optional; mutually exclusive with ui_url)
ui_url: Airflow UI URL to resolve instance (optional; takes precedence)
dag_id: DAG identifier (required if ui_url not provided)
dag_run_id: DAG run identifier (required if ui_url not provided)
include_subdags: Include subDAGs (optional)
include_parentdag: Include parent DAG (optional)
include_upstream: Include upstream tasks (optional)
include_downstream: Include downstream tasks (optional)
dry_run: Preview without mutating (default true); set false explicitly to clear
reset_dag_runs: Reset DagRun state (optional)
Returns
Response dict: { "dag_id": str, "dag_run_id": str, "cleared": object, "request_id": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| dag_id | No | ||
| ui_url | No | ||
| dry_run | No | ||
| instance | No | ||
| dag_run_id | No | ||
| reset_dag_runs | No | ||
| include_subdags | No | ||
| include_upstream | No | ||
| include_parentdag | No | ||
| include_downstream | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true. The description adds the destructive nature, dry_run safety mechanism (default true, set false to clear), return format, and error handling (ToolError with JSON payload). This provides behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and well-structured with bullet points for parameters and returns. While necessary given the number of parameters, it is somewhat lengthy but without 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's complexity (10 parameters, no schema descriptions, but output schema exists), the description covers purpose, parameter usage, return values, and error handling comprehensively. It is fully sufficient for an agent to select and invoke 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?
With 0% schema description coverage, the description compensates fully by listing all 10 parameters with brief explanations, including mutual exclusions and defaults. This adds essential meaning beyond 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 clearly states the action ('clear all task instances') and the resource ('within one specific DAG run'). It distinguishes from siblings like 'airflow_clear_task_instances' by scoping to a single DAG 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?
The description implies use for clearing a single DAG run but does not explicitly contrast with siblings or provide when-not-to-use guidance. It does specify mutual exclusivity of parameters and dry_run behavior, aiding correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear task instances for a DAG across one or more runs using Airflow's native filter set (destructive).
Parameters
instance: Instance key (optional; mutually exclusive with ui_url)
ui_url: Airflow UI URL to resolve instance (optional; takes precedence)
dag_id: DAG identifier (required if ui_url not provided)
task_ids: List of task IDs to clear (optional)
start_date: ISO8601 start date filter (optional)
end_date: ISO8601 end date filter (optional)
include_subdags: Include subDAGs (optional)
include_parentdag: Include parent DAG (optional)
include_upstream: Include upstream tasks (optional)
include_downstream: Include downstream tasks (optional)
include_future: Include future runs (optional)
include_past: Include past runs (optional)
dry_run: Preview without mutating (default true); set false explicitly to clear
reset_dag_runs: Reset DagRun state (optional)
Returns
Response dict: { "dag_id": str, "cleared": object, "request_id": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| dag_id | No | ||
| ui_url | No | ||
| dry_run | No | ||
| end_date | No | ||
| instance | No | ||
| task_ids | No | ||
| start_date | No | ||
| include_past | No | ||
| include_future | No | ||
| reset_dag_runs | No | ||
| include_subdags | No | ||
| include_upstream | No | ||
| include_parentdag | No | ||
| include_downstream | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark destructiveHint=true, and the description reinforces this with a clear 'destructive' label. It explains the dry_run parameter (default true, must be set false to mutate) and the return/error formats. However, it does not mention authorization requirements or side effects beyond the dry_run flag.
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 well-structured: a one-sentence intro, followed by parameter and return bullets. Every sentence adds value, with no redundant or vague statements.
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 14 parameters, no required ones, and an output schema, the description covers parameters and return value thoroughly. It lacks context on prerequisites (e.g., permissions) or edge cases, but for a complex tool it is largely 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?
With 0% schema description coverage, the description fully compensates by providing a detailed bullet list for all 14 parameters, including optionality, mutual exclusivity (instance vs ui_url), and the effect of dry_run. This adds significant meaning beyond 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 clearly states the action ('Clear task instances') and the resource ('for a DAG across one or more runs'), with the note 'destructive' distinguishing it from read-only tools. Sibling tools like airflow_clear_dag_run are implicitly differentiated by the focus on task instances rather than entire runs.
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 lists many parameters and the dry_run behavior but does not provide explicit guidance on when to use this tool versus alternatives like airflow_clear_dag_run or airflow_get_task_instance. The 'destructive' label and filter semantics imply use cases, but direct comparisons are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List dataset events.
Parameters
instance: Instance key (optional)
ui_url: Airflow UI URL to resolve instance (optional)
dataset_uri: Dataset URI (required)
limit: Max results (default 50; accepts int/float/str, coerced to non-negative int, fractional values truncated)
Returns
Response dict: { "events": [object], "count": int, "request_id": str }
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| ui_url | No | ||
| instance | No | ||
| dataset_uri | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds parameter coercion details (limit truncation) and return format, but does not disclose additional behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is mostly concise with a clear heading and structured parameter and return sections. However, the parameter list is slightly verbose and could be more compact.
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 and the presence of output schema in description, the description covers basic usage. However, the contradiction about required/optional dataset_uri and lack of error or pagination details reduce 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 description explains each parameter, including limit's type coercion, but contradicts the schema by stating dataset_uri is required when schema marks it optional with default null. Schema coverage is 0%, so description had burden but the contradiction reduces clarity.
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 'List dataset events,' specifying the verb 'list' and the resource 'dataset events.' It distinguishes this tool from siblings which focus on DAGs, task instances, and instances.
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 contextual prerequisites or exclusion criteria, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe a configured Airflow instance (host + metadata, never secrets).
Parameters
instance: Instance key (e.g., "data-stg")
Returns
Response dict: { "instance", "host", "api_version", "verify_ssl", "auth_type", "request_id": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| instance | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent, so the description adds value by stating 'never secrets' and detailing the return structure. It does not contradict annotations and provides additional behavioral context (no secrets exposed, error format).
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 concise (three short sections: purpose, parameter, returns). Every sentence adds value, and the structure is clear and front-loaded.
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 tool with one parameter and explicit return and error specifications, the description is complete. The output schema is effectively described in text, and no additional context is needed.
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 only parameter 'instance' has no description in the schema (0% coverage). The description adds meaning by calling it an 'instance key' and providing an example ('data-stg'), which clarifies what the string represents.
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 tool 'describe a configured Airflow instance (host + metadata, never secrets)'. The verb 'describe' and resource 'Airflow instance' are specific, and the distinction from sibling tools (which deal with DAGs, runs, tasks) is clear.
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 when not to use it, prerequisites, or how it differs from other describe/list tools (e.g., airflow_get_dag, airflow_list_instances).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get DAG details and a UI link.
Parameters
instance | ui_url: Provide one; ui_url auto-resolves/validates the host.
dag_id: Required when only instance is supplied.
Returns
Response dict: { "dag": object, "ui_url": str, "request_id": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| dag_id | No | ||
| ui_url | No | ||
| instance | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. Description adds valuable details: auto-resolution of ui_url, return structure (dag, ui_url, request_id), and error format (compact JSON payload). No contradictions.
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?
Highly concise with clear sections: purpose, parameter instructions, returns, and errors. Every sentence adds value; no fluff.
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?
Covers key aspects: purpose, parameter behavior, return format, errors. Output schema exists so detailed object description is unnecessary. Could mention authentication/network requirements but those are implicit for Airflow tools.
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 compensates fully: explains conditional requirement (dag_id needed only with instance) and auto-resolution behavior of ui_url. Adds clarity beyond 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?
Clearly states 'Get DAG details and a UI link,' specifying the verb and resource. Distinguishes from sibling tools like airflow_list_dags (list vs get) and airflow_get_dag_run (different resource).
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?
Provides parameter guidance (provide one of instance/ui_url, dag_id required with instance) but lacks explicit when-to-use vs alternatives like airflow_list_dags or airflow_get_dag_run. Usage context is implied but not fully articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single DAG run and a UI link.
Parameters
instance: Instance key (optional)
ui_url: Airflow UI URL to resolve instance/dag/dag_run (optional)
dag_id: DAG identifier
dag_run_id: DAG run identifier
Returns
Response dict: { "dag_run": object, "ui_url": str, "request_id": str }
| Name | Required | Description | Default |
|---|---|---|---|
| dag_id | No | ||
| ui_url | No | ||
| instance | No | ||
| dag_run_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true, so the description is not required to disclose safety. The description adds that the tool returns a dictionary with 'dag_run', 'ui_url', and 'request_id', which is useful but not extensive behavioral context. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and uses a clear list for parameters. Every sentence adds value without redundancy. Well-structured for quick parsing.
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 an output schema and annotations, the description covers the basic purpose, parameters, and return structure. However, it lacks clarification on required parameter combinations (all optional but not all combinations valid) and does not anchor usage relative to many sibling tools. Adequate but not fully 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?
The input schema has 0% description coverage, so the description must compensate. It lists parameters with basic descriptions (e.g., 'DAG identifier', 'Instance key (optional)'), adding minimal meaning beyond the names. However, it does not explain how parameters interact or which combinations are required, leaving gaps.
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 'Get a single DAG run and a UI link', specifying the verb (Get), resource (single DAG run), and an additional unique feature (UI link). It distinguishes from sibling tools like airflow_list_dag_runs and airflow_get_dag by focusing on a single run and including the link.
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 explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, required parameter combinations, or exclusions. The usage context is only implied by the tool's purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return task metadata, config, attempt summary, optional rendered fields, and UI URLs.
Parameters
instance | ui_url: Target selection (URL precedence)
dag_id, dag_run_id, task_id: Required identifiers (unless resolved from ui_url)
include_rendered: When true, include rendered template fields (truncated using max_rendered_bytes)
max_rendered_bytes: Byte cap for rendered fields payload (default 100KB; accepts int/float/str, coerced to positive int, fractional values truncated)
Returns
Response dict: { "task_instance": {...}, "task_config": {...}, "attempts": {...}, "ui_url": {...}, "request_id": str, "rendered_fields"?: {...} }
Notes
attempts.try_number is the authoritative input for airflow_get_task_instance_logs.
Rendered fields include bytes_returned and truncated metadata.
Sensors increment try_number on every reschedule, so treat it as an attempt index; the derived retries counters are heuristic.
| Name | Required | Description | Default |
|---|---|---|---|
| dag_id | No | ||
| ui_url | No | ||
| task_id | No | ||
| instance | No | ||
| dag_run_id | No | ||
| include_rendered | No | ||
| max_rendered_bytes | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate safe read, and description adds details on optional rendering, truncation, and sensor try_number behavior. No contradictions.
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?
Well-structured with summary, parameter list, return dict, and notes. Concise yet informative, though slightly lengthy.
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?
Covers parameter behavior and return structure adequately; output schema exists for full details. Leaves minor gaps (e.g., error cases), but overall 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?
With schema coverage at 0%, description explains all 7 parameters, including target selection, required identifiers, and max_rendered_bytes coercion. Provides full context.
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 'Return task metadata, config, attempt summary, optional rendered fields, and UI URLs.' It identifies the specific resource (task instance) and distinguishes from sibling list/other 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?
Provides parameter guidance (URL precedence, required identifiers) and mentions the sibling tool for logs, but lacks explicit when-to-use vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch task instance logs with optional filtering and truncation.
Large log handling: Logs >100MB automatically tail to last 10,000 lines (sets auto_tailed=true).
Host-segmented responses are flattened into a single string using headers of the form --- [worker] ---,
ensuring agents can reason about multi-host output.
The tool requires an explicit try_number; callers should first retrieve it via airflow_get_task_instance.
Filter order of operations:
Auto-tail: If log >100MB, take last 10,000 lines
tail_lines: Extract last N lines from log
filter_level: Find matching lines by level (content filter)
context_lines: Add surrounding lines around matches (symmetric: N before + N after)
max_bytes: Hard cap on total output (UTF-8 safe truncation)
Parameters
instance: Instance key (optional, mutually exclusive with ui_url)
ui_url: Airflow UI URL to resolve identifiers (optional)
dag_id, dag_run_id, task_id, try_number: Task instance identifiers (required)
filter_level: "error" | "warning" | "info" (optional) - Show only lines matching level
"error": ERROR, CRITICAL, FATAL, Exception, Traceback
"warning": WARN, WARNING + error patterns
"info": INFO + warning + error patterns
context_lines: N lines before/after each match (optional, clamped to [0, 1000]; accepts int/float/str, coerced to non-negative int, fractional values truncated)
tail_lines: Extract last N lines before filtering (optional, clamped to [0, 100000]; accepts int/float/str, coerced to non-negative int, fractional values truncated)
max_bytes: Maximum response size in bytes (default: 100KB ≈ 25K tokens, clamped to 1MB)
Returns
Response dict with fields:
log: Normalized/filtered log text (host headers inserted when needed)
truncated: true if output exceeded max_bytes
auto_tailed: true if original log >100MB triggered auto-tail
bytes_returned: Actual byte size of returned log
original_lines: Line count before any filtering
returned_lines: Line count after all filtering/truncation
match_count: Number of lines matching filter_level (before context expansion)
meta.try_number: Attempt number for this task instance
meta.filters: Echo of effective filters applied (shows clamped values)
ui_url: Direct link to log view in Airflow UI
request_id: Correlates with server logs
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| dag_id | No | ||
| ui_url | No | ||
| task_id | No | ||
| instance | No | ||
| max_bytes | No | ||
| dag_run_id | No | ||
| tail_lines | No | ||
| try_number | No | ||
| filter_level | No | ||
| context_lines | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: large logs auto-tail, host-segmented responses are flattened, filtering order, parameter clamping, and return fields. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with clear sections (log handling, filter order, parameters, returns). It front-loads the core purpose. Every sentence adds value given the tool's complexity; minor reduction could improve 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 an output schema, the description comprehensively explains all return fields (log, truncated, auto_tailed, bytes_returned, etc.) and error handling. Given the tool's complexity (10 parameters, filtering logic), it is fully 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. It thoroughly explains each parameter: mutual exclusivity of instance and ui_url, defaults, type coercion, clamping, filter_level patterns, and context_lines behavior. This adds critical meaning beyond 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 begins with 'Fetch task instance logs with optional filtering and truncation,' providing a specific verb (fetch) and resource (task instance logs). It clearly distinguishes from sibling tools like airflow_get_task_instance, which presumably returns instance metadata, not logs.
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 states that the tool requires an explicit try_number and advises callers to first retrieve it via airflow_get_task_instance. It also details the filter order of operations, guiding when each parameter applies. However, it does not explicitly exclude scenarios where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List DAG runs (defaults to execution_date DESC) with per-run UI URLs.
Parameters
instance: Instance key (optional)
ui_url: Airflow UI URL to resolve instance/dag_id (optional)
dag_id: DAG identifier (required if ui_url not provided)
limit: Max results (default 100; accepts int/float/str, coerced to non-negative int, fractional values truncated)
offset: Offset for pagination (default 0; accepts int/float/str, coerced to non-negative int, fractional values truncated)
state: List of states to filter by (optional)
order_by: Optional "start_date", "end_date", "execution_date", or "logical_date" (omit to use execution_date; execution_date and logical_date are mapped to whichever name the target Airflow version uses)
descending: Sort direction (default True). Ignored when order_by is omitted; defaults always use execution_date descending
Returns
Response dict: { "dag_runs": [{ "dag_run_id", "state", "start_date", "end_date", "ui_url" }], "count": int, "request_id": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| state | No | ||
| dag_id | No | ||
| offset | No | ||
| ui_url | No | ||
| instance | No | ||
| order_by | No | ||
| descending | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, non-destructive. Description adds significant behavioral details: default sorting, parameter coercion, dependency logic for instance/ui_url/dag_id, and error format. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headings and bullet points. Slightly verbose but no redundant information. Each sentence adds value. Appropriate length for 8 parameters.
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?
Covers all parameters, default behavior, return format, and error handling. Given the presence of output schema in description and annotations, it is sufficiently complete. Could mention pagination or rate limits but not critical.
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 fully compensates. Every parameter is explained with defaults, coercion, optionality, and dependencies (e.g., dag_id required if ui_url not provided). Adds meaning beyond schema (e.g., fractional truncation, order_by mapping).
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 it lists DAG runs with default ordering and includes UI URLs. It specifies the verb 'list' and resource 'DAG runs', and distinguishes from sibling tools like 'airflow_get_dag_run' (single run) and 'airflow_list_dags' (list DAGs).
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 (e.g., get_dag_run, list_dags). It does not state conditions or prerequisites, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List DAGs (pause state + UI link) for the target instance.
Parameters
instance: Instance key (optional; mutually exclusive with ui_url)
ui_url: Airflow UI URL to resolve instance (optional; takes precedence - must match a configured host)
limit: Max results (default 100; accepts int/float/str, coerced to non-negative int, fractional values truncated)
offset: Offset for pagination (default 0; accepts int/float/str, coerced to non-negative int, fractional values truncated)
Returns
Response dict: { "dags": [{ "dag_id", "is_paused", "ui_url" }], "count": int, "request_id": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| ui_url | No | ||
| instance | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral details: pagination via limit/offset, parameter coercion, mutual exclusivity of instance and ui_url, error payload structure, and return schema. This goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for parameters and returns. It is informative but slightly verbose; each sentence adds value. Could be marginally more 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 the output schema existence and rich annotations, the description covers return format and error handling. However, it does not explicitly clarify when to use this tool versus the many sibling tools (e.g., airflow_get_dag), leaving a minor gap in contextual 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?
Schema description coverage is 0%, so the description fully compensates by explaining each parameter (defaults, accepted types, coercion rules, mutual exclusivity). This provides clear semantics that the schema alone does not convey.
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 DAGs with pause state and UI link for a target instance. It distinguishes the basic listing function from sibling tools like airflow_get_dag (retrieves a single DAG) and airflow_list_dag_runs, but does not explicitly differentiate its 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?
The description lacks guidance on when to use this tool versus alternatives. It does not specify that this is for obtaining an overview of all DAGs or compare to other listing tools. No explicit when-not-to-use 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.
List configured Airflow instance keys.
Returns
Response dict: { "instances": [str], "default_instance": str | null, "request_id": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| 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?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral details: the return type (dict with keys 'instances', 'default_instance', 'request_id') and error format (ToolError with JSON payload).
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 two sentences, no wasted words, and clearly front-loaded with the core 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?
For a parameterless list tool with rich annotations and an output schema, the description is complete. It specifies the response structure and error behavior, covering all needed 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?
There are no parameters, so schema coverage is 100%. The description does not need to add parameter information. It correctly omits irrelevant details.
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 configured Airflow instance keys, using a specific verb and resource. It distinguishes itself from sibling tools that list other entities like DAGs or runs.
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 discovering available instances, but lacks explicit when-to-use or when-not-to-use guidance compared to siblings. 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.
List task instances within one DAG run, including state and attempt log URLs.
Parameters
instance: Instance key (optional)
ui_url: Airflow UI URL to resolve instance/dag/dag_run (optional)
dag_id: DAG identifier
dag_run_id: DAG run identifier
limit: Max results (default 100; accepts int/float/str, coerced to non-negative int, fractional values truncated)
offset: Offset for pagination (default 0; accepts int/float/str, coerced to non-negative int, fractional values truncated)
state: Optional list of task states (case-insensitive). When provided, only matching states are returned.
task_ids: Optional list of task identifiers to include.
Returns
Response dict: { "task_instances": [{ "task_id", "state", "try_number", "ui_url" }], "count": int, "total_entries"?: int, "filters"?: { "state": [...], "task_ids": [...] }, "request_id": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| state | No | ||
| dag_id | No | ||
| offset | No | ||
| ui_url | No | ||
| instance | No | ||
| task_ids | No | ||
| dag_run_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, making safety clear. The description goes beyond by detailing the return structure (task_instances array with fields, count, filters) and error handling (ToolError with compact JSON). This adds valuable behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a one-sentence summary, bullet-pointed parameter list, and a clear Returns section with an example JSON. Every part adds value, and the information is front-loaded.
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 8 optional parameters and many siblings, the description covers the purpose, all parameters, return format, and error handling. The output schema further complements the return docs. No gaps remain for a list operation of this complexity.
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, the description compensates well by explaining each of the 8 parameters, including type coercions for limit/offset and case-insensitivity for state. However, it does not explicitly indicate which parameters are typically required (e.g., dag_id and dag_run_id) for meaningful results, leaving some 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 verb 'List' and the resource 'task instances within one DAG run', with a specific scope that distinguishes it from siblings like 'airflow_get_task_instance' (single instance) and 'airflow_list_instances' (potentially across DAGs). The mention of 'state and attempt log URLs' adds 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?
The description implies usage for a specific DAG run by stating 'within one DAG run', but does not explicitly compare with alternatives or state when not to use it. No when-not or explicit alternative mentions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pause DAG scheduling (sets is_paused=True and returns UI link).
Parameters
instance: Instance key (optional; mutually exclusive with ui_url)
ui_url: Airflow UI URL to resolve instance (optional; takes precedence)
dag_id: DAG identifier (required if ui_url not provided)
Returns
Response dict: { "dag_id": str, "is_paused": true, "ui_url": str, "request_id": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| dag_id | No | ||
| ui_url | No | ||
| instance | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description discloses that the tool sets is_paused=True, returns a specific response dict, and mentions error format (ToolError). It adds context about the side effect and return value.
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 concise: a single sentence for purpose followed by a clear bullet list of parameters and return values. Every sentence is necessary and well-structured, front-loading the action.
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 an output schema and sibling tools, the description covers purpose, parameters, error behavior, and return format. It could mention effects on running tasks, but the description is largely complete for agent decision-making.
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, the description compensates by documenting each parameter: instance (optional, exclusive with ui_url), ui_url (optional, takes precedence), dag_id (required if ui_url not provided). This adds meaning beyond the schema alone.
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 'Pause DAG scheduling (sets `is_paused=True` and returns UI link).' It specifies the verb (pause) and resource (DAG scheduling), differentiating it from sibling tools like airflow_unpause_dag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each parameter (instance, ui_url, dag_id) and their mutual exclusivity. However, it does not explicitly state when to use this tool versus alternatives like unpause_dag, though the name conveys the basic use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse an Airflow UI URL, resolve instance and identifiers.
Parameters
url: Airflow UI URL (http/https)
Returns
Response dict: { "instance", "dag_id"?, "dag_run_id"?, "task_id"?, "try_number"?, "route", "request_id" }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and idempotentHint. The description adds useful behavioral context: return format (dictionary with fields) and error handling (ToolError with compact JSON payload), which goes beyond what annotations convey.
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 relatively concise but mixes sections (Parameters, Returns, Raises) without clear formatting. It could be more structured, but no 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?
Given low complexity (1 param, output schema exists, annotations cover safety), the description adequately covers input, output, and error behavior. No missing essential 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?
Only one parameter 'url' with schema coverage 0%. Description adds 'Airflow UI URL (http/https)', providing some meaning beyond the schema. Baseline adjusted due to low coverage, but description is minimal.
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 'Parse an Airflow UI URL, resolve instance and identifiers', using a specific verb and resource. It distinguishes from sibling tools like airflow_clear_dag_run or airflow_get_dag which perform different 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 on when to use this tool versus alternatives. The description does not mention any context, prerequisites, or exclusions that would help an agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a DAG run with optional configuration.
Parameters
instance: Instance key (optional; mutually exclusive with ui_url)
ui_url: Airflow UI URL to resolve instance (optional; takes precedence)
dag_id: DAG identifier (required if ui_url not provided)
dag_run_id: Custom run id (optional)
logical_date: Optional ISO8601 logical date/time assigned to the new run
conf: Configuration object as dict or JSON string (optional)
note: Run note/comment (optional)
Returns
Response dict: { "dag_run_id": str, "ui_url": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| conf | No | ||
| note | No | ||
| dag_id | No | ||
| ui_url | No | ||
| instance | No | ||
| dag_run_id | No | ||
| logical_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds the return format and error handling details. However, it does not disclose potential side effects (e.g., creating a run even if another is active) or authorization needs beyond what annotations imply.
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 well-structured with a lead sentence, a parameter list, and return/error details. It is slightly lengthy but each section adds value. Front-loading the main action is effective.
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, mutual exclusivity, output schema exists), the description covers the essential information: how to specify the DAG and instance, what configuration and notes can be provided, and the expected returns and errors. No major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain parameters. It provides clear descriptions for all 7 parameters, including mutual exclusivity between 'instance' and 'ui_url', the meaning of 'conf' as a dict or JSON string, and the optional nature of most fields. This adds significant value over the schema alone.
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 ('Trigger a DAG run') and the resource ('DAG run with optional configuration'). Among sibling tools like 'airflow_get_dag_run', 'airflow_list_dags', etc., this uniquely describes a mutation that initiates a run, making the purpose distinct.
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 starting a new DAG run, but does not explicitly state when to use this tool versus alternatives like 'airflow_get_dag_run' (for retrieving an existing run) or other lifecycle tools. No exclusion criteria 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.
Resume DAG scheduling (sets is_paused=False and returns UI link).
Parameters
instance: Instance key (optional; mutually exclusive with ui_url)
ui_url: Airflow UI URL to resolve instance (optional; takes precedence)
dag_id: DAG identifier (required if ui_url not provided)
Returns
Response dict: { "dag_id": str, "is_paused": false, "ui_url": str, "request_id": str }
Raises: ToolError with compact JSON payload (code, message, request_id, optional context)
| Name | Required | Description | Default |
|---|---|---|---|
| dag_id | No | ||
| ui_url | No | ||
| instance | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true (mutation). The description adds that it sets is_paused=False and returns a response dict, clarifying the state change. It also discloses error format (ToolError with JSON payload). This is good context beyond annotations, though it doesn't mention potential side effects like triggering downstream tasks.
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 highly concise, with a one-line summary followed by a bulleted parameter list and return value info. Every sentence adds value without redundancy. Structure is clear and easy to scan.
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 output schema, the description adequately covers return values, error handling, and parameter relationships. It lacks details on permissions or when to prefer alternative tools, but for a three-parameter tool with annotations, it is largely 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 fully compensates. It explains each parameter: instance (optional, mutually exclusive with ui_url), ui_url (optional, takes precedence), dag_id (required if ui_url not provided). This adds critical constraints and meaning beyond the schema's bare types 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 it resumes DAG scheduling by setting is_paused=False, which distinguishes it from siblings like airflow_pause_dag (pauses) and airflow_trigger_dag (triggers a run). The verb 'resume' combined with the specific resource 'DAG scheduling' provides a precise action.
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 does not provide explicit guidance on when to use this tool versus alternatives. It lacks statements about prerequisites, when not to use, or comparisons to related tools like airflow_pause_dag or airflow_trigger_dag. The parameter documentation partially implies resolution logic but no strategic usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose, targeting specific Airflow entities (DAGs, runs, tasks, instances, datasets) and actions (list, get, clear, trigger, pause/unpause, describe, resolve). No two tools perform the same operation on the same entity, and descriptions make boundaries clear.
All tools follow a consistent 'airflow_verb_noun' pattern (e.g., airflow_list_dags, airflow_trigger_dag). No mixing of conventions or unusual naming styles, making it easy for agents to predict tool names.
With 16 tools, the count is slightly above the high end of 'well-scoped' (3-15), but it is reasonable given the complexity of Apache Airflow. The tools cover a comprehensive set of operations without feeling bloated or redundant.
The tool surface covers all core Airflow interactions: listing, getting, clearing, triggering, pausing/unpausing DAGs, runs, and task instances, plus logs, dataset events, and instance management. Minor gaps exist (e.g., no DAG update or deletion), but those are less common operations and the set still enables effective agent workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connect, monitor, and control AI agents — tasks, approvals, schedules, and governance.
Enterprise AI Control Plane: governance, guardrails, spend tracking, compliance & smart routing.
Manage Supabase projects end to end across database, auth, storage, realtime, and migrations. Moni…
Manage Jitsu data pipelines: destinations, streams, connections, functions, live events.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/madamak/apache-airflow-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
