Check Source Health

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context beyond annotations: the probe layer reads eval/probe-latest.json, the published-install caveat ('status stays unknown until this process itself calls it'), and the data merge behavior. This meaningfully informs the agent about edge cases and internal mechanics.

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 three sentences: core function with output states, behavioral caveat, and usage/parameter guidance. It is front-loaded, every sentence earns its place, and there is no redundant filler.

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 a rich output schema, clear annotations, and a description that covers purpose, behavior, edge cases, usage triggers, and parameter guidance. For a read-only health-reporting tool with all-optional parameters, nothing an agent needs to invoke it correctly is missing.

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 100%, so baseline is 3. The description adds value by explaining that response_format: 'detailed' exposes 'error rate, latency, and quota usage'—quotas are not mentioned in the schema—and by framing source/cluster as optional filters. This is a modest but genuine addition beyond the schema.

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 states a specific verb ('Report') and resource ('per-source health'), enumerates the exact output states ('ok', 'degraded', 'down', 'key_missing', 'unknown'), and describes the data fusion mechanism. This clearly distinguishes it from siblings like library_list_sources (listing) or library_search (retrieval).

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 gives explicit when-to-use guidance: 'Use before relying on a source that has been erroring, or to check whether a key is configured.' It does not explicitly name exclusions or alternative tools, but the context is clear and actionable for an agent.

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