Voidly Hosted MCP

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's job is lighter. It still adds value by pre-announcing the return payload shape and, notably, warning that usage counts are withheld (internal_operator_metric: true) so the agent doesn't retry looking for them.

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 core capability, with the caveat second. The explanation about internal operator metrics is slightly wordy but earns its place by preventing futile follow-up calls.

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 describing returned fields (protocol, encryption, endpoints, availability) and the internal_operator_metric flag is necessary and largely done. Only minor gaps remain, such as what 'availability' states beyond degraded/unavailable.

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 zero parameters, so there is nothing to document; the baseline for 0-param tools is 4. The description correctly says nothing about inputs and instead spends its words on output semantics.

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 ('Get') and resource ('Voidly Agent Relay status') and enumerates what the status comprises: protocol, encryption, endpoints, availability. No sibling tool covers relay status, so ambiguity is low.

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 (you'd call it to check whether the relay is up). There is no explicit when-to-use/when-not framing or reference to an alternative tool, though the absence of relay-related siblings keeps mis-selection unlikely.

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 non-readonly, open-world, non-idempotent, non-destructive. The description adds real behavioral context beyond them: the body bytes must be forwarded unmodified, the caller must supply an Ed25519 signature over the exact board path, no key is stored server-side, and no payment occurs. It omits nonce-replay and timestamp-window behavior, but the signing contract is well disclosed.

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?

Four short sentences, front-loaded with the core contract (unmodified byte forwarding) before the signing requirement and the two exclusions. No filler; every sentence carries a distinct fact.

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 explanation, and annotations cover the safety/mutation profile. The description supplies the unusual signing workflow and the no-key/no-payment guarantees. Gaps remain around replay protection and timestamp validity, but the essential operational contract is 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 description coverage is 0% with six parameters, so the description must carry the load and only partly does: it explains replyTo as the public thread selector and implies signature/did semantics via the Ed25519 signing statement. did, nonce, timestamp, and bodyJson constraints (formats, size limits, freshness) go unexplained 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?

The title and first sentence establish a specific operation: forwarding a caller-signed raw JSON body to a public board. It distinguishes the mechanism (signed post) from siblings and notes no payment is involved, implicitly separating it from the voidpay_* tools. It does not explicitly name a sibling it should be preferred over.

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 states a prerequisite ('a local client must sign the exact board path with its Ed25519 key') and rules out payment, giving useful context. However, it never says when to choose board_post versus board_reply_private or board_reply variants, leaving the private-vs-public reply distinction to inference from 'replyTo selects a public thread reply.'

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/non-destructive, so the bar is lower, and the description still adds real value: a hard reply cap of 20, the guarantee that private replies are excluded, and a prompt-injection warning that board text and links are untrusted public content.

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 short sentences, zero filler, with the core read scope front-loaded and the security caveat last.

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 low-complexity read tool with an output schema (so return values need no explanation), the description covers scope, privacy filtering, and the untrusted-content caveat; only cursor-based pagination is left unexplained.

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 parameter meaning; it explains the reply cap ('up to 20') which matches the limit maximum, but says nothing about cursor pagination, which is the non-obvious parameter for retrieving results beyond the first page.

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: 'Read one post and up to 20 public replies.' The clause 'Private replies are never included' implicitly distinguishes it from the sibling board_reply_private, though it never names alternatives like board_post or board_search.

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 by 'Read one post' and the private-reply exclusion, but there is no explicit statement of when to prefer this over board_search or board_post, and no prerequisites or exclusions beyond the privacy rule.

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 annotations (readOnly/idempotent/openWorld/non-destructive), the description discloses substantive constraints: no message text, ciphertext or keys accepted, no reply sent, and that sender/recipient DIDs are retained in the DM rail. These privacy and scope facts are exactly what an agent needs and are not 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?

Three tight sentences, purpose front-loaded, followed by scope exclusions. No filler, though the retention note ('The current DM rail retains...') is slightly abrupt and could tie back to privacy more explicitly.

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 not be explained, and annotations cover the safety profile. The description usefully clarifies that no reply is actually sent despite the 'reply' name, though it leaves the postId parameter entirely unexplained.

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% and the description never mentions the single parameter or its required UUID postId format. With the schema carrying no prose, the description fails to compensate; only the indirect mention of 'post author' hints at the input's meaning.

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: 'Resolve the post author,' distinguishing this private DM-prep operation from the public board_post/board_read/board_search siblings. The framing is slightly at odds with the 'reply' name and title, which could confuse an agent about whether a reply is sent, but the first sentence is concrete.

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: the description rules out sending and content handling, signaling the caller must compose the DM locally, but it never states when to pick this over alternatives or what workflow it belongs to. No sibling is named as an alternative.

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 safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new context: the result is a single 'bounded' page, and the returned content is untrusted, with listing links explicitly not payment proof. That trust/warning detail goes beyond anything structured fields provide.

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 short sentences with no filler, and the core scope statement is front-loaded. The trust warning is compact and earns its place, though the three ideas are slightly disjointed.

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 not be described, and the untrusted-content warning covers a real risk. Still, for a five-parameter tool with 0% schema coverage, the description omits too much (query syntax, tag meaning, limit default, cursor pagination) to be fully actionable.

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% across five parameters, so the description must carry the burden, yet it only clarifies 'board' (omit for all). The query (q), tag, limit, and cursor parameters are entirely undocumented, leaving pagination and filtering semantics unexplained.

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 gives a concrete verb and resource: 'Read one bounded public board page', with 'public board' establishing scope. It is clear it is a bounded read, but it never mentions that this tool accepts a query string or tag to filter, which is the defining behavior of a 'search' tool.

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?

'Omit board for All posts' gives an explicit conditional on one parameter, which is useful usage guidance. However, it never states when to use this tool versus siblings like board_read or board_post, so routing between board tools is left to inference.

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 safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the description's added value is the 7-day window, the single-source constraint ("reads only the OONI index"), and the low-confidence flag — all real behavioral context an agent can't get from annotations. It stops short of saying what happens for a country with sparse or missing index data.

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, zero filler, with the returned-field inventory front-loaded and the scope caveat immediately after. Every clause earns its place.

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 correctly compensates by enumerating the five returned fields, which is the critical missing piece. It is slightly under-specified on failure/empty-index behavior and on the freshness semantics of the ingestion timestamp, but is otherwise complete for a one-parameter read.

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 single parameter has 100% schema coverage including the ISO 3166-1 alpha-2 pattern and uppercase requirement, so the schema carries the semantics. The description only obliquely references the parameter as "one country's" and adds no format or edge-case guidance beyond the schema. 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 and resource ("Returns one country's 7-day OONI index signal") and enumerates exactly what the payload contains: score 0-100, rank, measurement count, low-confidence flag, ingestion time. The second sentence scopes it against sibling territory (incident details, per-measurement citations belong elsewhere), 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 exclusion sentence implicitly tells the agent not to come here for incident detail or citations, which implies the use case (a quick single-country index snapshot). However, it never says when to prefer this over close siblings like get_country_profile, get_country_status, or get_atlas_score, leaving the routing decision to inference.

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 safety profile (readOnlyHint=true, openWorldHint=false), and the description adds meaningful behavior beyond them: large outputs are truncated, the status column distinguishes corroborated vs suspected rows, and the REST URL is the escape hatch for full files. Missing only specifics like the truncation threshold or auth requirements.

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 purpose front-loaded and no filler. Each sentence carries distinct information (formats, output semantics, truncation guidance), though the format list partially duplicates the schema.

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 bears the burden of explaining returns; it does cover the status column and truncation, which is useful. However it never says where the 'REST URL' comes from or what the export actually returns, leaving a gap an agent would hit in practice.

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 format enum and country ISO filter are already documented. The description restates the format options and adds only a weak contextual hint that country filtering reduces truncation. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Bulk export of the incident corpus') and enumerates the output formats, which cleanly separates it from single-record siblings like get_incident_detail and incremental ones like get_incidents_since. It does not explicitly name those siblings, so differentiation is implied rather than 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?

Provides some operational routing — 'filter by country or fetch the REST URL for the full file' — but this addresses truncation, not tool selection. There is no explicit when-to-use versus the many get_incident_* siblings; the bulk-vs-incremental distinction is left to inference from the word 'bulk'.

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=true and openWorldHint=false, so the safety profile is covered; the description usefully adds behavior beyond that — a best-first ranking that surfaces real events over single-source outage signals, and the default citable=true filtering behavior. It stops short of describing return shape or volume/pagination behavior.

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 compact sentences with the core purpose and ranking behavior front-loaded. The sentence about the human-readable ID format earns its place by flagging citability, though it is slightly tangential to invoking the tool.

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 still notes the citable ID format and the ranking/ordering behavior, and the readOnly annotation covers the safety profile. An agent has everything needed to call this correctly for a simple filtered list 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 description coverage is 100%, so all four parameters (limit, citable, country, min_sources) are already fully documented in the schema. The description only re-explains citable (its false branch) and adds no syntax or semantics for limit/country/min_sources, matching the baseline for schema-dominated definitions.

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 clear verb+resource ('Get citable censorship incidents') and adds scope/ordering ('multi-source, evidence-backed, ranked best-first'), distinguishing citable incidents from raw single-source IODA outage signals. It does not name any of its close siblings (e.g., get_incidents_since, get_incident_detail), so it falls just short of full sibling differentiation.

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?

Provides one explicit conditional ('Set citable=false to include raw outage signals'), which hints at when to loosen filtering, but offers no when-to-use guidance relative to the many incident-related siblings or any exclusions. Usage is largely implied rather than stated.

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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value beyond that: it discloses the method is unsupervised/DBSCAN, that output carries 'model caveats,' and that results are exploratory ('may surface') rather than authoritative. It stops short of describing the return shape or any rate/limit behavior.

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, front-loaded with what the tool produces before the caveat about complementary coverage. 'CenDTect-style' is unexplained jargon, but nothing is 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?

For a read-only, single-param tool with no output schema, the description is close to sufficient, but it leaves ambiguity about the result shape — a scalar country-level score versus a per-day anomaly list — which matters given the phrase 'surface shape-anomalous days.' A brief note on the returned granularity would close the gap.

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% for the single country_code parameter, and the schema already documents the ISO 3166-1 alpha-2 format with examples. The description adds no syntax or format 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?

The description gives a specific verb (read/score), resource (anomaly score for a country) and method (unsupervised DBSCAN, CenDTect-style). It distinguishes itself from the supervised-label path by framing itself as a 'second opinion,' though it names no sibling tool 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?

It implies usage via 'second-opinion' and 'may surface shape-anomalous days the supervised labels missed,' which hints at when to reach for it over a supervised classifier. However, it never states an explicit when-to-use/when-not condition or names the alternative tool (e.g., get_classifier_score) to route the agent.

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=true and openWorldHint=false, so the safety profile is covered. The description adds that the output consists of A–F censorship grades and that omitting country_code returns all graded countries, but it does not describe return structure or other behavioral details beyond that.

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 description is two efficient sentences with no wasted words. It front-loads the resource and output type before giving the optional parameter guidance.

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 simple one-parameter read tool with annotations and no output schema, the description covers what the tool returns and how to scope it. It could be slightly more complete by clarifying the return shape of the grade table, but overall it is adequate.

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 schema already documents country_code as an optional ISO alpha-2 code. The description reinforces the omit-for-all behavior but adds no syntax, format, or validation 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?

The description states a specific verb-resource pair: retrieving 'Atlas Score v2 A–F censorship grade(s).' It clearly defines the returned data type and the optional scope, but it does not explicitly distinguish this tool from related siblings such as get_censorship_index or get_country_profile.

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 gives clear parameter-driven usage guidance: 'Pass country_code for one country; omit for all graded countries.' However, it offers no guidance on when to use this tool versus the many sibling censorship-grade/report tools, so the usage context is only implied.

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=true and openWorldHint=false, so safety is covered. The description then adds genuinely non-obvious behavioral context: national block counts are deliberately null because that layer is being rebuilt after false positives, and a review object carries the layer's window end as the data date — exactly the kind of caveat that prevents an agent from misreading nulls as missing data.

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 tight sentences, front-loaded with what the tool returns and followed by the null-data caveat. Every clause earns its place — no restatement of the title or name.

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 must describe the return shape, and it does: per-code entries with name and measured-domain count, plus null national counts and a review object with a window end. It stops short of showing the field names or orientation of the response, so an agent still learns the structure only by calling.

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?

Zero parameters, so per the baseline the schema can carry no semantic burden and the description need not document arguments. Nothing is missing on this dimension.

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 — a content-category legend mapping codes like NEWS/POLR to human names and measured-domain counts — with the verb implied by 'legend'. An agent can tell this is a static lookup table rather than a filtering or aggregation tool, though it never names the nearest siblings (get_isp_categories, get_category_coverage) to sharpen the boundary.

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: the description makes clear this is the reference for decoding category codes, but it never says when to call it instead of get_censorship_by_category or get_category_coverage, nor any precondition such as 'call this first to interpret codes returned elsewhere'.

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 safety is covered; the description adds genuine behavioral context by disclosing that the tool reports tagged/untagged counts plus per-category domain counts and that it is an honest self-disclosure of a categorization blind spot. No pagination, timeframe, or freshness caveats are given, which is the remaining gap.

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 short sentences, front-loaded with the core question it answers and the return contents. The em-dash appositive about the 'blind spot' is slightly ornamental but still earns its place as framing for a coverage metric.

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 parameters and no output schema, the description must carry the return-value burden, and it does name the outputs (tagged/untagged counts, per-category counts). It omits things like when the snapshot was taken or whether coverage is global vs. per-region, which an agent might reasonably want.

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 zero parameters, so the schema cannot add semantic meaning and the baseline is 4. The description correctly implies a no-argument call by not referencing any filters.

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 measurement (what share of Voidly's measured-domain corpus carries a Citizen Lab content category) rather than a vague verb, and signals what it is not by tying itself to 'by category' analyses. It stops short of naming the sibling tools it most resembles (get_categories, get_censorship_by_category) to make the distinction explicit.

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 gives a clear when-to-use context: gauge how complete any 'by category' analysis is. There is no when-not guidance and no named alternative, so the routing against sibling category tools is left partially to inference.

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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: that data is withheld, that counts/rankings will come back null, and that a review object carries the layer's window end as the data date — a real degradation disclosure an agent would not otherwise know.

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 a single dense sentence that front-loads 'Under review' before saying anything about the actual resource, and the explanatory clause about false positives is padded. Not bloated, but the priority ordering buries the capability behind the suspension notice.

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-param read tool with full schema coverage and no output schema, the description does explain the returned shape (category code, null rows, review object) and the data date. What it omits is the practical next step — which sibling tool to use to get the withheld ranking — leaving the agent stranded once it learns the data is unavailable.

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?

Only one parameter and schema coverage is 100%, with the enum-like examples (NEWS, ANON, HUMR, ...) already in the schema. The description adds nothing about the category code, 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?

The description conveys the underlying concept (which countries block the most domains within a Citizen Lab category) but frames it entirely as a suspended feature, so an agent cannot tell what the tool actually returns today beyond 'null rows'. The resource is identifiable, but the verb/deliverable is degraded and muddied by the review narrative.

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?

No when-to-use guidance and no routing to alternatives. With siblings like get_censorship_by_category, get_most_blocked_domains, and get_national_blocklist available, the description should say what to call instead while rankings are withheld, but it never names a substitute.

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=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that - what the data actually reveals (content-targeted blocking, e.g. TCP-reset for messaging vs DNS-poisoning for news) - without covering pagination or output format.

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 front-loaded clauses with the core purpose first, then a concrete illustration, then parameter guidance. The 'e.g.' example is somewhat long but earns its place by clarifying the emission insight; no redundant 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 carries the burden of describing returns and does so conceptually (per-category technique composition). A single optional parameter tool with readOnly annotation is well covered, though return shape (list/aggregate format) is left implicit.

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 ISO 3166-1 alpha-2 semantics are already documented. The description still adds meaning beyond the schema by specifying the default behavior when the parameter is omitted (global view), which the schema alone does not state.

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: it returns the blocking-technique composition per content category, with concrete examples (news, communication tools, anonymity/VPN, search, adult). The 'by category' axis implicitly distinguishes it from sibling get_censorship_by_region, letting an agent pick the right one 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?

Explicitly tells the agent how to vary scope: 'Omit country_code for a global view; add it to see one country.' That is clear when-to-use guidance conditioned on the parameter, though it names no alternative sibling tool or 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?

Goes well beyond the readOnly/openWorld annotations by disclosing that block fractions and confirmed block counts are under review, return null, and come back with a review object plus a data date — a significant non-obvious caveat. It stops short of describing the rest of the response shape (how counts are aggregated, ordering, or the review object's fields), which matters since there is no output schema.

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 payload (coverage plus the under-review caveat) is correctly front-loaded, but the second sentence is a ~60-word run-on explaining internal provenance (CensoredPlanet rows, IODA outages, national blocklist layer, false positives in open countries) that is far longer than the agent needs to act correctly.

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-optional-parameter read tool with no output schema, the description covers what is returned, the default grouping, and the one anomalous return case. Only the broader response structure and aggregation semantics are left unspecified.

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 schema already documents the only parameter as "'continent' (default) or 'subregion'"; the description largely repeats that. Baseline 3 is appropriate since the schema does the work.

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 first sentence states a specific resource and scope: measurement coverage by world region, returning countries measured and measurement counts, with continent vs. UN sub-region granularity. A sibling get_censorship_by_category exists but is not named, so the agent must infer the split from the tool names 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?

It implies when to change behavior ("UN sub-region with level=subregion") but never says when to prefer this tool over get_censorship_by_category, get_global_heatmap, or get_censorship_index. Usage is inferable from the resource name rather than stated.

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=true and openWorldHint=false, so safety is covered; the description adds real value beyond that by disclosing the data provenance (OONI anomaly rates, risk tiers, measurement counts) and warning that scores are estimates, not confirmed block counts, and that coverage/dataAsOf must be read from the response.

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 tight sentences with no filler: the first defines the resource and scope, the second covers return content and the interpretive caveat. Everything is front-loaded and each clause earns its place.

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 must carry the return-value burden, and it does: country scores, risk tiers, measurement counts, plus the source window caveat. Complete enough to call correctly, though it never says how the index is ordered or how many countries are included.

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 zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misleads about inputs, and the note about reading coverage/dataAsOf from the response implicitly confirms there are no input filters.

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 ('Get the global censorship index with rankings for monitored countries') and scopes it to the global view. It does not name or contrast any sibling, so an agent cannot tell from the text alone why to pick this over get_censorship_summary or get_global_heatmap.

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 the global, parameterless nature of the tool; there is no explicit when-to-use statement, no exclusion criteria, and no named alternative among the crowded get_censorship_* family. Adequate but leaves routing to inference.

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 establish readOnlyHint=true and openWorldHint=false, and the description is consistent with both. It adds genuinely non-obvious behavior: the category mix is withheld pending a rule rebuild, false positives in open countries were the cause, and the response will contain bucket definitions, null country rows, and a review object whose data date is the layer's window end. That is real disclosure of what the returned payload looks like when degraded.

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 critical fact — 'Under review ... so it is withheld' — is front-loaded, and the return-shape sentence earns its place since there is no output schema. The first sentence does carry a lot of stacked clauses (category mix, source layer, false-positive history, rebuild), more than strictly needed to explain the withholding.

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 describing the return payload (bucket definitions, null country rows, review object with a data date) and by explaining why the payload is empty. About the only gap an agent might want is an explicit pointer to a working alternative tool while this one is under review.

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 optional country param is documented in-schema with examples (IR, RU, SA). The description only restates the usage ("Pass country=XX for one country") and adds the implication that omitting it returns multiple countries, which is marginal value over the schema.

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 — per-country category mix of nationally blocked domains, sourced from Voidly's national blocklist layer — which distinguishes it from siblings like get_censorship_by_category and get_national_blocklist. It also states plainly that the data is currently withheld, so an agent knows what the tool is for and that it is not producing real content right now.

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 gives an explicit calling convention ("Pass country=XX for one country"), implying omission returns all countries, and the 'under review' framing tells the agent not to treat results as substantive. However, it names no alternative for agents that actually need national blocklist data — get_national_blocklist in the sibling list would be the obvious substitute but is never referenced.

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 establish that the tool is read-only and closed-world. The description adds important data-quality behavior: certain headline fields are under review and return null, and a review object carries the layer window end as the data date. That is useful transparency beyond annotations, though it does not fully describe response structure.

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 description is two sentences and front-loads what the snapshot contains. The second sentence carries the necessary null-return caveat and review-object context; dense but free of filler.

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 and no parameters, the description needs to carry the return-value burden. It lists the coverage dimensions, identifies which fields return null, and explains the review object, which is sufficient for a zero-parameter summary tool, though the full response shape is not detailed.

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 has zero parameters, so there is no parameter semantics for the description to explain. Under the scoring rule, zero parameters establishes a baseline of 4.

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 gives a clear verb and resource: a one-call snapshot of Voidly's measurement coverage. It enumerates the included dimensions, so the agent understands what the tool returns. It does not explicitly contrast itself with sibling tools such as get_category_coverage or get_measurement_freshness, so it falls short of a 5.

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 'One-call snapshot' implies this is for overview use rather than detailed per-category or freshness queries. However, it never names alternatives or states when not to use it, leaving routing to the many sibling tools 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=true and openWorldHint=false, so the safety profile is covered. The description adds useful content context by naming the technique taxonomy the response is broken down by, plus an illustrative China/TCP-reset example. It stays silent on return format, data freshness, and whether values are per-country aggregates or raw counts, which is the remaining gap for a read-only analytic tool.

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 value proposition, then the technique list, then the usage rule. It is a single flowing sentence plus a short clause, with the China example earning its place as a concrete illustration. Slightly heavy on enumeration but nothing is wasted.

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-optional-param, read-only tool with 100% schema coverage and no output schema, the description is nearly complete: it explains purpose, scope, technique categories, and the country-vs-global switch. It could note data time range or aggregation level, but nothing essential to 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 coverage is 100% — the schema already documents country_code as an optional ISO 3166-1 alpha-2 code with an 'Omit for all countries' note. The description's 'omit for a global all-country view' largely restates that, adding only a format example (CN). Baseline 3 is appropriate when the schema does the work.

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 verb+resource ('breakdown of blocking techniques') and enumerates the technique dimensions (DNS manipulation, TCP-reset injection, Tor blocking, DPI/middlebox, etc.), so an agent knows exactly what this returns. The 'how a country censors, not just what' framing distinguishes it from the summary/index/'what is blocked' siblings, though it never names the closely related get_censorship_technique_trend.

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 gives one concrete usage rule ('Omit country_code for a global all-country view'), which is genuinely helpful. However it never states when to use this over alternatives like get_censorship_technique_trend, get_censorship_intent, or get_censorship_summary, leaving the agent to infer the distinction from the description's framing alone.

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=true and openWorldHint=false, so the safety profile is covered. The description adds a genuinely valuable behavioral detail beyond annotations: shares are coverage-robust percentages rather than raw counts and are therefore not skewed by growing measurement volume. It stops short of return shape/pagination specifics, keeping it at a strong 4.

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-loads the core purpose, then the sibling disambiguation, then a data-semantics caveat and the scoping defaults. Every sentence earns its place and there is no filler.

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 must imply the return shape, and 'monthly percentage composition' does so adequately, while annotations cover safety. A minor gap remains around exact output fields and pagination, but nothing essential to 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%, and the description's parameter guidance ('Omit country_code for global; months defaults to 12') largely restates the schema's own descriptions ('Omit for all countries', 'default 12, max 60'). Baseline 3 is appropriate since the schema carries the semantics.

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 (censorship method mix) and verb/scope (shifts over time, monthly percentage composition) and enumerates the techniques measured. It explicitly distinguishes itself from the sibling get_censorship_techniques by labeling that one a snapshot and this the trend, so an agent can route 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?

Names the alternative (get_censorship_techniques) and the exact condition that selects between them (snapshot vs trend). Also gives the operator lever: 'Omit country_code for global; months defaults to 12', leaving no inference needed for scoping.

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=true and openWorldHint=false, so the safety profile is covered. The description adds a substantive behavioral claim beyond that: the response includes evaluation methodology and caveats, suggesting an honest, self-critical disclosure rather than a raw number. However, it does not describe the shape or volume of that disclosure.

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 front-loaded sentence with a colon list of contents. It is efficient and waste-free, though the fragment style is terse rather than fully structured prose.

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 zero-arg, read-only tool the description is close to sufficient, but with no output schema and no explanation of return format, an agent does not know how version, training data, methodology, and caveats are presented. It is adequate but leaves the response shape unspecified.

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 zero parameters, which sets the baseline at 4 per the rubric. With no inputs to misdocument, the description is not required to carry parameter burden 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?

States a specific resource (classifier transparency) and enumerates what it returns: version, training data, evaluation methodology, caveats. It is clear what the tool delivers. It is not fully differentiated from siblings like get_classifier_scope or get_classifier_score, which the description does not name or contrast against, so it falls short of a 5.

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?

There is no when-to-use guidance, no condition that selects this tool over get_classifier_scope or get_classifier_score, and no exclusions. An agent sees an alphabetically adjacent trio of classifier tools and gets no routing signal from this description.

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 safety is covered; the description goes further by naming the three evaluation regimes and their purpose, listing returned metrics, and explicitly flagging that v2 had country-tier leakage and is not a live claim. That methodological caveat 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 core question (what the tool answers) and each subsequent sentence adds distinct value: the regimes, the returned metrics, and the honesty caveat. Slightly chatty phrasing, but no filler worth cutting.

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 parameters and no output schema, the description carries the return-value burden and does so well by enumerating AUC, F1, the generalization gap and citation guidance. What remains unaddressed is how this tool relates to its two classifier siblings.

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?

Zero parameters, so there is nothing to disambiguate and the baseline is 4. The description does not need to compensate for any schema gap.

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: reading the classifier's evaluation sidecars across three named regimes, plus the metrics returned. Clear enough to act on, but it never differentiates itself from the sibling tools get_classifier_info and get_classifier_score, leaving the agent to guess which classifier endpoint to pick.

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 real usage guidance about interpreting results ('Never quote one number alone', 'which metric to cite for which use'), but gives no when-to-use vs the classifier siblings (get_classifier_info, get_classifier_score) or when-not to call it. Usage is implied by content rather than routed.

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=true and openWorldHint=false, so safety is covered; the description adds genuine context in naming the metric family (LOCO mean F1) and flagging a 'small-sample median caveat', which warns the agent the value can be unreliable in low-data countries. It stops short of describing the return shape or what the caveat means operationally, and the endpoint reference (/v1/classifier/info) reads like leakage from a different tool.

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 compact sentences with no padding, and the core subject (classifier score plus model version) is front-loaded in the first clause. The trailing endpoint path is arguably noise but costs little.

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 tool with no output schema and safety already covered by annotations, the description is near-adequate: it names the metric and a reliability caveat. It is still ambiguous about what the response actually contains and how it relates to get_classifier_info/get_classifier_scope, so an agent could easily misroute.

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 description coverage and a single documented parameter (ISO 3166-1 alpha-2 code with examples), the schema does the work. The description adds no format, defaulting, or validation detail beyond it, 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 resource ('country-day censorship classifier score') and pins the model version (GradientBoosting v3.3), and it explicitly rules out a neighbouring concept ('this is not shutdown-onset skill'). However, it does not differentiate itself from close siblings like get_classifier_info or get_classifier_scope, and the phrase 'Read the current LOCO mean F1 and small-sample median caveat from /v1/classifier/info' muddies whether this tool returns a score or the info payload.

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?

Provides one useful exclusion ('this is not shutdown-onset skill'), which tells the agent when not to reach for it, but gives no positive trigger describing when the classifier score is the right call versus the many other score/risk siblings. Usage is implied by the name rather than stated.

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?

The description discloses important behavioral context beyond the annotations: the data is under review due to false positives, the layer is being rebuilt, outputs are withheld as null pairs, and a review object includes the layer's window end as the data date. This is exactly the kind of operational caveat 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 description is two sentences and front-loads the critical status ('Under review') before explaining the reason and current return behavior. It is efficient, though dense.

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 and no parameters, the description fully explains what the tool currently returns: null pairs plus a review object with the data date. An agent has enough information to understand the tool's current unusable state and return shape.

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 has zero parameters and the schema is complete, so there are no parameter semantics to document. The baseline for a no-parameter tool is a 4.

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 clearly identifies the resource as country pairs that share a national blocklist and states that the current output is withheld. It is specific enough to understand the tool's intended purpose, though it does not explicitly contrast with sibling tools such as get_national_blocklist.

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 'Under review' and 'pairs and overlap counts are withheld' implies the tool should not be used for substantive analysis right now. However, the description does not explicitly say when to use it or name an alternative such as get_national_blocklist.

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 supply readOnlyHint and openWorldHint, and the description adds genuinely useful behavior the schema cannot: the underlying data layer is under review for false positives, comparison fields will come back null, and a review object carries the layer's window end as the data date. That is exactly the kind of disclosure an agent needs to avoid treating nulls as 'no censorship'.

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 a single long compound sentence that leads with deprecation status rather than with what the tool returns or does, and the key fact (fields are null) is buried mid-sentence. The content is largely justified, but the ordering and density work against quick scanning.

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 carries the burden of describing returns, and it does so adequately: two country codes, null comparison fields, and a review object with a window-end date. Given the tool currently returns no real comparison data, this is close to complete for what an agent needs.

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 both parameters already document ISO country codes with examples. The description adds nothing about the two inputs (e.g. whether same-code input is allowed or how mismatched coverage between countries is handled), 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?

The description names the intended content (per-country national block counts, shared blocklist, per-category comparison) and the current return shape, so an agent can infer 'compare censorship between two countries'. But it never states the action in an active, front-loaded way and it is dominated by deprecation status rather than purpose. It is distinct enough not to be confused with get_country_profile or country_brief, but only by inference.

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?

No when-to-use guidance and no alternatives are named, despite obvious sibling overlap with country_brief, get_country_profile, get_co_blocking and get_national_blocklist. The only implicit guidance is that the tool is degraded, which an agent must piece together itself.

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 establish read-only and non-open-world behavior, and the description adds important data-quality context: the national blocklist field is null because that layer is under review and being rebuilt. This is genuinely useful transparency beyond the annotations, though it does not describe broader return behavior.

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 description is front-loaded and efficient: the first sentence states what the profile contains, and the second explains the null blocklist field. The second sentence is somewhat long, but its detail earns its place by clarifying a non-obvious data caveat.

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 profile tool without an output schema, the description sufficiently lists the main returned areas and explains the notable null field. It does not fully describe the return object shape, but it gives enough context 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?

There is only one parameter and schema coverage is 100%, so the schema already explains country_code with ISO examples. The description adds little beyond confirming that the profile is for one country, making the baseline 3 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?

The description names a specific resource, a country measurement profile, and enumerates its main contents: data freshness, measurement volume, and technique mix. It is distinguishable from broader siblings by profile scope, but it does not explicitly position itself against country_brief, get_country_status, or get_national_blocklist.

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 does not say when an agent should choose this tool over alternatives, nor does it provide exclusions or prerequisites. Usage is only implied by the term profile.

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=true and openWorldHint=false, so the safety profile is covered; the description earns credit for disclosing the return shape (no output schema exists) and for the interpretive caveat that these are aggregate country measurement signals rather than per-domain block verdicts. No permissions, rate limits, or freshness caveats beyond lastUpdated are noted.

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 resource identity, then the field inventory, then the scoping caveat. The field list is dense but each item maps to a real returned value; 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?

For a single-parameter read-only lookup with no output schema and no annotations gap, the description does the necessary work: it enumerates the returned fields and frames how to interpret them. The remaining hole is sibling differentiation from get_country_profile/get_country_compare, which the agent cannot resolve from this text.

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?

Only one parameter, and its schema description is fully covered (100%) including ISO 3166-1 alpha-2 format with IR/CN/RU examples. The prose adds nothing about the parameter, so the baseline 3 for high schema coverage 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 ('Country record from Voidly's OONI-based censorship index') and enumerates the returned signals: risk level/score, measurement count, affectedServices, active incidents, lastUpdated. It scopes itself against domain-level tools with 'not per-domain block verdicts', but never distinguishes itself from very close siblings like get_country_profile or get_country_compare.

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?

There is an implicit negative scoping hint ('not per-domain block verdicts') that tells the agent when NOT to use it, but no positive when-to-use guidance and no named alternative sibling is offered. The agent must infer the selection rules from the sibling list alone.

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=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the 0-100 scoring range, the high/medium/low band, the four derivation inputs, and the fact that it is the observatory auditing its own data — useful for interpreting the output. It does not describe return shape/pagination, but no output schema exists to constrain expectations further.

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 tight sentences: the metric and its meaning are front-loaded, with the derivation and usage tucked in after. Zero filler, and the scope ('per-country') plus scale arrive before any elaboration.

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 parameters and no output schema, the description carries the full burden, and it does explain the return value well (0-100 range, three-band label, four input dimensions) plus the intended interpretation, which is what an agent needs. Minor gaps remain — no mention of geographic coverage or staleness of the score itself — but nothing essential to invoking 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?

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to clarify. The baseline for a no-parameter tool is 4, and nothing here requires a lower score.

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 clear resource (per-country data-trustworthiness scores) with scale and band, and explains what it measures (trust in Voidly's censorship measurements) and how it is derived (freshness, volume, stability, source diversity). It reads as a distinct meta-quality metric versus sibling tools like get_data_freshness or get_measurement_freshness, though it never names an alternative, so full sibling differentiation is only implied.

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 says when to use it: 'use it to weight conclusions about sparsely-measured countries,' which is a concrete usage condition. It does not name a specific alternative tool or state exclusions, so it stops short of the when/when-not/alternatives bar required for 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds provenance context ('source receipts', 'Satellite/Hyperquack fetch success tracked by host health logs'), which is useful but references internal systems without explaining them to the agent.

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 short sentences with the subject front-loaded, which is efficient. However, the second sentence is opaque and leans on internal jargon ('Satellite/Hyperquack') whose payoff to an agent is unclear, so not every clause clearly earns its place.

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 burden of explaining what is returned. It only says to 'check the returned fields' without naming them or defining what a grade or receipt looks like, leaving the caller unable to interpret the result.

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 zero parameters, so per the rubric the baseline is 4. There are no argument semantics for the description to clarify or omit.

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 gestures at the resource ('per-country data grades and available freshness context'), but 'data grades' is ambiguous and the scope is never pinned down. It also fails to distinguish itself from close siblings like get_measurement_freshness or get_data_confidence, so an agent cannot tell which freshness tool to pick.

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?

There is no statement of when to use this tool, when not to, or which sibling to prefer. With get_measurement_freshness present in the sibling list, the absence of any routing guidance is a real gap.

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 read-only safety, so the bar is lower, and the description clears it by disclosing a significant data-quality caveat: block dates/rates/statuses may return unknown or null due to CensoredPlanet and IODA contamination, with a review object carrying the newest evidence date. That is real behavioral context beyond annotations, though it stops short of describing output shape or limits.

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, and all three sentences carry information. The middle sentence is dense but earns its length through the data-reliability caveat; minor redundancy in restating field names.

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 does the work of outlining what comes back (dates, counts, evidence window, review object). The unknown/null semantics for block fields are covered. Missing only finer return-format detail such as date formats or multi-country response shape.

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%, with both domain and country already documented and exampled in the schema, so baseline 3 applies. The description adds only the clarification that country 'focuses' one country and repeats example values, adding little beyond the schema.

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 opening clause names a specific verb-and-resource pair ('Measured history for one domain per country') and enumerates the returned fields (first/last measured dates, measured days, counts, evidence window). It clearly separates itself from siblings like get_most_blocked_domains or get_incident_evidence, though it never names an alternative tool 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 description shows how to invoke it ('Pass domain=twitter.com, optional country=IR to focus one country') but gives no explicit when-to-use or when-not-to-use guidance relative to siblings. The caveat about block dates being under review implies context, but the agent must infer when this timeline is the right call.

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 mark this readOnly and closed-world, and the description adds real value beyond them: the per-issue-day hash structure, the zero-scoring convention for missed days, and the important cryptographic caveat that a hash proves file identity, not issuance time. It also discloses what the ledger deliberately withholds (scores, alerts).

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 ledger contents are front-loaded, which is good, but the prose is elliptical ('or a missed day scored as zero alerts') and mildly redundant — 'No performance score yet' and 'alerts and scores are not disclosed' largely repeat the same disclosure. Four sentences for one optional parameter is more than strictly needed.

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 only one optional parameter, no output schema, and read-only annotations, the description carries the return-value burden well: it explains the per-day hash rows, the missed-day zero convention, and the hash's verification limits. Complete enough to call correctly, though it never says what the row structure or date range defaults look like.

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 `since` parameter is fully specified in the schema (pattern, UTC, YYYY-MM-DD, on-or-after semantics). The description merely restates the same filter semantics without adding format or edge-case detail, 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?

The description states a specific resource — a dated early-warning commitment ledger — and explains its content (per issue-day SHA-256 of the forecast file and comparison arms, or a zero-scored missed day). It is distinguishable from get_early_warning_protocol by being the commitment/hash record rather than the protocol itself, though it never names that sibling to make the contrast explicit.

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 by the content description, and there is a useful 'when-not' hint in 'No performance score yet; alerts and scores are not disclosed', which tells the agent not to reach for this tool seeking alerting or scoring. However, no alternative tool is named and no explicit condition for choosing this over the protocol or prediction-track-record siblings is given.

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=true and openWorldHint=false, so safety is covered; the description adds genuinely new context by disclosing data limitations ('no accuracy or lead-time claim', 'alerts are not disclosed') and return metadata (source_url, fetched_at, caveats). That caveat framing is exactly the kind of methodology disclosure the 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?

Two sentences, front-loaded with the resource contents before the caveats. Dense but every clause carries information; the parenthetical field list is efficient. Slightly run-on structure keeps it off a 5.

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 bears the return-value burden; it does list key fields (source_url, fetched_at, caveats) and the rule categories, which is adequate, but the exact shape of the returned protocol object remains vague and the overlap with the commitments tool is unresolved.

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 zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly avoids inventing parameter guidance.

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 the specific resource (shutdown early-warning study rules plus official notice sources) and enumerates the rule categories (issue time, horizon, alert budget, onset confirmation, decision review). It lacks an explicit verb and blurs the line with its sibling get_early_warning_commitments by also calling itself 'a commitment ledger', so it is clear but not perfectly differentiated.

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?

There is no statement of when to call this versus alternatives, even though get_early_warning_commitments and get_prediction_track_record sit right next to it. The mention of 'commitment ledger' arguably muddies rather than clarifies the routing, so an agent gets no help choosing.

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=true and openWorldHint=false. The description adds that the tool joins multiple data sources and warns that calendar dates should be verified against their source, which usefully flags potential data reliability issues. It does not mention auth or rate limits.

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 and followed by a concise verification caveat. No wasted words; each sentence contributes.

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 outlines the returned content (scheduled dates, current-regime scores, historical context) and includes a date-verification caution. This is adequate for a one-parameter read-only tool whose annotations already cover safety, though output format details remain unspecified.

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% with the single country_code parameter fully documented as an ISO 3166-1 alpha-2 code. The description adds no syntax or format details 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 it is an election-aware country briefing that joins scheduled dates, current-regime scores, and historical context. This is more specific than a generic country briefing and differentiates from get_upcoming_elections by including regime scores and history, though it does not name siblings.

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?

No explicit when-to-use or when-not-to-use guidance; the phrase 'election-aware country briefing' implies the context. It does not point to alternatives like get_upcoming_elections or country_brief. The verification note is a usage caution, not a selection guideline.

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=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it flags the endpoint as experimental and warns that scores must not be read as shutdown-onset timing, which is substantive behavioral context for an opaque risk score.

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 short sentences with no filler, and the core purpose is front-loaded. The phrasing is slightly telegraphic ('single-call experimental'), but nothing is wasted.

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 leaves the return shape entirely unspecified: no indication of what a ranking looks like, how many countries, or what fields accompany each score. For a low-complexity read tool the gap is tolerable but not filled.

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 with 100% schema description coverage ('Minimum risk filter 0-1 (default 0)'), so the schema carries the full semantics. The description adds no range, default, or filtering detail beyond that, making the baseline 3 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?

Names a specific resource (country risk ranking) and a distinct implementation trait (single-call). It stops short of differentiating from close siblings such as get_high_risk_countries or get_atlas_score, so an agent cannot route between them from the 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?

There is no when-to-use statement and no named alternative among the many risk-rating siblings. The caveat about shutdown-onset timing is a limitation on interpretation, not usage guidance, so the agent gets no basis for choosing this over get_shutdown_risk or get_high_risk_countries.

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=true and openWorldHint=false, so safety and scope are covered. The description adds one genuinely useful piece of context, that the underlying current-regime score is 'experimental', which warns the agent the metric is not production-grade, but it says nothing about ordering, result size, or freshness.

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?

One tight sentence with the filter criterion front-loaded and no filler. The parenthetical default duplicates the schema, a small redundancy, but nothing is wasted overall.

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 should indicate what a result looks like (country names only, or names plus scores?) and clarify what the 'experimental current-regime score' actually measures. Neither is provided, leaving a meaningful gap for an agent that must interpret the output.

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 threshold parameter is fully documented there, including its 0-1 range and default. The description repeats the 0.5 default and adds nothing about how the threshold is applied or what happens at boundaries, so 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 resource (countries) and the exact filter criterion (experimental current-regime score above a threshold), which is far more than a restatement of the name. It does not, however, distinguish itself from the many other risk-listing siblings such as get_shutdown_risk, get_isp_risk_index, or get_platform_risk, so the agent cannot tell which risk list it wants.

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?

There is no statement of when to use this tool rather than an alternative risk tool, nor any prerequisite or context. The only implicit guidance is the threshold itself, which does not route the agent among the crowded risk-related sibling set.

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=true and openWorldHint=false, so the safety profile is covered. The description adds value by enumerating the kind of content returned (evidence links, domains, blocking methods, timeline), which stands in for the missing output schema. It says nothing about behavior for an unknown/expired incident ID, which would be the natural next detail.

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?

One front-loaded sentence that opens with the verb and resource and then lists the payload contents. No filler, no redundancy, nothing to trim.

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 lookup with no output schema, the description adequately sketches what the caller receives. It is close to complete; the only thing missing is a note on failure behavior or whether all listed sections are always populated.

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 parameter is fully documented in the schema, including both the human-readable (IR-2026-0142) and hash ID forms. The description only refers to 'a specific incident' and adds no syntax or format detail beyond the schema, so a 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?

The description gives a specific verb ('Get') and resource ('detailed information about a specific censorship incident') and enumerates the content returned (evidence links, affected domains, blocking methods, timeline). It does not, however, differentiate this tool from close siblings like get_incident_evidence, get_incident_report, or get_incidents_since, leaving the agent to infer the distinction from names 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?

There is no explicit when-to-use statement, no prerequisites, and no mention of alternative tools for related data. The sibling set contains at least four other incident-oriented tools, so failing to route between them is a real gap rather than a minor omission.

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=true and openWorldHint=false, so the safe read-only profile is covered. The description usefully adds that the output is permalinks/raw measurements, but says nothing about pagination, count limits, or behavior when no evidence exists for an incident.

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 tight sentence that front-loads the resource and its scope, with zero filler. Size is well matched to a one-parameter read tool.

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 simple read-only tool with one required param and no output schema, the description adequately conveys what is returned (evidence permalinks). It could be more complete by indicating the return shape or empty-result behavior, but the essentials are present.

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% — the single incident_id parameter is fully documented ('Readable or hash incident ID'). The description adds no parameter-level 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 resource (evidence permalinks) scoped to one incident, and clarifies the content is 'raw measurements' — more informative than a generic 'get incident' verb. It hints at differentiation from detail/report siblings but never names them, so the agent must infer the boundary.

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 'a journalist can verify' implies a verification use case, giving implied usage. However, there is no explicit when-to-use, when-not-to-use, or routing to alternatives like get_incident_detail or get_incident_report, which is a notable gap given the many incident-related siblings.

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=true and openWorldHint=false, so the safety profile is covered. The description adds that the report is citation-formatted output, but says nothing about what the report contains, its length, or how it differs from the detail/evidence endpoints.

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 short, front-loaded sentences with zero filler. The core purpose leads and the format options follow, which is the right ordering for an agent.

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 and no annotations about content, the description should say more about what the report actually includes beyond the citation format. It is adequate for invocation but leaves the return content opaque.

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 both parameters are already documented, including the enum values and the ID format example. The description merely repeats the format options already present in the schema enum, adding no new semantics.

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 (retrieve) and resource (citable incident report) scoped to one incident. The 'citable' framing distinguishes it from get_incident_detail and get_incident_evidence, though it never names those siblings, so the differentiation must be inferred.

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 'ready to paste into an article or reference manager' implies the citation use case, which is useful context. However, it offers no explicit when-to-use vs. when-not guidance and does not name the closest alternatives like get_incident_detail.

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/openWorldHint, so the description carries the operational burden and delivers: at-least-once paging semantics with a de-duplication requirement on hashId, cursor continuation protocol, and the upstream corpus_truncated cap that makes has_more:false non-authoritative. This is exactly the behavioral context an agent cannot infer from 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-loads the core semantics (what, ordering, delta), then the pagination contract, then the truncation caveat. Every sentence changes agent behavior — none is restating the name or schema.

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 must name the response fields that drive logic, and it does: has_more, next_cursor, corpus_truncated, plus the hashId dedup key. An agent has everything needed to sync correctly and to report partial syncs honestly.

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 baseline is 3. The description still adds meaning by explaining cursor's lifecycle ('call again with cursor=<next_cursor>', from the previous response) and the role of the since boundary in delta semantics; limit's cap is left to the schema.

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+scope: incidents created OR updated after an ISO timestamp, returned oldest first as a delta sync. That framing ('delta sync', 'created or updated') distinguishes it from pure-state siblings like get_active_incidents or aggregate siblings like get_incident_stats. An agent knows exactly what this returns without opening the 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?

Gives clear conditions for continued use ('if has_more is true... call again with cursor=<next_cursor> until it is false') and a caveat about when the result is not trustworthy (corpus_truncated). It does not explicitly compare itself to alternatives like export_incidents or get_incident_detail, so it stops short of full when/when-not routing.

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 read-only and closed-world safety. The description adds real semantic context beyond them: citable_censorship excludes suspected/draft data while by_status is the complete breakdown, which tells the agent how to interpret and trust each aggregate.

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 compact sentences, front-loaded with the tool's function and followed immediately by the field interpretation guidance. Nothing is wasted and the ordering is sensible.

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 burden of explaining return values, yet it only names two fields of what is presumably a larger aggregate payload and says nothing about scope, time window, or other breakdowns. It is helpful but not complete for a zero-parameter data 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?

The tool takes zero parameters, so the baseline is 4. The description instead characterizes the returned metrics, which is a reasonable substitute for parameter discussion.

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 ("Aggregate incident statistics") and names two of the fields it returns, which distinguishes it from incident detail/listing siblings. However, it never explicitly contrasts itself with closely related tools like get_censorship_summary or get_incident_detail, so the differentiation is implicit.

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?

There is no guidance on when to call this tool versus its many siblings. It does give field-level selection guidance by recommending citable_censorship as the "honest citable headline" over the full by_status breakdown, which is useful implied usage direction, but tool-selection context is absent.

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 a real behavioral trait: the underlying source conflates CensoredPlanet rows and IODA outages with blocks, so the tool returns null rows plus a review object with verdict 'unknown' and no data date. That tells the agent exactly what a call will yield and why — high-value context that annotations do not 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?

Two sentences, no padding, but the ordering is inverted: a long run-on caveat comes before any statement of what the tool does. Leading with the review status rather than the function forces the agent to parse the warning to recover the purpose.

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 correctly takes on the burden of describing the return value (null rows plus a review object with verdict unknown), which is precisely what an agent needs before calling an effectively dead endpoint. The remaining gap is that it does not point to a working alternative for the same question.

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 parameters are already documented in the schema, including the ASN format example and ISO country codes. The description's parenthetical 'optional asn for one network' merely restates 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?

The phrase 'per-network category block rates' does identify the resource more precisely than the tool name, but there is no verb and the statement is buried inside a data-quality caveat. An agent must infer that the tool returns an ISP/ASN-level category blocking profile per country, and nothing distinguishes it from siblings like get_isp_risk_index or get_censorship_by_category.

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?

'Pass country=XX (optional asn for one network)' gives invocation guidance for both parameters. However, there is no explicit when-to-use vs. when-not, and critically no routing to an alternative even though the description itself says the tool currently produces no usable output.

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?

The description adds substantial context beyond the annotations: it discloses that the source is under review, explains why no network is ranked, states that ISP rows will be null, and notes the review object's verdict is unknown with no data date. This is exactly the behavioral transparency an agent needs for a currently unusable data source.

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 description is a single front-loaded sentence beginning with 'Under review:' and every clause adds relevant information about the status, cause, and return behavior. There is no filler or repetition.

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?

Given the simple one-parameter schema and absence of an output schema, the description is nearly complete: it explains the current return behavior and why the data is unavailable. The remaining gap is that it does not explicitly point the agent to a usable alternative, but the core calling context is covered.

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 only one parameter and schema description coverage is 100%, so the schema already fully documents country_code. The description does not add any syntax or semantic detail beyond the schema, matching the baseline for high schema 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?

The description identifies the domain (ISP block rates and composite scores) and explicitly states the current under-review behavior, but it never says plainly 'retrieves the ISP risk index for a country' and does not differentiate itself from sibling tools like get_isp_categories. An agent can infer the tool's subject, but the purpose is framed mainly as a status caveat rather than a clear action.

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 signals that the tool is under review and returns null ISP rows, which implicitly warns against relying on it, but it gives no explicit when-to-use guidance or alternative sibling tool to call instead. The agent is left to infer whether to skip this tool entirely or still call it for the review object.

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=true and openWorldHint=false, so safety profile is covered. Description adds the four-band taxonomy (live/recent/aging/stale) and the map/list shape, which is useful context beyond annotations. Does not enumerate what other stale-related tools return or rate limits, but the band semantics are the key behavioral detail.

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 compact sentences, front-loaded with the core output spec ('last-measurement timestamp + band') then the use-case. Every clause earns its place; no repetition of the title.

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?

Zero-param, read-only, no-output-schema tool; description covers output content and purpose adequately. Slightly incomplete on the exact map key/value format and band thresholds, but the agent has enough to call and interpret 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?

Zero parameters, so baseline is 4. No parameter semantics to document, and the description correctly confines itself to describing output rather than fabricating inputs.

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 ('get_measurement_freshness') and crisply defines the output: last-measurement timestamp plus a four-band freshness label across all monitored countries. Distinguishes itself from siblings like get_data_freshness and get_data_confidence by scoping to per-country measurement recency.

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?

Explicit when-to-use: 'to check whether a country's censorship data is current before relying on it.' Tells the agent how to act on the result (find the country in the returned map). No explicit exclusions or named alternatives, but the context is 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?

This is the description's strongest contribution: it discloses that the call returns null domains plus a review object, and that the review's data date is the layer's window end. That prevents an agent from misreading a null result as an error or as an empty result. The reason for withholding (false positives in open countries, stricter rule being rebuilt) adds useful trust context beyond the readOnly/openWorld 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 critical state ('Under review') is front-loaded, and the rest explains cause and effect in two compact sentences with no filler. The middle clause about false positives in open countries is slightly dense but earns its place as justification.

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 does the right thing by describing the actual return shape (null domains + review object + data date). What's missing is what an agent should do instead to obtain a comparable ranking, and whether a limit/category call has any effect while withheld. Adequate but with a clear routing gap for a tool that currently returns nothing.

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 both parameters (limit, category) are documented in the schema. The description adds no parameter-level information, such as whether limit or category still apply given the withheld state. Baseline 3 applies when the schema carries the parameter burden.

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 the specific resource and metric: a global ranking of domains by how many countries block them nationally, sourced from Voidly's national blocklist layer. It also states the tool is currently withheld, which is the essential fact about what it returns. It doesn't explicitly contrast with near-siblings like get_most_censored or get_national_blocklist, keeping it short of a 5.

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?

Implicit guidance comes from 'the ranking is withheld', which tells an agent not to call this expecting usable domain data, and the 'under review' framing implies deferring to another tool. However, no alternative is named for getting blocked-domain rankings and no condition for when calling is still worthwhile (e.g. to check review status) is stated.

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=true and openWorldHint=false, so the safety and scope profile is covered. The description adds the return shape (country, score, risk tier, blocked categories), which is useful, but says nothing about ordering direction, ties, or how much data is available beyond the limit. Adequate but thin for the annotation-lowered bar.

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, zero waste, front-loaded with the purpose before the return fields. Nothing is padded or 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?

There is no output schema, and the description compensates by naming the returned fields, which is the key missing piece. For a simple read-only leaderboard with one documented parameter, this is nearly complete; only the sibling disambiguation is absent.

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 single 'limit' parameter has 100% schema description coverage including default and max, so the schema carries the semantics. The description adds nothing about the parameter (no mention of the cap, defaults, or effect of limit on ranking), 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 ('Get') and resource ('most censored countries') with the ranking criterion ('censorship severity score') and enumerates the returned fields. It is clear on its own, but it does not differentiate itself from close siblings such as get_high_risk_countries or get_censorship_index, which an agent could easily confuse it with.

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?

There is no when-to-use guidance, no statement of when-not-to-use it, and no pointer to an alternative among the many sibling ranking/risk tools. The agent is left to infer that this is a global leaderboard view rather than a per-country lookup.

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?

With readOnlyHint=true already covering the safety profile, the description adds genuinely useful behavioral context: the tool is experimental and probability intervals are deliberately withheld pending validation. That tells the agent to expect incomplete output and not to treat the scores as calibrated probabilities.

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 tight sentences with no filler, leading with the scope (1/7/30-day country scores) and immediately following with the output caveat. Every clause carries 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, single-parameter tool with no output schema, the description covers both what is returned (scores plus SHAP features per horizon) and a key output limitation (intervals withheld). It could say more about what a 'score' represents, but nothing essential for calling the tool 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% and the single parameter (country_code) is fully documented in the schema with an ISO format and examples. The description adds no syntax or format detail beyond that, so the baseline of 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 resource (country scores) with explicit horizons (1/7/30-day) and a distinctive payload detail (per-horizon SHAP top features), which sets it apart from generic getters. However, it never contrasts itself with close siblings such as get_risk_forecast or get_shutdown_risk, so an agent must infer the distinction.

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?

There is no explicit when-to-use, when-not-to-use, or alternative tool guidance. The word 'Experimental' and the withheld-intervals note hint at caution, but the description does not tell the agent when to prefer this over get_risk_forecast or get_prediction_track_record.

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 give readOnlyHint and openWorldHint; the description adds substantial non-redundant behavior: the layer failed against false positives in open countries and is being rebuilt, so nothing is ever returned as blocked. It discloses the response shape (review object with reason, data date equal to the layer's window end, plus confirmed_block_layer window and per-country measured-domain coverage) — information the annotations and schema do not carry at all.

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 under-review status is front-loaded, which is the single most important fact, and each sentence contributes (status, return shape, interpretive warning, alternative). It is denser than necessary — the 'open countries / stricter rule' backstory and the 'Voidly's' branding could be trimmed without loss.

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 must carry the return values, and it does: review object fields, the layer window, and coverage. It also preempts the natural misinterpretation of an empty blocklist. For a single-parameter read tool in a degraded state, nothing material 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 'country' parameter is already documented in the schema with an ISO 3166-1 example. The description adds nothing about the parameter (e.g. whether unsupported countries error or degrade to unknown), so it meets but does not exceed the baseline.

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 the resource (national blocklist layer) and states the current outcome precisely: it lists no domain as blocked and answers 'verdict unknown'. That is an unusual but genuine statement of purpose; a reader knows exactly what this call returns and why. It is not quite a 5 because the operative verb is negated ('lists no domain as blocked'), so the tool's positive function has to be inferred.

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 explicitly routes the agent away from this tool for citable censorship events: 'For citable censorship events use get_active_incidents.' It also gives an interpretive rule ('absence from any list is not evidence of access'), which prevents misuse. It stops short of saying when the tool IS worth calling (e.g. only to surface the review/reason metadata).

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 (readOnlyHint, openWorldHint=false), and the description adds genuinely useful interpretive behavior: coverage depth is explicitly NOT a censorship score, and an absent/shallow country means under-measured, not unblocked. It also tells the agent to read current coverage from the response, which matters given there is no output schema.

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 definition, then the interpretive caveat, then the parameter hint — a sensible ordering with no filler sentences. It is slightly dense and the gating-gate clause could be tightened, but each sentence carries 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?

No output schema exists, and the description compensates by explaining what the metric means and instructing the agent to read current coverage from the response. It could go further on the shape of the returned coverage values, but for a single-optional-param read tool the essentials are present.

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% for the single country parameter, so the baseline is 3. The description adds meaning beyond the schema by stating that passing country=XX scopes to one country, implying the omitted case returns all countries' coverage — a default behavior the schema does not document.

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 (per-country measurement depth) and defines it concretely as 'how many distinct ISP networks (ASNs) Voidly has evidence from', including what it bounds (the >=3-network confirmed-block gate). It also explicitly distinguishes the metric from censorship scores, so an agent can separate it from siblings like get_censorship_index or get_atlas_score.

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 gives an implied usage ('read current coverage', 'pass country=XX for one country') but never states when to reach for this tool versus adjacent measurement-quality tools such as get_data_confidence, get_measurement_freshness, or get_category_coverage. The condition that selects it over alternatives is left to inference.

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?

Far beyond the annotations, the description discloses the concrete return shape (null platforms plus a review object), the reason the data is voided (CensoredPlanet rows and IODA outages no longer count as block evidence), and residual caveats (verdict unknown, source reports no data date). For a zero-parameter stub this is exactly the behavioral context an agent needs to avoid misreading an empty response as 'no censorship found'.

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, none wasted: the reason for the degraded state comes first, then what is actually returned, then the redirect. The opening clause is dense with internal specifics (CensoredPlanet, IODA, Voidly) but those details justify the null result rather than decorate 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 carries the burden of describing returns — and it does, naming the null platforms and the review object's fields. Combined with the redirect to get_active_incidents, an agent has everything needed to call it correctly or avoid it. Minor gap: it doesn't say whether this state is temporary or when the review concludes.

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 (schema coverage 100%), so the baseline is 4. Nothing in the description contradicts or adds ambiguity to the empty schema.

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 conveys the resource (per-platform block rates / platform scores) and, unusually, its current degraded state: it returns null platforms and a review object rather than rankings. It also names the sibling that should be used for the real need (get_active_incidents). It loses a point only because the operative purpose is buried behind the 'Under review' framing, so an agent skimming the first clause may not immediately register that this tool is a stub.

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?

There is an explicit, actionable alternative: 'For citable censorship events use get_active_incidents.' The condition that makes this tool useless (the source no longer accepts those rows as block evidence) is also stated. What's missing is a direct instruction like 'do not call this tool for rankings' — it is strongly implied rather than stated.

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 readOnlyHint and openWorldHint, so the safety profile is known. Beyond that, the description adds genuinely valuable context: the score is experimental, derives from historical OONI plus calendar inputs, and has no demonstrated skill at onset timing, with a pointer to the skill endpoint. Return format is not described, but no output schema exists and the limitation disclosure is unusually candid.

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 tight sentences, zero filler, and the most decision-relevant fact (experimental, 7-day, current-regime) is front-loaded ahead of the caveat. Nothing to trim.

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-only tool with no output schema, the description covers inputs, method, horizon, and a crucial reliability caveat, which is close to sufficient. The one gap is that it does not position itself against the dense set of sibling forecast/risk tools.

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 there is a single required country_code parameter with an example-bearing description, so the schema carries full parameter semantics. The description only implies country-level scoping; it adds no format or syntax detail beyond the schema. 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 with scope: '7-day current-regime risk score' derived from 'historical OONI and calendar inputs', plus an experimental caveat. It is clear what the tool returns, but it does not name the close siblings (get_shutdown_risk, get_multi_horizon_forecast), so an agent must infer the distinction from the 7-day framing 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 description gives one implicit usage constraint ('no demonstrated skill at timing new shutdown onsets'), which steers agents away from using it for onset prediction. However, it never states when to choose this over the many sibling risk/forecast tools, so the when-to-use guidance is only implied.

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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation context: the score is 'experimental', within-country onset timing is 'unproven', and the agent should read the info endpoint and response caveats before trusting results.

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 tightly written sentences with the core action front-loaded followed by the reliability caveat; nothing is wasted. Slightly terse, but every sentence earns its place.

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 no output schema, the description covers the caveat caveat-routing and reliability warning adequately. It could say more about return shape or comparison to sibling shutdown-risk tools, but nothing essential 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 coverage is 100% and the single ISO 3166-1 alpha-2 parameter is fully documented in the schema itself. The description adds no format or semantics beyond that, so the baseline of 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 and resource ('Get ... country shutdown-risk score') scoped to a country, which separates it from the many get_* siblings at a glance. It does not, however, distinguish itself from close siblings like get_shutdown_risk_accountability or get_shutdown_risk_leaderboard, so it stops short of a 5.

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 context is implied (fetch a country's shutdown-risk score) and it points the agent at the /v1/shutdown-risk/info endpoint for caveats. But there is no explicit when-to-use/when-not guidance relative to the accountability or leaderboard variants, so this is minimum viable.

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, closed-world safety profile, and the description adds genuinely non-obvious context: the predictions are unscored, precision and recall are null, and evaluation limits are embedded in the response. That is real disclosure an agent could not get from annotations. It stops short of describing what the joined archive actually contains row-by-row.

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 short sentences with no filler, and the key caveat (unscored predictions, null precision/recall) is placed before the pointer to the response's evaluation limits. Slightly repetitive in restating the 'no model skill' point twice.

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 burden of explaining returns; it only gestures at 'evaluation limits' without saying what fields the archive exposes (score, outcome, null metrics). For a no-argument archival tool this is adequate but leaves the agent guessing about payload shape.

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 zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4. The schema coverage is also 100%, so no compensating detail is required.

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 and framing: a 'retrospective archive of shutdown-risk scores joined to recorded outcomes', which tells an agent this is an outcome-joined historical dataset rather than a live risk score. It never names its obvious siblings (get_shutdown_risk, get_shutdown_risk_leaderboard), so the distinction is inferable but not explicit.

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: the archive is for accountability against recorded outcomes, and the warning that it 'supports no claim of model skill' implies it should not be used for validation claims. There is no explicit when-to-use or when-to-prefer-get_shutdown_risk 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?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description nonetheless adds a genuinely useful epistemic caveat that no structured field carries: the score bands have no proven shutdown-onset timing skill. That is exactly the kind of context an agent needs to avoid over-claiming predictive power.

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 caveat. Every clause carries information; nothing is filler or restated from the name.

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 params, no output schema, and read-only annotations, the description supplies the essentials: the population, the sort key, the columns, and a critical limitation. It could still mention sorting direction or the score's scale, but it is adequate for this simple enumeration 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond the implicit no-argument, global-scope behavior.

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 ('All scored countries') and ordering ('sorted by experimental model score') plus the payload contents (bands, as-of dates). It does not explicitly distinguish itself from close siblings such as get_shutdown_risk or get_high_risk_countries, so it lands at 4 rather than 5.

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?

There is no when-to-use guidance, no mention of the sibling tools it overlaps with (get_shutdown_risk, get_high_risk_countries, get_shutdown_risk_accountability), and no stated exclusions. Usage must be inferred entirely from the ranking semantics.

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=true and openWorldHint=false, so safety is covered. The description adds that results carry a censorship-risk overlay, which is real context beyond the annotations, but says nothing about pagination, coverage, or data freshness.

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 tight sentence, front-loaded with the resource and scoping. No filler.

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 one-parameter tool with annotations covering safety, the description is nearly sufficient, but it leaves 'censorship-risk overlay' undefined and does not clarify the boundary with the sibling get_election_risk.

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 'days' parameter is fully documented in the schema with its default. The description adds nothing about the lookahead window, so 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 concrete verb+resource ('upcoming elections') with worldwide scope and names the value-add ('censorship-risk overlay'). It is discernible from most siblings, though the closely related get_election_risk is not distinguished.

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?

No indication of when to use this versus alternatives such as get_election_risk or get_risk_forecast, and no prerequisites or exclusions. The agent must infer usage entirely.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns dated public examples, includes no-auth example calls, and falls back to a static guide if a source is slow.

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 description is two tight sentences, front-loaded with 'Start here' and then listing the return contents and fallback behavior. Every clause carries useful information with no filler.

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 parameters and no output schema, the description should explain the return shape, which it does by listing index summary, newest citable incidents, one country answer, next calls, and three no-auth examples. The fallback behavior is also stated, making it sufficiently complete for 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?

There are zero parameters, so the baseline is 4 and the description does not need to explain parameter meanings. It appropriately focuses on what the tool returns instead.

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 clearly states that this is an onboarding/example tool: it returns a live dated example with index summary, newest citable incidents, one country answer, next calls, and three no-auth example calls. The purpose is concrete, though it does not explicitly contrast itself with specific sibling 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?

The phrase 'Start here' explicitly indicates first use, and the mention of 'next calls to make' plus no-auth example calls gives follow-up guidance. It does not state when not to use the tool or name alternatives, but the onboarding context is 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?

Annotations already declare the safety profile (readOnly, non-destructive, non-idempotent), and the description adds substantial context beyond them: the exact Ed25519 signing protocol, that the signature is over LF-joined fields including SHA-256 of exact raw_body, that results carry resource identities, and that after_seq must be advanced to next_seq. This is real invocation-critical behavior. It stops short of describing rate limits or error/auth-failure behavior.

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 in the first sentence, but the signing instructions are a single telegraphic, comma-run clause ('Locally Ed25519-sign LF-joined voidly-alerts-v1, POST, /v1/agent/alerts/poll, DID...') that is hard to parse and would benefit from clearer sentence structure. Nothing is wasted, but readability suffers.

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 describe the return value; it only says 'Results contain resource identities' and to advance after_seq to next_seq, leaving the response shape thin. Invocation mechanics are well covered, but an agent cannot fully anticipate the returned payload.

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 carries the burden and largely does: it names all five parameters and explains their roles (DID, Unix timestamp, nonce, signature, raw_body) plus how the signature is computed from them. It omits format details (which the schema patterns cover) and any per-field constraint notes, but the core semantics of the signing inputs are conveyed.

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: 'Poll one owned board or matching-job subscription.' An agent can tell this consumes an existing subscription rather than creating one, and the closing sentence distinguishes it from setup/mutation operations. It does not, however, differentiate itself from the adjacent voidly_trigger_poll sibling.

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 final sentence ('Create, pause, delete and webhook setup use the direct API') gives a partial when-not rule by excluding lifecycle operations, implying this tool is poll-only. There is no explicit guidance on when to prefer this over voidly_trigger_poll or board_read, so usage is inferred rather than stated.

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 establish read-only, non-destructive, closed-world behavior. The description adds meaningful policy context beyond that: only open/unexpired bounties are returned, claimed/finished ones are omitted, and listed bounties are explicitly unpaid with owner-run off-platform payout.

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 compact sentences, with the listing scope and exclusions front-loaded. The payout caveat is the only extra detail and is directly relevant to interpreting results.

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 adequately explains what the list contains, what it excludes, and the non-paying nature of listings. It does not describe ordering or pagination, but for a zero-parameter read-only list tool the essential context is present.

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 zero parameters, so there is nothing for the description to clarify beyond the schema. The baseline score for a parameterless tool 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 (List) and resource (owner-posted work bounties), and sharply scopes it to open, unexpired, unclaimed items. The explicit exclusions (claimed or finished bounties are not listed) make it distinguishable from siblings like voidly_bounty_status and voidly_bounty_claim without reading schemas.

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 listing filter clearly implies when to use this tool: browsing available work before claiming or checking status. It does not explicitly name alternatives such as voidly_bounty_status or voidly_bounty_claim, but the scope is clear enough for an agent to choose correctly.

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 declare destructiveHint=true and readOnlyHint=false, but the description adds real context beyond them: signing must happen locally, the exact signed JSON must be forwarded, the idempotency key must be included, and critically that 'claiming does not make it payable or paid.' That last point clarifies the side effect so the agent does not expect payment, which is valuable given the destructiveHint.

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 no filler, front-loading the core action before the signing mechanics and the side-effect caveat. Efficient, though the flow could be marginally clearer about which fields the agent supplies versus signs.

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 cryptographic, 6-parameter mutation tool with no output schema and 0% schema coverage, the description gives the high-level signing flow but omits parameter-level detail and any notion of the response. Adequately describes the mechanics but not complete enough to call the tool correctly without external knowledge.

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% with 6 required parameters, so the description bears full burden. It hints at the idempotency key (likely mapping to the undocumented nonce) and the notion of a signed body, but nothing explains did, timestamp, signature, or bounty_id beyond what their names imply. Most parameter meaning is left unexplained.

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 verb and resource: 'Forward exact caller-signed JSON to claim one bounty.' An agent can distinguish claiming from reading (voidly_bounty_status) or submitting. However, it does not explicitly differentiate from the closely named voidly_bounty_submit sibling, leaving that boundary to inference.

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?

There is no explicit when-to-use guidance. The description never routes the agent to voidly_bounty_status (to check claimability) or distinguishes claiming from voidly_bounty_submit. It implies a claim action but gives no conditions or prerequisites for selecting this tool over its siblings.

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 establish readOnly/destructive=false/openWorld=false, and the description adds real value beyond them: it discloses that the call requires a locally signed proof (auth requirement) and clarifies lifecycle semantics ('Owner acceptance remains unpaid; payout is owner-run and off'). That off-platform payout note is non-obvious and prevents wrong assumptions.

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 compact sentences, front-loaded with the core action and auth mode. The payout sentence is tangential to invocation but short and informative, so little is wasted.

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, auth-gated tool with no output schema, the description covers the auth mode and payout semantics but omits what the status response contains and how the five signing parameters relate. Adequate but leaves real gaps an agent would face at call time.

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% across 5 required params, so the description carries the full burden, and it largely does not meet it. The phrase 'locally signed GET ... proof' hints that did/nonce/timestamp/signature form a signed auth envelope, but it never explains how to construct or order those values, and says nothing about bounty_id usage.

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: reading bounty status, and distinguishes two audience views (claimant vs posting operator). It is separable from siblings like voidly_bounties and voidly_bounty_claim, though the phrase 'claimant or posting operator view' could be sharper about which status fields are returned.

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?

No explicit when-to-use or when-not guidance relative to siblings such as voidly_bounties, voidly_bounty_claim, or voidly_bounty_submit. The claimant/operator framing implies an audience but does not tell an agent which tool to pick in a given situation.

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 destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the write-oriented safety profile is covered. The description adds real value beyond that: it notes the caller must supply signed JSON (the tool does not sign), that an idempotency key is involved, and that payment/acceptance happens elsewhere – none of which the annotations convey.

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 core action and endpoint, with the exclusion about acceptance/payment following. Dense and largely waste-free, though the second sentence packs several distinct constraints into one 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?

For a six-param tool with 0% schema description coverage and no output schema, the description covers the write semantics and non-goals well but leaves parameter-level meaning incomplete (notably the signing fields and bounty_id). It is adequate at the operation level but thin 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 description coverage is 0%, so the description must compensate for six required params. It hints at caller-signing (implying did/nonce/signature/timestamp) and mentions an idempotency key and result text buried inside raw_body, but never explains the meaning or format of did, nonce, signature, timestamp, or bounty_id. Most parameters remain semantically undocumented.

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 verb and resource ('Forward ... to POST /v1/bounties/{id}/submit') and scopes it as submitting bounty work, which distinguishes it from sibling tools like voidly_bounty_claim and voidly_bounty_status. It does not explicitly name those siblings, but the action is concrete enough to identify the tool.

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 clarifies scope boundaries ('Owner acceptance is separate and unpaid; this tool does not sign or pay'), which implies when this tool applies versus downstream steps. However, it never states when to use this versus voidly_bounty_claim or voidly_bounty_status, so routing relies on inference.

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=true and destructiveHint=false, so safety is covered. The description adds useful context beyond that: it is public, has no payment/action side effects, and is 'versioned' (implying content may change over time). Missing only return-shape or frequency details.

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 tight sentences with zero waste; the core purpose and the 'no action/payment' caveat are both front-loaded and easy to scan.

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 no-parameter read tool with no output schema, the description pre-summarizes the manifest's sections and disclaims side effects, giving an agent everything needed to decide whether to call it.

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?

Zero parameters with 100% schema coverage, so the baseline is 4. There is nothing for the description to clarify on the parameter front, and it correctly doesn't invent any.

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 ('Read') and resource ('versioned Voidly agent capability manifest'), then enumerates exactly what the manifest contains (endpoints, auth, price basis, examples, availability). This is clearly distinguishable from siblings like voidly_home, voidly_join, or voidly_bounties.

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 clause 'performs no action or payment' implies this is a discovery/introspection step, so usage is implied. However, it never explicitly says when to call this versus alternatives, nor that it should be consulted before invoking action endpoints.

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 the safe read-only profile, and the description adds material context beyond them: a per-call fresh four-header proof requirement (auth), the explicit trust boundary that board/job/listing text is untrusted, and the guarantee that no action or payment is performed. This is exactly the extra disclosure the 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?

Three dense sentences, front-loaded with identity and contents before the auth and trust caveats. Every clause carries distinct information (contents, prerequisite, safety), though the enumeration of payload items is on the edge of a run-on list.

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 parameters and no output schema, the description must carry the return-side and safety burden, and it does: it enumerates the snapshot contents, states the auth requirement, and flags the trust boundary and no-action guarantee. Nothing an agent needs to call 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?

The tool takes zero parameters, so per the baseline there is nothing for the description to compensate for. The schema is closed (additionalProperties: false) and coverage is 100%; the description correctly focuses on inputs external to the schema (the header proof) rather than parameters.

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 ('Read') and resource ('signed private Agent Home snapshot'), then enumerates the payload (identity, board handle, posts, jobs/bids, Relay unread count, Pay pointers). This detailed scope distinguishes it from siblings like agent_relay_stats or voidly_capabilities 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?

Usage is implied (fetch your personal dashboard snapshot) and a hard prerequisite is stated ('Requires a fresh caller-local four-header proof for each call'). However, it never says when to prefer this over voidly_capabilities, agent_relay_stats, or the individual board/job tools, leaving alternative selection to inference.

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