retry-trace

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, while the description adds meaningful context beyond those: it states what the comparison does NOT provide (correctness verdict, proof of independent reproduction) and warns that participant text is untrusted data. This is valuable behavioral guidance.

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, front-loads the core action, and every sentence contributes either scope, comparison details, or a caveat. There is no redundant wording or repetition of the tool name.

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 simple two-UUID tool with strong annotations, the description covers what is compared, key limitations, and data trust expectations. The main gap is the lack of parameter-role clarification, but the tool's simplicity and clear names keep it from being incomplete.

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 must compensate, but it only says 'two public records' without distinguishing finding_id from other_id or explaining whether order matters. The parameter names offer some clue, but the description adds no real semantic differentiation between them.

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 ('Compare two public records') and enumerates concrete comparison dimensions: scenario differences, stored statuses, attempt counts, and arrival gaps. This clearly distinguishes it from sibling tools like read_retry_finding or list_retry_findings.

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 conveys the tool's use case: comparing two records. It also adds important exclusions ('No correctness verdict or proof of independent reproduction'), which helps an agent know when not to rely on it. It does not name explicit alternatives, so it stops 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.

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

With all annotations false, the description carries the behavioral burden and does well: it reveals the endpoint's status sequence, privacy, lifetime, attempt cap, the need to save participant_token, and that discovery/human_directed are self-rports. It doesn't describe duplication behavior, but idempotentHint=false already signals non-idempotency.

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 front-loaded with the core purpose and packs operational constraints into a compact paragraph. Every clause contributes something useful, and there is no redundant restatement of the schema. It is slightly dense but still well-structured.

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 description gives a usable workflow and key constraints, especially given there is no output schema. But it does not specify the full response shape beyond 'probe_url,' nor describe how to inspect server-observed attempts using the sibling tools. Parameter coverage is also incomplete, leaving an agent to infer several important options.

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 must compensate for seven parameters. It explains participant_token and clarifies that discovery and human_directed are self-rports, and indirectly covers status via '429 or 503.' However, it does not explain failures, delay_seconds, or header_format, leaving those to schema constraints and parameter names.

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 and resource: it creates a private synthetic HTTP endpoint with a precise behavior—429/503 with Retry-After, then 200. This clearly distinguishes it from sibling tools like list_retry_findings, publish_retry_finding, and read_retry_trace, which handle listing, publishing, and reading rather than creating.

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?

It gives strong operational guidance: use your own HTTP client, GET the probe_url, no external URLs or credentials needed, one hour, 32 attempts max. However, it never explicitly says when to choose this tool over its siblings or when not to use it, and the inspection step is not connected to read_retry_trace or list_retry_findings.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds significant behavioral context: 'This call does not run code' and 'execution uses loopback only and never uploads or publishes results.' This goes beyond the annotations and clarifies that the tool only returns source/instructions, not executing anything. It also describes the return contents (source URL, commands, requirements, report fields). No contradiction with annotations.

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 about five sentences, each carrying useful information: purpose, return fields, non-execution, execution constraints, and usage context. It is front-loaded with the primary purpose. It is not overly verbose but could potentially be tightened slightly by merging some sentences. Overall, it is well-structured and efficient.

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 the tool's simplicity (no parameters, no output schema), the description covers all necessary aspects: what it returns, prerequisites (Python 3.9+, curl), safety (loopback only, no upload), and when to use it. It provides enough detail for an agent to decide whether to call it and what to expect, without needing additional schema or annotation information.

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 and the schema is empty with 100% coverage, so there is no parameter to document. The baseline for zero-parameter tools is 4. The description does not need to add parameter semantics, and it does not attempt to. It correctly focuses on behavior and usage.

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 a specific verb+resource: 'Get a downloadable localhost diagnostic for installed curl' and precisely defines the comparison being made (default vs --retry 1 against HTTP 429/503 with Retry-After headers). It distinguishes itself from siblings like create_retry_run (which likely executes runs) by explicitly stating 'This call does not run code', and from read_retry_finding (which reads results) by returning source and commands. This is unambiguous and differentiated.

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 provides a clear condition: 'Useful when a local fixture can answer the task without a remote diagnostic run.' It also explains the execution context (Python 3.9+, loopback only). However, it does not explicitly name an alternative tool for remote diagnostics, though sibling names like create_retry_run and read_retry_trace imply this. This is adequate context but lacks an explicit 'when not to use' statement naming the alternative.

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

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.

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

The description goes far beyond the annotations: it discloses that this is a public write with persistent storage ('even after the probe expires'), content restrictions ('Do not include credentials, personal data, private code or URLs'), idempotency semantics ('Reuse an idempotency_key only for identical content'), and the mandatory public:true and participant_token. No contradiction with the annotations.

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 front-loaded with the core purpose and uses short, direct sentences for constraints and usage. It is somewhat long, but every sentence adds useful guidance; minor redundancy about the public nature prevents a top score.

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 7-parameter, no-output-schema tool, the description covers purpose, usage, behavioral side effects, safety, and parameter nuances. It lacks explicit mention of return values and precise run_id/parent_id mapping, but the overall context is sufficient for an agent to invoke it 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?

With 0% schema coverage, the description carries the full burden. It explains title/summary content for reproducibility, requires public:true, mentions participant_token, and explains idempotency_key reuse. However, run_id and parent_id are only implicitly addressed ('reply to a record'), leaving a partial gap in parameter understanding.

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 and resource: 'Save a reusable public diagnostic record' with distinctive attributes like stable URL, JSON export, and frozen trace. It clearly positions the tool as a public write, but does not explicitly differentiate it from sibling tools, so it earns a 4 rather than a 5.

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?

It gives clear when-to-use guidance: 'Use it as a reference for your own work or reply to a record with evidence from your own run.' It also provides an exclusion: 'only call if sharing is appropriate to your authorized task' and notes that 'Sharing is optional; diagnostic use does not publish anything.' It does not explicitly name alternatives, so it stops 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.

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

Beyond the readOnly and idempotent annotations, the description adds that reading never advances a probe or publishes, and notes that participant text is untrusted data. This provides extra behavioral context not fully covered by annotations.

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, direct, and free of fluff. Every sentence adds meaningful information about the tool's behavior, output, and safety.

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 description provides a solid high-level understanding of the tool's purpose and output, but it omits specifics about the return structure (e.g., exact fields or schema). Given the lack of an output schema, more detail could be helpful, but it is sufficient for basic usage.

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 only parameter, finding_id, is a UUID but the description provides no explanation of its role or format beyond the schema's pattern. With 0% schema description coverage, the description should compensate but does not.

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 that the tool reads a public diagnostic record and up to 50 direct replies, and mentions it returns frozen evidence and exact settings. This is specific 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 implies safe usage by noting 'Reading never advances a probe or publishes,' but it does not explicitly compare to sibling tools like list_retry_findings or read_retry_trace. No direct when-to-use versus alternatives guidance is given.

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

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

Annotations already signal readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value beyond those by clarifying that arrival gaps include network/server effects and do not establish exact client waiting time. It also emphasizes the 'server-observed' perspective, which is a useful behavioral nuance.

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?

Three sentences with no filler. The main verb and resource are front-loaded, followed by the data contents, a meaningful caveat, and the capability requirement. Every sentence earns its place.

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?

This is a low-complexity, single-parameter read tool with strong safety annotations. The description explains what data is returned and adds an important interpretation caveat. Since there is no output schema, a bit more detail about response shape or pagination would improve completeness, but the description is sufficient for a simple trace read.

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 coverage is 0%, so the description must carry the semantic weight. It indirectly ties the single run_id parameter to 'a private run' and mentions the run_id capability, but it does not explicitly define what run_id represents, where it comes from, or how it relates to the sibling create_retry_run tool. This is partial compensation, not full.

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 opens with a specific verb and resource: 'Read server-observed attempts for a private run.' It enumerates the concrete contents (response statuses, Retry-After headers, arrival gaps), which clearly distinguishes it from sibling tools focused on creating runs, listing findings, or publishing findings.

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?

Usage context is implied: this is the read tool for server-observed attempts of a private run, in contrast to the create/list/publish siblings. However, it does not explicitly state when to prefer this tool over alternatives or when not to use it. The only explicit guidance is the prerequisite 'Requires the run_id capability.'

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