get_effective_config

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

With no annotations, the description carries the full burden and handles it excellently. It explicitly states 'Pure read - makes no changes and writes nothing', explains the meaning and restart implications of 'restart_required', describes how misconfigured roles surface via an inline 'error' key without raising, and documents the degraded behavior for missing plan manifests. This is far beyond typical behavioral disclosure.

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 longer than average, but nearly every sentence carries substantive behavioral or parameter semantics. The opening sentence front-loads the core purpose and read-only guarantee. Minor redundancy exists ('Read-only diagnostic snapshot' vs 'Pure read - makes no changes and writes nothing') and the self-referential 'same effect as get_effective_config's plan_name' could be tightened, but overall it is well-organized into scannable paragraphs.

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 and the presence of an output schema, the description covers everything needed to call it correctly: what it returns, how the single optional parameter behaves, error-handling behavior, and restart semantics. The output schema handles return-value structure, so no further description is needed there.

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 the description must explain plan_name, and it does so thoroughly: optional, layers role_config overrides, missing manifest degrades to no overrides. It also clarifies the semantic distinction between values that require a restart and those that are live immediately, which adds meaning far 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 names a specific resource ('pipeline's effective configuration') and a specific diagnostic purpose ('Read-only diagnostic snapshot'), then enumerates exactly what it reports: resolved role configs, env vars, provenance, and consulted files. This clearly differentiates it from the sibling tools, which are all mutation or status operations on stories/plans.

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?

It gives explicit context for the optional plan_name parameter: pass it to layer in role_config overrides, and a missing manifest degrades gracefully instead of raising. It does not explicitly name alternatives or when-not-to-use, but the tool is unique among siblings and its read-only diagnostic role is clear. The phrase 'same effect as get_effective_config's plan_name' is slightly self-referential and confusing, but does not undermine the guidance.

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