atom-mcp-server

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

Annotations declare the operation is read-only, idempotent, and safe. The description adds valuable return value details ('vendor metadata (country, region, pricing page URL) plus every model and SKU') that compensate for the missing output schema, clarifying what data structure to expect without contradicting the safety annotations.

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 front-loaded with purpose, followed by return value disclosure, then practical examples. Every sentence serves a distinct function—scope definition, output specification, or usage illustration—with zero redundancy or filler text.

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 5 parameters including optional filters (modality, direction), pagination (limit), and authentication (_atom_api_key), plus the absence of an output schema, the description adequately covers the return structure and provides sufficient examples to infer usage patterns for the filtering capabilities.

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?

With 100% schema coverage, baseline is 3. The examples add semantic context beyond raw schema definitions by demonstrating how to translate user intents like 'OpenAI's text model pricing' into specific vendor/modality parameter values, effectively illustrating the relationship between the parameters.

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 a specific scope ('Full catalog for a specific vendor: all models, modalities, and pricing') that clearly distinguishes this from siblings like list_vendors (which lists vendors) and get_model_detail (which retrieves single model info). The verb 'Get' from the title combined with 'catalog' precisely identifies the resource operation.

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?

Three concrete examples map natural language queries to specific parameter combinations, providing clear context for how to invoke the tool. However, it lacks explicit guidance on when NOT to use this tool (e.g., 'use search_models instead for cross-vendor searches') which would earn a 5.

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