neon3_capabilities

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

There are no annotations, so the description carries the full burden of behavioral disclosure. 'Query' implies read-only behavior, but the description does not explicitly state that no modifications occur, nor does it explain behavior when zero, one, or multiple endpoints are supplied.

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 well-front-loaded sentence with no filler, putting the verb and resource first. It is concise, but the brevity contributes to missing usage and parameter context.

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 annotations, no output schema, and three semantically undocumented optional parameters, the description is not complete enough for an agent to reliably select and invoke the tool. It only conveys the high-level operation and return value, not endpoint semantics or invocation strategy.

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%, and the description does not explain ui_endpoint, wgpu_endpoint, or projectd_endpoint. The endpoint names are mildly self-descriptive, but the description adds no meaning about how these parameters map to Neon3 services or how they should be selected.

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 names a specific operation ('Query service.describe') and the returned data ('current capabilities and epochs'), so the tool's purpose is clear. It does not explicitly differentiate itself from sibling tools like neon3_diagnose or neon3_nui_inspect, so it stops short of full sibling-focused clarity.

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 states what the tool does but gives no guidance on when to use it versus alternatives. It also does not explain whether the three optional endpoints are alternatives, mandatory in some combination, or optional for querying all services.

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