Ops MCP Server

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it's a read operation ('Get'), returns detailed DAG information ('source code / definition', 'details including file location, schedule, tags, and task list'), and has a critical constraint about the 'env' parameter requiring explicit user input. However, it doesn't mention potential errors (e.g., if DAG doesn't exist), rate limits, or authentication needs, leaving some gaps.

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

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

The description is appropriately sized and front-loaded. The first sentence states the core purpose, followed by usage guidelines and parameter details in a structured 'Args:' section. Every sentence earns its place: the purpose, use cases, parameter explanations, and return value summary are all essential without redundancy. The formatting with bullet-like sections enhances readability.

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 moderate complexity (2 parameters, no annotations, but with an output schema), the description is complete enough. It covers purpose, usage, parameters, and return values. Since an output schema exists, the description doesn't need to detail return values extensively, and it appropriately summarizes them ('Returns the DAG details including file location, schedule, tags, and task list'). This provides sufficient context for an agent to use the tool 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 schema description coverage is 0%, so the description must compensate fully. It does so by clearly explaining both parameters: 'dag_id: The DAG identifier' and 'env: Target environment — 'dev', 'uat', 'test', or 'prod'. IMPORTANT: Do NOT guess or default. Ask the user which environment if not specified.' This adds crucial meaning beyond the bare schema, including enum-like values for 'env' and a strict usage rule, making the parameters well-understood.

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

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

The description clearly states the tool's purpose: 'Get the source code / definition of a DAG' with specific verbs ('get', 'understand') and resources ('source code', 'definition', 'DAG'). It distinguishes from siblings like 'get_dag_run_details' or 'list_dags' by focusing on the DAG's source/definition rather than runs, status, or lists. The phrase 'Use this to understand what a DAG does' reinforces its unique role.

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 explicit guidance on when to use this tool: 'Use this to understand what a DAG does — its tasks, operators, dependencies, schedule, and configuration. Useful for debugging or understanding a pipeline's structure.' It also includes a critical exclusion: 'IMPORTANT: Do NOT guess or default. Ask the user which environment if not specified.' This clearly defines the tool's context and constraints, helping the agent choose it over alternatives like 'list_dags' for structural insight.

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