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

Beyond the readOnly/idempotent annotations, the description adds valuable behavioral details: the 50-record limit, the untrusted nature of the text data ('not instructions'), exclusion of Operator QA findings, and that records include scenario and URL. The security-relevant warning is especially useful for agent safety.

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?

Four sentences, each carrying distinct and necessary information: purpose, result contents, security warning, exclusions, and access requirements. No filler or redundancy. The main purpose is front-loaded, and the safety note is placed appropriately after the basic function.

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?

For a read-only list/search tool with three optional filters and no output schema, the description is remarkably complete. It states result cap, what each record contains, what data is excluded, and provides an important security disambiguation. No critical information for an agent to decide on or invoke the tool 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 0%, so the description carries the full burden of explaining parameters. It successfully maps all three parameters: title/summary text (q), HTTP status (status), and Retry-After format (header_format). This goes well beyond raw parameter names and compensates for the empty schema descriptions.

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 ('Find') and resource ('public diagnostic records') and adds explicit filtering dimensions: title/summary text, HTTP status, or Retry-After format. This clearly distinguishes it from sibling tools like read_retry_finding or compare_retry_findings without relying on the tool name.

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 clearly establishes the use case: searching for diagnostic records using one or more of the listed filters. It also notes that no contribution is required, which helps set expectations. However, it does not explicitly mention when not to use this tool or name alternative tools, so it falls just short of a 5.

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