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

With no annotations, the description carries the full disclosure burden and does real work: it states the data source (Stripe, GitHub, App Store), the 7-day freshness window, the 10-listing visibility threshold, and the exact failure shape (visible false and no entries). It does not say whether the call is read-only, whether Stripe revenue is authorized on the caller's behalf, or how results are paginated.

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?

Two sentences, no filler. The ranking criteria and board types come first, then the edge-case behavior, which is the right front-loading order for a caller deciding whether to invoke it.

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?

There is no output schema, so the description should ideally sketch the return shape. It covers the most important edge case (invisible board returns visible false with no entries) but never says what a populated entry looks like, so an agent knows when the call fails yet not what success yields. For a single-parameter read tool this is close but not complete.

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%, so the enum and its one-line description are already documented. The description still adds meaning the enum cannot: it maps each opaque value (revenue, stars, rated) to the actual data source that ranks it, which is the difference between guessing and knowing which board to request.

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 nails the resource and its defining property: boards of listings ranked by data Toolfound fetched itself, split into revenue band, GitHub stars, or App Store rating. It is far more specific than the name alone. It never explicitly contrasts itself with the adjacent toolfound_get_trending sibling, so an agent has to infer the verified-vs-trending split.

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?

Usage is implied rather than stated: you call it when you want a board ranked by self-fetched data. There is no when-not guidance and no naming of the sibling (toolfound_get_trending) that an agent should pick instead when it wants unverified or trending data. The 7-day freshness window is a usage constraint but is framed as data provenance, not as a selection rule.

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