get_recent_changes

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

With no annotations, the description fully discloses behavioral traits: it compares against a cached mirror by default, can optionally read live files, reports the drift_layer, and confirms it is handle-only with no content reads. This provides comprehensive transparency.

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 concise with five short sentences, each adding unique value. It is front-loaded with the core purpose and version requirement, with no redundant information.

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 adequately covers the tool's role as a pre-flight check and explains behavior. However, without an output schema, it could provide more detail on the return structure beyond drift_layer. Still, it is sufficient for the tool's complexity.

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 100%, setting baseline at 3. The description adds meaningful context beyond the schema, such as explaining the default behavior of using the cached mirror and the fallback mechanism when live_source fails.

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 the tool lists sections that have 'drifted from index state' into specific buckets (edited_uncommitted or stale_index). It distinguishes itself from sibling tools (e.g., get_sections) by focusing on drift detection and serving as a pre-flight check before re-indexing.

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 explicitly frames the tool as a 'Pre-flight check before deciding whether to re-index,' providing clear usage context. It does not explicitly name alternatives, but the pre-flight purpose is well defined.

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