Quorumz Sense

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

Beyond the readOnly/openWorld annotations, the description discloses the per-call price, that unknown ids are not charged, the required Authorization: Bearer API key on the connection, and the 100-call/7-day free window. These are precisely the operational facts an agent needs before spending money or hitting an auth failure.

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 dense sentences: the first front-loads what is returned and the id source, the second packs cost, error-billing behavior, auth, and free-tier limits. No filler and nothing important is buried.

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?

For a one-parameter read with an output schema, the description covers the remaining agent-relevant concerns: where the id comes from, what the response contains, auth requirements, and cost/billing edge cases. Nothing needed to invoke it 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% and the single parameter already carries the 'id of a list_news record' description, so the description largely restates it. It adds no new syntax, format, or constraint detail beyond the schema, which is the expected baseline here.

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 states exactly what is fetched (one news article), the key it is fetched by (article_id), and what comes with it (all the quorums on its story). It also anchors the id to a sibling tool, list_news, so an agent can distinguish this from list_news and search_quorums without opening a 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?

It makes the calling path clear: the id must come from a list_news record, which tells an agent to list before getting. It does not name an explicit alternative or exclusion (e.g., when to use get_quorum instead), so it falls 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.

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses the billing model ($0.01 per call, unknown ids are not charged), the authentication requirement (Quorumz API key as a Bearer token on the connection), and the free tier (first 100 calls in 7 days). These are exactly the operational facts an agent needs before spending a paid call, and nothing contradicts the 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?

The purpose is front-loaded in the first clause, followed by resource definition, then cost and auth. Every sentence carries useful signal, though the detailed viewpoint/support-count breakdown partially duplicates what the output schema already conveys.

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?

For a single-parameter read tool with full schema coverage, an output schema, and safety annotations, the description is self-sufficient: it covers semantics, cost, authentication, and free-tier limits. The only missing piece is sibling differentiation against sample_quorum and search_quorums.

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?

There is a single parameter at 100% schema description coverage, so the schema already defines quorum_id and notes it comes from another record. The description only restates "by quorum_id" without adding format, sourcing, or validity guidance. Baseline 3 applies since the schema carries the weight.

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 states a specific retrieval ("One quorum by quorum_id") and defines the resource domain richly: a news story split into distinct viewpoints with labels, summaries, and support counts split across media, socials and iwitness. An agent knows exactly what object comes back. It does not, however, distinguish this from siblings like sample_quorum or search_quorums, which are alternate routes to quorum data.

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 only implied: "by quorum_id" signals this is the lookup path when an id is already known. There is no explicit statement of when to prefer this over search_quorums (discovery) or sample_quorum (exploration), and no exclusion criteria. The cost and free-tier notes help an agent decide whether to spend a call, but they are not routing guidance.

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?

Beyond readOnlyHint/openWorldHint, the description discloses the real operational traits: $0.02 per event returned, an empty page being free, the requirement for a Quorumz API key as a Bearer header on this connection, and a 100-call/7-day free allowance. It also discloses result ordering and that quorum data is only present 'when one exists' — the kind of non-obvious detail that prevents misuse.

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 what alpha events are, then payload, then filters, then cost/auth. Three dense sentences with no filler, though the final sentence bundles pricing, empty-page behavior, keys, and free-tier limits into one long clause.

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 an output schema present, the field list is somewhat redundant, but cost, authentication, and paging expectations are all covered, which matters for a paid, keyed endpoint. The only gap is that alpha_kind and alpha_score are returned but their meaning or value range is never characterized.

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 adds genuine meaning by tying cost to the limit parameter ('costs $0.02 per event returned') and by framing cell/country as filters over the newest-first stream. It doesn't explain cursor mechanics beyond what the schema already says.

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 defines the resource concretely — 'stories flagged ahead of the wider press' — and states the ordering ('newest first') plus the data each event carries, so an agent knows exactly what comes back. It stops short of differentiating this from list_news or search_quorums, so the agent must infer whether alpha events or general news is the right feed.

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?

Filtering options (country, geohash cell) are stated, which implies when to use them, but there is no explicit guidance on when to choose this tool over list_news or the quorum siblings, and no stated exclusions. Usage is implied rather than directed.

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 readOnlyHint and openWorldHint; the description adds substantially more: an itemized return shape (title, summary, countries, quorums with support counts), a per-article price of $0.005 with empty pages free, the requirement for a Bearer API key on the connection, and a free tier of 100 calls in 7 days. Those cost and authentication facts are exactly the operational context annotations cannot express.

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 what is returned before the billing and auth constraints. It is dense but nothing is clearly wasted; the long parenthetical about quorums is the only place that could be tightened.

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?

An output schema exists, so return values need no prose, and the description nonetheless covers ordering, filters, pagination, price per record, auth, and the free tier. For a three-parameter read tool with full schema coverage, an agent has everything needed to call it correctly and predict the cost.

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 parameters are already fully documented and the baseline is 3. The description's 'filter by country' restates the schema rather than extending it, though the 'most recently active first' ordering and the note that every returned record is billed do add mild interpretation value.

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 names a specific resource (news articles) and its default ordering (most recently active first), and it enumerates what each article carries. It stops short of distinguishing itself from siblings such as get_article or search_quorums, so an agent must infer the boundary between listing and fetching a single article.

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 supplies context – filter by country, paginate with a cursor, omit the cursor for the newest – which implies when to use it. It never states when to prefer get_article or search_quorums, nor does it flag any exclusions, so the routing decision against siblings is left implicit.

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 readOnlyHint and openWorldHint=false, so the safety profile is covered; the description adds genuinely new behavior facts: free tier, no API key required, and output parity with search_quorums. It stops short of saying whether the sample is fixed, randomized, or rate-limited, and whether it returns exactly one quorum or a small set, which are the remaining behavioral unknowns.

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 sentences, front-loaded with the free/no-key differentiator and the output-shape guarantee. The middle sentence defining the quorum data model is longer than strictly necessary but earns its place by telling an agent how to interpret support_count and viewpoint labels.

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 zero parameters and an output schema present, the description needs only to explain purpose, access model, and return parity, all of which it does. The minor omission is cardinality/randomness of the sample, which an agent might want to know before relying on it for anything beyond a shape preview.

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?

The tool takes no parameters, so there is no parameter meaning to add beyond the schema. Baseline for a zero-parameter tool is 4, and the description correctly explains what the (parameterless) call returns.

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 identifies the resource ('a recent, well-sourced quorum') and ties it explicitly to the sibling search_quorums by promising 'the exact shape search_quorums returns.' It also defines what a quorum contains (viewpoints with label, summary, support_count split into media/socials/iwitness). The only gap is that the action verb is implied rather than stated, and it never contrasts with get_quorum.

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 it to see the data before paying' plus 'Free, no key needed' gives a concrete selection condition: pick this over paid siblings when previewing or unauthenticated. It does not spell out when NOT to use it (e.g., when you need a specific quorum by id, which get_quorum presumably covers), but the zero-parameter, free-preview framing makes the intended role clear.

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?

Beyond readOnlyHint/openWorldHint, the description discloses the cost model ($0.01 per quorum, empty page free, first 100 calls in 7 days free), the authentication requirement (Quorumz API key as a Bearer token on the connection), sort order, and pagination method. These are exactly the operational facts an agent needs before calling a paid, credentialed endpoint, and none are recoverable from the 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?

It is front-loaded with the feed description and closes with the two operational constraints that matter most (cost and auth). The sentence enumerating viewpoint fields overlaps with the output schema, which is a small amount of waste but doesn't obscure the call-relevant information.

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?

For a read-only, credentialed, metered listing tool the description covers ordering, filtering, pagination, cost, and auth, and an output schema already documents return shape. An agent has everything needed to decide to call it and to call it 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?

Schema description coverage is 100%, and the description's parameter-relevant content (country filtering, cursor paging) merely restates what the schema already documents with more precision (ISO 3166 alpha-2, next_cursor of previous page). Baseline 3 applies since the schema carries the semantic load.

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 states the resource concretely ("the live quorum feed, newest first") and defines what a quorum is (a story split into viewpoints with label, summary and support_count), plus its filtering and paging capabilities. It never names its closest siblings (get_quorum, sample_quorum) or explains how it differs from them, so an agent can't fully route between the quorum-family tools from this text alone.

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 live quorum feed" plus "Filter by country; page with cursor" implies a browsing/listing use case, but there is no explicit when-to-use or when-not-to guidance and no mention of sample_quorum or get_quorum as alternatives for other needs. Usage is inferable rather than stated.

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