get_navigation_data

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds substantial context on top: the server-authoritative nature of the navmesh, the misleading 'Navigation System not found' answer from a client, honest error behavior when no navigation system exists, and the provenance fields stamped into the reply. That is genuine behavioral disclosure beyond structured fields.

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?

Purpose and the key diagnostic rule are front-loaded, and the trailing Returns block is justified because this tool has no output schema. It is dense rather than wasteful, though the WARNING and Returns sections make it longer than strictly necessary for a single-parameter read.

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?

With no output schema present, the description compensates by spelling out the full return shape field by field, plus error behavior and world-selection semantics. An agent has everything needed to call it and interpret the result correctly.

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 schema already documents 'world' and its accepted values, making some of the description redundant. However, the description adds diagnostic rationale the schema lacks — that only the server world owns a navmesh, and that a client query yields a spurious 'not found' — which materially changes how an agent should set this parameter.

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?

It states a specific verb+resource ('Inventory of navigation in a chosen world') and enumerates exactly what is returned: every ANavigationData actor with class, every NavMeshBoundsVolume with location, and the whole-world-navigable flag. This is unambiguous and distinct from write-side siblings like rebuild_navigation or diagnose_navmesh.

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 a clear triggering condition ('The first thing to read when AI will not path') plus an interpretation rule (no bounds volume / empty brush means zero navmesh tiles), and directs the agent to anchor world='server'. It does not, however, name a sibling such as diagnose_navmesh or get_recast_navmesh_settings as the next step when this tool is inconclusive, so alternatives are left implicit.

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