get_topology

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description deeply discloses behavior: summary returns only non-up links, full requires filters to avoid flooding, basenet performs one API call per leg with a 100-leg fan-out cap, and 'node_count' can legitimately be 0 alongside non-zero link counts. It also highlights ID semantics (path_id vs anynet_link_id). This is rich, non-obvious behavioral context that annotations alone cannot convey.

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 long but every sentence carries necessary information for correct invocation. It is structured into a short purpose statement followed by itemized parameter explanations. Repetition of 'requires site' is intentional reinforcement of a critical constraint. The length is justified by the tool's complexity (seven parameters, multiple modes, pagination, ID semantics).

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 the tool's complexity and the presence of an output schema, the description covers all essential usage contexts: mode differences, filter requirements, pagination tokens, leg_offset mechanics, and how to interpret unusual return values like node_count=0. It also explains that basenet exposes element/interface-level underlay info. No critical behavioral aspect appears omitted for effective invocation.

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 significantly enriches every parameter: it explains defaults, interdependencies (site required for full and basenet), edge cases (leg_offset resumption, node_count semantics), and pagination behavior. For instance, it clarifies that cursor is opaque and must be copied from next_cursor, and that limit has a server default of 50 with max 200. This far exceeds the schema's bare descriptors.

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 'Return AnyNet topology with careful ID semantics preserved', which is a specific verb+resource statement. It clearly distinguishes this from sibling tools like get_routing or get_wan by detailing topology-specific modes (summary/full) and views (anynet/basenet). The tool's purpose is unambiguous and well-scoped.

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 provides explicit guidance on when to use summary vs full mode, when basenet is appropriate, and states requirements (site required for full unless status is set, and for basenet). It also documents exclusions, such as refusing a tenant-wide full dump without filters. However, it does not explicitly compare this tool to sibling alternatives (e.g., when to prefer get_wan for underlay instead), so it stops short of a full 5.

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