cos_graph_stale_files

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: why staleness is silently unflagged versus truncation, and that the tool fails with `unavailable` rather than returning an empty list that would be misread as 'nothing stale'. That failure-mode disclosure is exactly the kind of context annotations cannot carry.

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-loads the core definition, then explains the staleness/truncation asymmetry and pipes into Args/Returns sections. The middle paragraph is dense but each sentence adds meaning; the framing is slightly prose-heavy rather than scannable but not wasteful.

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 an output-schema-backed, single-param read tool, the description covers what an agent needs: purpose, when to call it, the parameter bounds, and the failure envelope. Nothing material is missing given the schema and annotations already present.

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, and it does: it documents `top` as max paths returned with default 100 and a max of 5000, the latter of which appears nowhere in the schema.

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 indexed files') with a precise predicate ('with a git commit newer than the index pass that read them'). The title reinforces this and the semantics clearly distinguish it from sibling graph tools like cos_graph_overview or cos_graph_doctor.

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?

Gives a clear operational condition: 'Ask this before acting on a confidently complete answer,' which tells the agent when staleness checking matters. It lacks explicit when-not guidance or named alternatives among the many cos_graph_* siblings, 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.