Recent files

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

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses a bounded filesystem walk, hard skip list (node_modules/target/.git), a 2s TTL cache, and scan caps of 4000 files / 300 directories. That is exactly the operational context an agent needs to interpret partial results; the 'Batch-safe: no' tag is terse but informative. It loses a point only for not clarifying what 'truncated' means in practice or how depth affects the scan bound.

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?

Front-loaded purpose sentence followed by short labeled lines (Use when / Avoid when / Speed / Output / Batch-safe). Every line carries distinct, actionable information with no filler.

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?

Even without an output schema, the description gives the return shape (recent_files entries sorted by mtime desc, scanned_files, truncated). Combined with the disclosure of skip rules, caching, and scan caps, an agent has enough to call it correctly and interpret the result. Only the undocumented optional parameters are a mild gap.

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 only 25% (only relative_path is documented), so the description should compensate more than it does. The skip list and bound hint at include_ignored and depth behavior, but limit's default/max and depth's cost impact are never explained. Partial compensation justifies a middle score rather than a high one.

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 ('List files modified most recently in the workspace') plus the scope of the scan and what it skips. It explicitly names the two sibling tools it is not (project_list_files for full listing, project_search for content search), so an agent can distinguish it without opening a 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?

Provides explicit 'Use when' (need to know which files just changed, pick next file to read) and 'Avoid when' (full list/by name -> project_list_files, content search -> project_search) clauses. Alternatives and selection conditions are named directly, 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.