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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description only needs to add beyond that. It does: it discloses sort order (newest first) and, notably, the date semantics — HackList's own posted date when exposed, otherwise sitemap last-modified time — which materially affects result interpretation.

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?

Three tight sentences with the core behavior front-loaded and the fallback date logic appended where it belongs. No filler and nothing redundant.

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?

No output schema exists, yet the description never indicates what a listing record contains. Combined with the undocumented open_only default and limit cap, an agent can call the tool but cannot predict the shape or filtering of results.

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 carry the load. It only accounts for the 'days' parameter ('last N days'); 'limit' and especially 'open_only' (default true, a meaningful filter that silently excludes closed listings) are never mentioned in either schema or description.

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: 'Listings posted or updated on HackList in the last N days, newest first.' The recency framing implicitly separates it from deadline-driven siblings like closing_soon and quality-driven ones like best_opportunities, but no sibling is named explicitly.

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 phrase "Useful for 'what got added this week'" gives an implied use case, but there is no when-not guidance and no routing to alternatives such as search_opportunities or closing_soon when recency is not the criterion.

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