roamzy_status

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

While annotations already indicate read-only and non-destructive behavior, the description adds critical operational context: the presence of a 'purchases_paused' flag and the required backup behavior. This goes beyond the annotations and tells the agent how the API status affects downstream actions.

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 two sentences long, front-loaded with the main purpose, and the second sentence provides a mandatory usage rule. Every word earns its place; there is no fluff or repetition of schema/annotation data.

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 that this is a simple status-check tool with no parameters, an output schema (not shown but mentioned), and annotations covering safety, the description provides all necessary context: what it checks, a critical usage requirement, and the exact flag behavior. It is fully complete for an agent to 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, so the schema provides full coverage by default. The description adds no parameter-specific information because none exists. Baseling score of 4 is appropriate; no deduction is needed since there is nothing to clarify.

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 starts with a specific verb and resource: 'Check Roamzy API status.' It further clarifies the scope by mentioning 'agent pause flags,' which distinguishes this tool from sibling tools like roamzy_list_countries or roamzy_create_order. The purpose is clear and 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 description explicitly states when the tool must be used: 'Agents MUST call this before purchase attempts.' It also provides a conditional action: 'back off if purchases_paused=true.' This gives clear context for when to invoke this tool and what to do with its result, which is more than typical usage guidance.

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