list_endpoints

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

With no annotations, the description does the heavy lifting by disclosing the returned fields, including read_safe — a per-endpoint safety signal that tells the agent which raw calls are safe reads. It doesn't explicitly state the tool itself has no side effects or discuss call cost, but the catalog nature and read_safe field convey the important behavioral context.

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?

Two short sentences: the first declares the catalog and its fields, the second covers the optional filter. The purpose and the key field list are front-loaded with zero filler.

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?

For a one-optional-parameter discovery tool with an output schema, this is close to complete — the returned fields are enumerated and the filter behavior is explained. Missing is the explicit workflow instruction to consult results before issuing raw_request, which would fully close the loop.

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 0% and the single 'contains' parameter has no description, so the description must carry the burden — and it does: it explains the filter matches substrings against form paths OR purposes and gives two concrete examples. Only case-sensitivity and whether matching is on the full form_path string are left unstated.

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 names the resource (API endpoint catalog) and explicitly ties it to the sibling tool raw_request, which distinguishes it from the other router tools. The framing is a noun phrase rather than a verb, but the function — discover endpoints usable with raw_request — is unambiguous.

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 tie to raw_request implies this is a discovery step before making raw calls, and the filter examples ('dhcp', 'wireless') show how to narrow the list. However, it never states when to reach for this versus calling raw_request or a dedicated sibling like dhcp_leases directly, nor any prerequisite ordering.

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