find_file_edits

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

With no annotations provided, the description carries the full burden and does so impressively. It discloses redaction behavior, reference-by-default semantics, size-bounded output with truncation markers, the default 7-day time window, and the error contract translation—far exceeding minimal disclosure expectations and providing rich behavioral context.

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 long but every sentence earns its place, organized by labeled behavioral aspects (redact, reference, truncation, default window, wrapper). It is front-loaded with the core purpose and uses bolded inline terms to make scanning easy.

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 complexity and the presence of an output schema, the description covers all major behavioral areas: redaction, reference-by-default, truncation, default time window, and error mapping. It leaves no significant gap for an agent to misuse the tool, and the output schema handles return-value details.

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 compensate, and it explains redact, include_input, since/until, agent, and the distinction between output_truncated and count-based truncation. However, the 'limit' parameter is not explicitly tied to record-count behavior; while 'count-based truncated' hints at it, the direct semantic of limit remains implicit rather than stated.

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 opening sentence, 'Find every file edit across sessions, cross-agent by default,' uses a specific verb ('Find') and resource ('file edit across sessions'), and the phrase 'cross-agent by default' immediately distinguishes it from sibling tools like find_tool_calls or session_diff. It is immediately clear what the tool does and how it is scoped.

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 explains when to fetch bodies on demand via get_body/read_session and when to pass include_input=True, giving practical alternatives. However, it does not explicitly state when not to use find_file_edits versus other sibling tools, relying more on implicit context than direct exclusions.

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