list_modified_files

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

With no annotations, the description carries the full burden and does substantially: it declares read-only, no side effects, session-bound persistence, and that the source is the session journal rather than git status. It stops short of documenting authorization requirements or failure modes, so it is strong but not exhaustive.

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 sectioned layout (What it does / When to use / When NOT to use / Side effects / Returns) is well front-loaded and scannable. There is mild redundancy—'Read-only' appears both in the opening line and again under Side effects—but the text is otherwise tight and every section 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?

An output schema exists, so return values need not be spelled out, yet the description still notes a JSON list of relative file paths. Combined with the session-boundary and source-of-truth caveats, nothing an agent needs to call this 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?

The tool takes zero parameters, which per the rubric sets a baseline of 4. The description confirms 'Parameters: None,' accurately matching the empty schema, so there is no gap to compensate for.

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?

States a specific verb and resource with scope: 'Lists files modified by recent replace_pattern operations in the current session.' It also distinguishes itself from the related get_file_diff sibling by clarifying it returns journal state, not git status, so an agent can pick between them without opening either schema.

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 provides 'When to use' (view unapproved changes before approving/rejecting) and 'When NOT to use' (does not persist across sessions; use get_file_diff for git-based modifications). This is the full when/when-not/alternative pattern, leaving nothing to inference.

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