Get API summary

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

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Return' implies a safe read-only operation NR, and the zero-parameter schema makes side effects unlikelyasi. Still, the description does not explicitly state that this is non-mutating, that it requires no authentication, or that it reflects current API capacity rather than live service health. For a simple no-argument introspection tool, this is adequate but not richly transparent.

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 sentence that states the action and the object of that action without any filler. It is front-loaded with the verb 'Return' and immediately specifies the tool's output. Every word contributes to understanding, making this an efficient and well-structured description.

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 simplicity (zero parameters, no output schema, no annotations), the description is mostly complete: an agent knows what the tool does and that it requires no inputs. The main gap is that the description does not hint at the structure or format of the returned endpoint map, which could matter if the agent needs to navigate the result. Still, for tool selection and invocation, the essential information is present.

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?

The tool has zero parameters, so the baseline is 4, and the description does not need to explain any parameter behavior. There is nothing in the input schema to elaborate on, and the description's mention of returning endpoint capabilities aligns with what a no-argument summary tool would produce. The description does not need to compensate for any parameter documentation gap because none exists.

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 uses a specific verb ('Return') and identifies a concrete resource ('MCP-facing transport12 API capabilities and endpoint map'), so an agent can tell this tool provides API metadata rather than transit data. It is distinguishable from siblings like health and get_service_status because those suggest operational status, not a discovery/endpoint map. However, 'capabilities' is somewhat broad and could be more explicit about what kind of capabilities are included.

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?

There is no guidance about when to use this tool versus alternatives, nor any mention of prerequisites or context. The description only states what the tool returns, leaving the agent to infer that it should be used when API capabilities or endpoint mapping are needed. Given the large sibling set, an explicit statement like 'Use this before calling other transport tools to discover endpoints' would have made the usage context much clearer.

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