ScrapeMole Social

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

With annotations already covering read/idempotent/open-world safety, the description still adds substantial non-obvious behavior: cost model (x402 USDC on Base, $0.002 per successful call), the payment-required failure path, the 50-item ceiling, and cursor pagination. These are exactly the traits an agent cannot infer from the schema or annotations.

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?

Purpose is front-loaded and the payment caveat is isolated in its own sentence; every clause carries information. The middle clause enumerating returned fields is dense, but it is informative rather than padded.

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 lists the fields returned, the maximum record count, and how pagination and payment errors behave, so an agent can plan both the call and the response handling. Nothing material is missing for a read-only feed tool.

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 3-baseline applies, but the description does add interpretive value: it explains that the result set contains original posts by default and that replies/reposts are opt-in via the filter, framing filter choice in terms of returned content. The limit ceiling and cursor behavior largely restate schema text.

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: 'monitor what a specific Bluesky account has posted recently', plus the returned payload shape (up to 50 posts with text, time, engagement counts, links). This clearly separates it from bluesky_search (keyword search) and bluesky_profile (account metadata) even though those siblings are never named.

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 use case ('monitor what a specific account has posted recently') and practical invocation guidance for the paid flow ('call without payment to receive the PaymentRequired object'). It stops short of naming alternatives such as bluesky_search for keyword-based discovery, so there is context but no explicit exclusion.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), but the description goes well beyond: it scopes data to 'Public profile data only', discloses the paid x402/USDC-on-Base model at $0.001 per successful call, and — critically — tells the agent that an unpaid call returns a PaymentRequired object rather than an error. That is exactly the kind of non-obvious runtime behavior an agent needs.

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 purpose and returned fields are front-loaded, followed by the access constraint and the payment mechanics. Every sentence carries distinct information with no repetition of schema or annotations.

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?

With no output schema, the description responsibly enumerates the return fields; with one simple parameter it explains the input; and it discloses access limits and payment flow. An agent has everything needed to call it correctly and interpret the response.

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% and the single 'actor' parameter is already documented as 'Handle (e.g. bsky.app) or DID'. The description adds no format or resolution detail beyond that, 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?

States a specific verb+resource ('look up or verify a Bluesky account') and enumerates the exact payload (DID, handle, display name, bio, counts, creation time, avatar/banner, labels). This clearly separates it from siblings like bluesky_feed and bluesky_search, which return different resource types.

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?

'Use to look up or verify a Bluesky account' gives a clear triggering context, and the single-handle/DID input makes its niche obvious relative to feed and search tools. It stops short of naming which sibling to use for the alternative cases (e.g. searching posts), so no explicit exclusion.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds substantial non-obvious behavior: it is a paid tool billed $0.002 USDC on Base per successful call and that an unpaid call returns a PaymentRequired object. It also enumerates the returned fields, so the agent knows both the cost model and the payload shape.

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?

A single dense paragraph, but front-loaded with the purpose and use case before the mechanical details. Every clause carries information (query syntax, return fields, pagination, payment), though the sentence runs long and could be split for scanability.

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?

With no output schema, the description carries the return-value burden and does so by listing text, author handle/display name, createdAt, engagement counts, links and a bsky.app URL. Payment mechanics and pagination are also covered, leaving no practical gap for correct invocation.

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 baseline is 3, but the description meaningfully enriches semantics by spelling out the supported query syntax (from:handle, #tags, since:/until:) that the schema only gestures at as 'Bluesky search syntax'. It also clarifies that cursor is for pagination.

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 ('returns up to 50 public posts matching a query') scoped to Bluesky, immediately distinguishing it from bluesky_feed and bluesky_profile. The query-capability summary makes the tool's niche unambiguous.

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?

Opens with explicit use cases ('real-time social listening, brand/topic mentions and sentiment research'), which tells the agent when this tool fits. It does not name a sibling as the alternative or state when not to use it (e.g., vs. bluesky_feed for timeline browsing), 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.

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

Annotations already declare read-only, idempotent and open-world behavior, and the description adds substantial context beyond them: the exact return fields delivered, the default type/sort behavior, and the paid x402 USDC-on-Base model with $0.001 per successful call and the PaymentRequired object on unpaid calls. That payment and output-shape detail is real value not available in the structured fields.

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-loaded with the core purpose and scope, then returns, then the alternative service, then payment. Dense but every sentence carries useful information; only slight trimming would be possible without losing content.

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?

With no output schema, the description explicitly lists the returned fields, covers default behavior and the payment requirement, and its annotations cover the safety profile. Nothing an agent needs to call this search tool correctly is missing.

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 all six parameters and their defaults are already documented in the schema; the description's mentions of 'stories or comments', 'last N days', 'minimum points' and 'relevance or newest' merely restate those schema semantics. It adds no format, range or interaction detail beyond what the schema provides, 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?

States a specific verb (searches) and resource (HN stories/comments across history), plus default behavior (story, relevance sort) that disambiguates it from a live-feed fetch. It does not explicitly name the sibling hn_thread, so the differentiation from that sibling is inferable but not stated.

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 use case (find what HN says about a product, company, library or topic) and an explicit exclusion with an alternative (use ScrapeMole Pulse for live front page/new/best/Ask HN/Show HN/jobs). However, it does not address when to prefer hn_thread over this search within the same server.

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

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

Annotations only declare the safe-read profile (readOnly/openWorld/idempotent); the description goes well beyond them by disclosing that this is a paid tool, the payment rail (x402 USDC on Base), the exact price ($0.002 per successful call), and the failure mode of calling unpaid (a PaymentRequired object is returned). It also notes comments are capped and HTML-stripped to plain text, which shapes what the agent will actually receive.

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-loaded with purpose followed by return contents, then usage and alternative routing, then the payment caveat in a final sentence. Every sentence carries information, though the payment/URL detail makes it denser than strictly needed for selection alone.

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?

With no output schema, the description takes responsibility for describing the return shape (story fields plus threaded comments with depth/author/time/plain text), and it covers the commercial prerequisite an agent must know before calling. Nothing material for correct invocation is missing.

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%, so both 'id' and 'limit' are already documented, and the schema is the authority on the 1-300 range. The description adds only light framing — that limit caps comments returned in thread order — which does not exceed the schema. Baseline 3 is appropriate.

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 ('read the discussion on a Hacker News post') and enumerates exactly what comes back: story fields (title, URL, points, author, time) plus comments with depth, author, time and stripped plain text. This separates it cleanly from hn_search (searching) and from the Pulse endpoint that serves HN list feeds.

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 an explicit use case ('summarising community reaction to a launch') and routes a competing need — the live front page, new, best, Ask HN, Show HN and job lists — to a named alternative with a URL. It does not, however, differentiate itself from the hn_search sibling, so the routing is clear for list feeds but incomplete against the closest HN-adjacent tool.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds genuinely new behavioral facts they cannot convey: the hard 25-story ceiling, the live 'right now' freshness, the exact per-call price ($0.002 USDC on Base), the x402 payment mechanism, and the failure mode of calling unpaid (returns a PaymentRequired object). This is exactly the kind of cost/auth disclosure an agent needs before invoking.

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, front-loaded with the purpose, then output shape, then cost/payment. No filler; the long payment clause is dense with required operational information rather than padding.

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?

With no output schema, the description usefully enumerates the returned fields (title, URL, score, comment count, tags, submitter, time). All three parameters are covered by the schema, and the payment/auth model — the biggest risk of misfire for an agent — is fully explained.

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%, so tag, list, and limit are already documented in the schema with defaults and range. The description only echoes them ('optionally filtered to one tag', 'up to 25 stories'), adding no syntax, validation, or semantic detail beyond the schema — the baseline 3 for full coverage.

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 ('returns up to 25 stories from the hottest or newest page') plus the exact scope (Lobsters, optional single-tag filter) and the fields returned. Since no sibling covers Lobsters, the platform name alone cleanly separates it from the bluesky_*/hn_*/mastodon_*/telegram_* tools.

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?

'Use to see what programmers on Lobsters are discussing right now' gives a clear use context, and the description distinguishes the hottest vs newest pages that the `list` parameter selects. It never states when NOT to use it or names an alternative (e.g., the other platform feeds) for different data sources.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing public-posts-only scope, the official public API with no login, and — critically — the payment model (x402 USDC on Base at $0.001 per successful call, and that an unpaid call returns a PaymentRequired object). That pricing/error behavior is exactly the kind of operational context an agent cannot infer elsewhere.

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, front-loaded with the use-case and result shape, then operational caveats. The field enumeration is dense but earns its place given there is no output schema; no filler 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?

With no output schema, the description compensates by enumerating returned fields (plain text, author handle, createdAt, language, reblog/favourite/reply counts, tags, URLs) and covers auth-free access plus the payment/handshake flow. An agent has everything needed to call this correctly and interpret the response.

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%, so the baseline is 3. The description restates the instance default (mastodon.social, or any public instance via instance=) and the 40-post cap, but adds little beyond what the schema already documents; it does not clarify max_id pagination semantics in prose.

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 resource (Mastodon hashtag timeline) and scope (up to 40 recent public posts tagged #tag), with the platform named explicitly. The fediverse/Mastodon framing cleanly separates it from the bluesky_*, hn_*, lobsters_* and telegram_* siblings without needing to name them.

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?

"Use for fediverse social listening on a topic or brand hashtag" gives a clear positive use context. There are no explicit exclusions or named alternatives (e.g. when to prefer bluesky_search), so it stops short of a full when/when-not rubric.

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

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

Annotations already cover the read-only/open-world/idempotent profile, and the description layers on substantial extra behavior: the 20-post cap, the exact public-only/web-preview eligibility constraint, no authentication requirement, and the x402 USDC on Base paid model with the PaymentRequired response returned on unpaid calls. That pricing and 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-loaded with the primary use case, then return shape, then modifiers, then constraints, then pricing. Dense but nearly every clause earns its place; the run-on sentence structure and duplicated mention of the 20-post cap cost it the top mark.

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, so the description carries the return-value burden and does so explicitly (field list, channel metadata). Combined with eligibility rules and payment semantics, an agent has everything needed to decide and call correctly.

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?

With 100% schema coverage the baseline is 3, but the description adds value beyond the schema: concrete channel-value examples ('durov', 'telegram', or a t.me link), clarification that q= searches within the given channel, and that before= is for paging backward. The limit parameter is only echoed from the schema, so it is not a full 5.

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+resource (monitor/research public Telegram channels) and enumerates the concrete payload: up to 20 recent posts with text, ISO date, view count, links, forward source, media flags, post URLs, plus channel title/bio/subscriber count. The platform scoping makes it trivially distinguishable from siblings like bluesky_feed, hn_search, or lobsters_hot.

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 clear context ('monitor or research'), the qualifying condition (public channels with web preview enabled), and exclusions ('no login, no private chats or groups'). It also explains the q= and before= usage modes. It does not explicitly name a sibling tool as the alternative for non-Telegram platforms, so it falls 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.