get_unhealthy_agents

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

The description reveals that the tool retrieves data ('取得する') and returns fields: success, unhealthy_agents, count. It also notes authorization requirements. However, there is a contradiction with the input schema: the parameter caller_agent_id is marked as required in the description but is optional (anyOf string/null, default null) in the schema. This inconsistency undermines reliability. No annotations are provided, so the description carries full burden but fails to clarify side effects, pagination, or the meaning of 'unhealthy'.

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 concise, consisting of four lines: a one-line purpose, an authorization note, and structured Args/Returns sections. It is well-organized and front-loaded with the main action. No unnecessary words are present, though some detail is sacrificed for brevity.

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 has one parameter and an output schema (not detailed in description). The description covers the main purpose, authorization, and return fields. However, it lacks specifics about the output structure (beyond field names), what constitutes 'unhealthy', and whether the list is paginated. The contradiction regarding the parameter's requiredness also creates a completeness gap. Overall, it is adequate for a simple tool but has clear areas for improvement.

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?

Schema description coverage is 0%, requiring the description to explain the parameter. It states 'caller_agent_id: 呼び出し元エージェントID（必須）', which adds meaning by specifying the parameter's purpose and claiming it is required. However, this contradicts the schema which defines it as optional with a default null. The added meaning is partially offset by this contradiction.

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: 'Get list of unhealthy agents' (異常なエージェント一覧を取得する). It uses a specific verb and resource, and additionally specifies that only Owner and Admin can use it, which helps distinguish it from related tools like healthcheck_agent or healthcheck_all.

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 includes an important usage restriction ('※ Owner と Admin のみ使用可能'), indicating who can invoke the tool. However, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., healthcheck_agent vs. get_unhealthy_agents). The usage is implied but lacks comprehensive context.

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