Report a failed tool call to the network

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

With no annotations provided, the description carries the full behavioral disclosure burden and succeeds. It reveals that the network is shared/public, that only failure metadata should be sent, that error messages are normalized server-side (with raw text discarded), that reporter_id is salted/hashed, that writes are rate limited, and the privacy redaction heuristics. All of this goes well beyond a bare name and would materially change how an agent uses the tool.

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 verbose but every block earns its place: primary action, when-to-call, privacy restrictions, normalization details, reporter_id guidance, and rate limiting. The most important call/decide information (purpose and when to use) is front-loaded, while deep privacy details appear later. Slightly longer than minimal, but justified by the sensitive nature of the tool.

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?

Complete for a 9-parameter tool with no annotations and a nontrivial privacy model. The description covers when to call, what data may/must not be sent, server-side normalization guarantees, reporter identity semantics, and rate limiting. With an output schema present, return-value documentation is not required. No critical gap remains.

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% and parameters already have clear descriptions, so the baseline is 3. The description adds value beyond the schema by explaining why reporter_id matters (counts as one independent reporter instead of anonymous noise) and how the error_message normalization process works (numbers, UUIDs, emails, URLs, IPs, tokens replaced; credential-shaped substrings redacted) — details absent from the property definitions.

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 uses a specific verb and resource ('anonymously contribute a tool/API/MCP failure to FailEcho') and states the purpose of helping other autonomous systems recognize failures. It clearly distinguishes itself from siblings like report_tool_success and report_recovery_outcome by focusing on failures.

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?

Explicitly says 'Call this whenever a tool call fails' and specifies the order relative to the sibling tool check_tool_failure ('after or alongside'). This leaves no ambiguity about when the tool should be invoked.

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