build_system_graph

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

With no annotations, the description carries the full burden and does supply real behavioral detail: it makes an external EDSM query, and it discloses an edge case that nodes with missing coordinates become isolated nodes with explicit missing flags. It says nothing about query cost, rate limits, failure modes, or whether a live network call is required for large radii.

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?

Four short sentences, front-loaded with the core operation and broken into lines that make each fact scannable. There is no filler, though the space spent on the missing-coordinate edge case arguably belongs after the more essential explanation of how the sphere's center is chosen.

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 7 optional parameters, zero schema descriptions, no annotations, and an output schema that already covers the return value. Given that, the description should resolve how the center point is specified and what graph_definition accepts, yet it leaves both ambiguous while spending words restating the return shape.

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 description coverage is 0% across 7 parameters, so the description must compensate, and it only clarifies radius_ly and max_edge_distance. The center specification (x/y/z versus system_name) is never addressed, and graph_definition — an enum-like string that changes the graph's semantics — is entirely unexplained.

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 opening sentence gives a specific verb and resource ('Build a jump-range proximity graph'), and the follow-up spells out the two-step process: query EDSM within radius_ly, then connect pairs within max_edge_distance. It implicitly separates itself from edsm_sphere_systems (raw system retrieval) but never names a sibling, so it stops short of full differentiation.

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?

Usage is only implied: the mention of a 'graph snapshot' suggests this is the precursor to analyze_graph_metrics or graph_sensitivity_analysis, but the description never says when to pick this over edsm_sphere_systems or query_bounded_region. No exclusions or prerequisites are stated.

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