run_pipeline

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

Despite no annotations, description details the 6 stages and parameter behaviors (e.g., skip_refresh, source fallback). Discloses pipeline flow and data source selection. Lacks mention of potential side effects like API calls or caching, but overall sufficiently transparent for a complex tool.

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 fairly long but well-structured with bullet points for stages and clear sections for args/returns. All content is relevant and adds value. Slightly verbose for a simple tool, but appropriate for the complexity of a 10-parameter pipeline.

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 10 parameters, 0% schema coverage, no annotations, but with an output schema (return mentioned), the description covers all parameters, pipeline stages, and return format. Provides sufficient context for an agent to understand input, behavior, and output.

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 provides extensive parameter explanations with examples (portfolio_json format, candidates style, overrides_json structure, env var for source). Adds significant meaning beyond bare schema types and defaults, fully compensating for lack of schema 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?

Description clearly states 'Run the full 6-stage rotation analysis pipeline' with specific stages enumerated. Distinguishes from sibling tools (individual stages like analyze_risk, compare_swaps) by positioning itself as the main entry point for a complete analysis.

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?

States 'This is the main entry point for a complete rotation analysis,' implying use when full pipeline is needed. Does not explicitly mention when to use alternatives (individual stages) or exclusions, but context from sibling names makes this clear.

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