sacloud-mcp

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it retrieves data (implying a read-only operation) and mentions the API source, but doesn't disclose other traits like authentication requirements, rate limits, error handling, or whether it's idempotent. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior beyond the basic purpose.

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 appropriately sized and front-loaded: the first sentence states the purpose clearly, and the subsequent section details the return structure. While the return details are somewhat lengthy, they are relevant for understanding the output since there's no output schema. There's minimal waste, though it could be slightly more concise in the Returns section.

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 has 0 parameters (simple), no annotations, and no output schema, the description does an adequate job by stating the purpose and detailing the return values. However, it lacks information on behavioral aspects like authentication or error handling, which would be important for completeness in a real-world API context. The return structure is helpful but doesn't fully compensate for the missing annotations.

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 input schema has 0 parameters with 100% coverage, so the schema fully documents that no inputs are required. The description doesn't need to add parameter details, and it correctly doesn't mention any parameters. This meets the baseline for tools with no parameters, as the schema already provides complete information.

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 purpose: 'さくらのクラウドAPIからアイコン一覧を取得します（全ゾーン共通）' which translates to 'Retrieves icon list from Sakura Cloud API (common to all zones).' It specifies the verb ('取得します' - retrieves) and resource ('アイコン一覧' - icon list), and distinguishes it from siblings by mentioning it's for icons specifically. However, it doesn't explicitly differentiate from 'get_icon_tag_list' which might be a related sibling tool.

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 no guidance on when to use this tool versus alternatives. It mentions '全ゾーン共通' (common to all zones), which could imply a scope, but doesn't specify prerequisites, exclusions, or compare it to other icon-related tools like 'get_icon_tag_list'. There's no explicit when-to-use or when-not-to-use information.

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