list_available_endpoints

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

Without annotations, the description carries the burden of behavioral disclosure. It explains that the tool returns a list with descriptions and status, indicates the active endpoint, and notes that the endpoint is session-specific in multi-user deployments. However, it does not explicitly state read-only behavior, auth requirements, or any side effects, though these are reasonably implied for a listing operation.

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 well-structured and concise: it states the purpose in the first line, adds relevant usage guidance in the middle, and ends with a clear summary of returns. Every sentence provides useful information, and the overall length is appropriate for the tool's simplicity.

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?

The tool is simple (no params), and the description covers purpose, usage, return structure, and session-specific behavior. An output schema exists, but the description's return summary suffices given the simplicity. Sibling tool comparisons are addressed via the alternative usage advice, making the description complete for an agent to select and invoke 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?

The tool has zero parameters, and the input schema is an empty object, so schema coverage is trivially 100%. With 0 params, the baseline is 4. The description adds no parameter details because none exist, but it does describe the return payload conceptually, which is not required for this dimension.

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 clearly states the tool's function: 'List all available SDMX data sources that can be switched to.' It specifies the resource (SDMX data sources) and the action (list), and further clarifies that it shows all configured statistical data providers and indicates the currently active one. This distinguishes it from sibling tools like get_current_endpoint, which likely returns only the current endpoint.

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 explicitly provides usage context: it explains when this tool is useful (to see available endpoints/current active) and provides an explicit alternative for a different task: 'Use compare_dataflow_dimensions(...) to directly compare dataflows from different providers.' It also notes session-specific behavior in multi-user deployments, which guides when to rely on the result.

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