generate_network_from_bbox

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

With no annotations, the description carries full responsibility for behavioral disclosure, and it does so thoroughly. It details the entire pipeline: OSM fetch, skeleton derivation, dead-end pruning, road decimation, deterministic diameter mapping (with explicit values), reservoir placement, DEM sampling that never guesses, engine validation, and immediate post-processing availability. It also discloses network constraints (Overpass endpoint, timeout, response cap) and the never-guessed contracts for elevation and reservoir head.

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 a single dense paragraph, but every sentence carries meaningful information. It is front-loaded with the core purpose and then expands into operational details and constraints. While lengthy, it avoids redundancy and is well-organized with a logical flow from inputs to processing to outputs. It is not overly terse, but the complexity justifies the length.

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 8 parameters, nested objects, and no output schema, the description is remarkably complete. It specifies parameter defaults, behavior, external dependencies, and the resulting model lifecycle (networkId, immediate support for run_simulation, assign_demands, etc.). It also covers error-prone aspects like the requirement of exactly one input mode and the fail-closed elevation contract. An agent would be well-equipped to invoke this tool correctly without additional lookup.

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?

Although schema coverage is 100%, the description adds substantial semantic value beyond the schema. It explains the effect of each parameter in context: spacingM controls junction density, minDeadEndM prunes short branches, river guides reservoir placement to the nearest waterway, and reservoirHead is a design input that must be positive. For nested objects like osmExtract and osmFile, it clarifies their relationship to bbox and the offline workflow. This goes well beyond the raw schema definitions.

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 opens with a clear, specific verb and resource: 'Build a water network automatically from real streets — the one-call GIS layout.' It distinguishes itself from siblings like fetch_road_network and create_network by positioning as the consolidated layout tool and explicitly noting it is the Phase 4 native tool. The purpose is unmistakable.

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 explicitly instructs to provide exactly one of bbox / osmExtract / osmFile along with river and reservoirHead, and explains the trade-off between live Overpass calls and saved extracts. It also references the fail-closed contract shared with create_network, giving context on when this tool behaves similarly. It does not explicitly list exclusions versus siblings, but the guidance is strong enough for an agent to choose appropriately.

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