generate_flow_paths

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

Annotations include destructiveHint=true, and the description honestly notes that generation takes time but cached paths return instantly, adding value beyond annotations. It does not explicitly warn about cost, but the openWorldHint and destructiveHint are present in annotations; the description adds performance and caching context, which is useful. Minor gap: it doesn't state what happens if model_group_id is invalid or whether generation consumes credits, but with annotations present the bar is lower.

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 compact: first sentence states purpose, second lists outputs, third gives prerequisite, fourth covers caching and performance, fifth gives defaults with context. Every sentence adds new information and the description is highly scannable, making it ideal for agent consumption.

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?

The tool has an output schema, so return values are documented separately. The description covers prerequisites, performance, caching, defaults, and parameter semantics, making it complete for a complex generation tool. Slight deduction for not explicitly warning about credit/resource consumption, but given the output schema and annotations, the description is nearly 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the default horizon (60 ≈ 1 quarter) and n_paths (1000), and clarifies price_history_length's purpose ('warm up indicators like MACD or z-score before forward_test_rules'), which the schema's description only hints at. It also ties model_group_id to explicit source tools, enriching the parameter meaning.

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 starts with a specific verb ('Generate') and resource ('simulated multi-step price trajectories from a trained Flow model'), clearly stating what the tool produces: per-asset percentile bands, sample paths, and scalar terminal statistics. It distinguishes itself from siblings like simulate_flow_scenario and train_flow_model by naming the required model_group_id and referencing related 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?

The description explicitly states prerequisite: 'Requires model_group_id from train_flow_model or list_model_groups.' It also mentions caching behavior ('If paths already exist, returns cached results instantly') and gives performance context ('takes ~1-3 min on GPU'), which helps the agent decide when to call and what to expect. While it doesn't name alternatives for exclusion, the context is sufficiently explicit for correct tool selection.

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