Palimpsest — censorship, China economy and model-eval observatory

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

Annotations already establish the safe read-only/idempotent profile, so the description earns credit by adding genuinely non-obvious behavior: the economy, machine-analysis and interconnection views are metadata-only until a lineage-filtered rebuild removes denied derivatives, and 'availability never implies publication readiness' with statuses, gates, counterevidence, limitations and right-to-reply state remaining attached. Those are real constraints an agent could not infer from the schema. It stops short of describing return shape or how the limit interacts with 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?

Front-loading the view list is the right structure and the second sentence carries real caveat value, but the definition is a single dense paragraph of stacked jargon ('named-key fat-object joins', 'topic-surface-only', 'denied derivatives') that an agent must parse as one unbroken clause chain. The content earns its place; the packaging does not.

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 four-parameter, no-output-schema, read-only tool, the description covers the decisive question (which view to read and what restrictions apply) and flags the gating semantics an agent must not misreport. The shortfall is moderate: status/priority filtering behavior and limit/pagination semantics are left entirely to the schema, and no indication of what a returned story or dossier contains.

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 only 50% schema coverage, the description compensates well where it matters most: every one of the seven 'view' enum values is given meaning beyond its bare name, which the schema does not do. However, it says nothing about 'limit' (default 10, max 50) or about how 'status' and 'priority' apply per view beyond the terse schema descriptions, so two of four parameters remain unenriched.

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 one evidence-first reporting surface') and then enumerates all seven views with a one-clause characterization of each, so an agent can tell 'wire' from 'investigations' from 'editorial-readiness' immediately. The remaining gap is that neither the resource nor the views are related to any sibling (get_signal, whats_happening, research_catalog), and the framing language ('evidence-first reporting surface', 'named-key fat-object joins') is domain jargon that doesn't map cleanly to a plain noun.

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 directed: 'without scraping a page or guessing a filename' hints at when this replaces file/page access, and the per-view glosses let an agent pick a view. But there is no explicit when-not guidance, no statement of how this differs from get_signal, list_signals or whats_happening, and no prerequisites or sequencing advice.

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, closed-world behavior, so the description rightly focuses on what annotations cannot convey: denied-lineage signals return restricted/unavailable rights metadata with no values, and row caps are reported with the true total rather than applied silently. It stops short of describing invalid-name errors or response shape, keeping it below a 5.

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 opening sentence is front-loaded and the rest is routing information rather than filler, but the description is dense and runs long for a two-parameter read tool. Most sentences earn their place, though the eval-side enumeration is heavy.

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 useful work describing return values: bounded latest payloads, restricted rights metadata, the eval ledger's verified flag and Merkle root, and a bounded GFI matrix view. It leaves out error behavior for unknown names, which keeps it from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds real semantic value by explaining what the signal names mean in context ('eval-registry' returns the hash-chained eval ledger, 'gfi-transcripts' the bounded GFI matrix, 'refusal-drift' the current refusal reading) and by tying max_rows to non-silent truncation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read one named signal') and immediately distinguishes itself from gfw_reading and list_signals. It explains what permitted versus restricted signals return, so the agent knows exactly what this tool yields.

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 to call list_signals first for valid names, names the eval-side entries and their intended use, and tells the agent to read eval-assurance before making validity claims and eval-journal/eval-findings for supporting evidence. It also names gfw_reading as the alternative for merged firewall views.

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, closed-world, so the safety profile is covered. The description adds substantive behavioral context the annotations cannot: the data is a join of live in-China OONI measurement and an index over Chinese LLMs, and it is a derived convenience aggregation rather than raw payload. It stops short of stating freshness/caching or what happens if one layer is unavailable.

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 scope, then the no-arg fact, then the escape hatch to get_signal. Every sentence carries distinct information with no restatement of the title or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-argument composite read with no output schema, the description tells the agent what content to expect (two joined layers) and where to get raw single-layer data instead. It leaves return shape and freshness unstated, which is a minor gap given no output schema exists to cover them.

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 the baseline is 4; the description reinforces this with 'Takes no arguments', removing any ambiguity about needing filters. No further parameter meaning is possible or needed.

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 ('the Great Firewall's current state at both layers'), then enumerates exactly which two layers: live OONI network blocking measured inside China and model-layer censorship from the Generative Firewall Index. It also names what it is not — a single-layer view — routing to get_signal.

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 'Takes no arguments' and frames itself as 'A combined convenience view', then names the alternative path: 'for one layer's full raw payload use get_signal with ooni-gfw or generative-firewall-index'. That is a clear when-versus-when-not with the exact sibling and argument values.

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, closed-world, non-destructive), it discloses what the call will NOT touch or return and fixes the semantics of a denial. That negative scoping and interpretation rule are exactly the context annotations cannot convey and prevent a costly misreading of the output.

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: returns first, boundaries second, interpretive caveat last. No filler and nothing that repeats the schema or annotations verbatim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so by naming each returned element. For a zero-argument, read-only metadata tool it supplies everything an agent needs to call and interpret 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-parameter tool, so the baseline is 4; the description reinforces this with 'Takes no arguments,' which matches the empty, additionalProperties:false schema. Nothing further is needed.

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?

Specific verb plus resource: 'Inspect publication-rights metadata for China economic evidence,' and it enumerates the returned artifacts (policy digest, UTC evaluation clocks, per-source decisions, published-record status). The negation clause ('never reads or returns observation rows, derived signals or replacement values') distinguishes it from data-fetching siblings such as get_signal and list_signals.

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 clear: this is the metadata/preflight check rather than a data read, and the 'denied decision is a restriction, not a zero observation' line guides interpretation. However, it never names an alternative tool or states an explicit 'use this before/after X' condition, so routing is inferred rather than prescribed.

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 readOnly/idempotent/non-destructive/closed-world, so the description correctly spends its words elsewhere: "no denied values are returned" and "metadata-only rights status" disclose a redaction policy the agent could not infer from structured fields. It does not describe result size or pagination for a catalog-style listing, which keeps it off a 5.

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 first sentence and the final instruction earn their place, but the middle is a dense marketing catalog of domain jargon (hash-chained, Merkle-rooted, assurance ceiling, Generative Firewall Index) that an agent cannot act on when calling a zero-argument list tool. Over half the text is signal-name decoration rather than invocation 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?

With no output schema, the description usefully states the return shape (name, description, source URL) so the agent knows what a list entry looks like. Combined with the annotations and the get_signal handoff, an agent has enough to call it correctly on the first attempt.

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 the baseline applies; "Takes no arguments" explicitly closes the question of whether filtering is possible. Nothing further is needed given the schema is an empty object with additionalProperties false.

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?

Opens with a specific verb and resource ("List every published signal Palimpsest exposes") and immediately states what each entry contains: name, one-line description, source URL. The three-application breakdown plus the closing pointer to get_signal makes it unambiguous which sibling this is not.

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?

"Call this first to discover signal names, then get_signal for one full reading" gives an explicit ordering rule and names the drill-down alternative. It stops short of saying when to prefer research_catalog or whats_happening instead, so it is strong but not fully exhaustive.

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 and closed-world, so safety is covered. The description adds real context — results are paginated metadata retaining source clocks, rights and access states, and Seiche values are not copied — but it omits practical traits like total counts, page traversal behavior, or what an empty page means. The phrase "external trade" sits slightly awkwardly against openWorldHint=false but does not clearly contradict it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core capability, with no obvious filler. However, the final sentence about the Seiche research_network handoff is dense and ambiguous — it is unclear whether the tool returns a pointer, an embedded summary, or nothing at all.

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 parameter documentation, the description must carry more weight than it does. It establishes what metadata fields come back and that values are not duplicated from Seiche, but an agent still lacks the return shape and paging semantics needed to consume results confidently.

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% for the two parameters, and the schema only carries types, defaults and bounds. The single word "Paginated" implies limit/offset exist but gives no guidance on sensible page sizes, the 25 max, or the 1000 offset ceiling, so the description does little to compensate.

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?

Uses a specific verb ("Discover") with a clear resource ("every Palimpsest dataset") and enumerates the catalog's coverage areas, so an agent knows this is the broad catalog-listing entry point. It does not explicitly contrast itself with siblings such as get_newsroom or gfw_reading, but the catalog framing is distinct enough to infer the split.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says what the catalog contains but never states when to reach for it versus alternatives like inspect_economic_publication_rights or get_signal. The Seiche "handoff" sentence hints that follow-up context lives elsewhere, yet no condition or routing rule 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 readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds real interpretive context beyond that: false-discovery control for multiplicity, coverage confounds flagged as artifacts rather than findings, and explicit no-argument behavior. It stops short of describing the verdict's shape or any latency/caching behavior, keeping it at a 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 action and follows with routing and scope in three tight sentences; every clause carries decision-relevant information. Some statistical jargon ('multiplicity paid for', 'coverage confounds') is dense but purposeful rather than 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?

No output schema exists, so the description must signal the return nature, and it does by describing an FDR-controlled verdict with confounds flagged as artifacts. Combined with annotations covering the safety profile and the explicit sibling routing, an agent has enough to call it correctly, though the exact verdict structure remains 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?

The tool takes zero parameters, so the baseline is 4, and the description confirms this with 'Takes no arguments', removing any ambiguity about whether scope/date filters exist. There is no further parameter meaning to add.

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 ('Judge whether anything is happening') and resource ('Chinese censorship', 'across every signal at once'), and the title/description pair distinguishes it from the per-signal siblings. An agent can identify this as the aggregate verdict tool without opening any 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 says 'Use this instead of fetching signals individually', then sequences the workflow ('then use get_signal to drill into whichever signal moved'). The scope note also names the specific eval-side signals ('eval-registry', 'eval-assurance', 'refusal-drift') to route elsewhere, so alternatives and exclusions are both covered.

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