find_stale_placeholders

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does convey that this is a scanning/detection tool that searches for TODO functions with hardcoded return values, and names a detected pattern rather than just 'detecting something.' However, it does not disclose whether this could be a read-only analysis operation, whether it modifies code, the scope of scanning, or what parameters beyond directory it might depend on. No annotations make full disclosure impossible, but given the description does illuminate purpose behavior, a 3 is fair.

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 two paragraphs, with the first sentence stating the core purpose and the second paragraph illustrating with a concrete example. It is efficient and front-loaded. The example paragraph adds genuine value via a real detection scenario rather than fluff. No wasted sentences.

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 has only 1 parameter, no annotations, but has an output schema (which presumably documents results), the description covers the essential 'what does it find and why it matters' context well. It could add detail about the scope of search, common match patterns, or false positives, but for a single-parameter pattern-detection tool, the current description is reasonably complete. The concrete example fills in expected-use context that a bare schema cannot.

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% (the 'directory' parameter has no description), so the description must compensate. The description mentions 'reads its input file' and performs analysis in a directory context, but it never explicitly references the 'directory' parameter or explains its meaning beyond what the schema type implies (a string). The parameter is intuitive given 'directory' naming, but the description does not add semantic depth about what kind of directory this should be or constraints.

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 what the tool does: 'Find functions marked TODO that still return a hardcoded value.' This uses a specific verb with a resource type (functions), and goes on to illustrate with a concrete use case (reporting function seeded with a constant). It distinguishes itself from siblings like find_failing_jobs and check_endpoint by targeting TODO-flagged placeholders specifically.

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 gives a clear concrete scenario ('Catches the reporting function that reads its input file, ignores it, and returns the constant'), which implies when to use it. However, it does not explicitly state when NOT to use it or name alternative tools for related but different tasks (e.g., find_failing_jobs for actual failures). The 'when to use' is implied well, but exclusions/alternatives are absent.

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