findpeek: search recent public posts on Bluesky and Hacker News (not X/Twitter)

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, yet the description adds substantial behavior beyond them: partial-failure semantics ('one source down: the other answers, with a per-source status'), 503 on total failure, count 0 vs error charging rules, live query with nothing stored, 0.5-3 s latency, USD 0.005 price, and a 10-call free tier. Untrusted-content and prompt-injection warnings plus a docs link round it out.

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?

Lead sentence front-loads purpose and scope, and the operational facts (failure modes, billing, latency) are packed efficiently. It loses a point for redundancy ('not X/Twitter' stated twice, untrusted-data warning repeated) and for the stray 'on-chain strings' phrase that is irrelevant to a social-post search.

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?

Output schema exists, so return-value shape need not be described. Given a 4-parameter tool with a single required param, the description covers the remaining gaps an agent needs: source coverage, partial/total failure handling, cost and free tier, latency, and safety caveats.

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 100%, with limit, since, sources, and query all documented in-schema (including the ISO 8601 and 90m/24h/7d window formats). The description only reinforces the source scope ('Bluesky and Hacker News only, not X/Twitter') and adds no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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?

Starts with a specific verb and resource ('Search social posts on Bluesky and Hacker News') and immediately scopes it ('recent public posts about a topic'). It names the sibling it must not be confused with (news_search) and rules out X/Twitter, so an agent can route correctly without opening either 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?

Explicitly routes news-article queries to news_search and repeats the 'not X/Twitter' boundary, giving clear context for when this tool is correct. It does not, however, spell out when other content-search siblings (search_with_contents, get_topic_trends_attention) would be preferred, so it stops short of full when/when-not guidance.

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