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

With no annotations supplied, the description does real work: it declares read-only behavior, explains the trust-weighted distinct-source diversity × recency ranking, and states that dismissal is out of scope. It does not cover auth, rate limits, or what capping means operationally, so it is strong but not exhaustive.

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 purpose and read-only constraint, then uses explicit Args and Returns sections. It is slightly verbose around the 'hearsay vs. primary source' framing, but every section is useful and nothing is buried.

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

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

For a two-optional-parameter read-only query tool with an output schema, the description supplies the selection semantics, defaults, scope limitation, and return shape. An agent has enough information to call it correctly without external docs.

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, and it does: limit is 'maximum suggestions to return' with a named default ('citation_signal.rank_cap'), and min_sources is a distinct-citing-source threshold with its own config default. The parameter meanings are clear even though the config keys themselves are not expanded.

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 ('rank undeposited URLs the corpus frequently cites') and characterizes the target set as primary sources cited but never deposited. This is clearly distinct from generic link suggestions and from the sibling links_suggest 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?

Explicitly frames the read-only half of a workflow and says the dismiss half lives on the CLI/HTTP API, which tells the agent this tool cannot complete the full loop. It does not explicitly contrast with the sibling links_suggest, so it falls short of a 5.

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

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

With no annotations, the description carries the full load; it does disclose the returned components (header, refs, payload), which is real behavioral context. It does not state that the operation is read-only, what happens when event_id is unknown, or any access constraints.

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 short and front-loads the purpose in the first sentence. The "Args:" block is redundant against the schema 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?

An output schema exists, so return values need not be explained further, and for a single-record fetch the description is close to sufficient. It still leaves the source of the event_id and error behavior unaddressed.

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, but "event_id: The event's id." is a tautology that adds nothing. It omits where an id comes from (presumably events_list) or any format expectation.

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 ("Show one operator event") and enumerates the returned sections (header, refs, payload), which distinguishes it from a bulk list operation. It never names the sibling events_list, so the differentiation is implied by "one" rather than 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?

There is no explicit when-to-use or when-not-to-use guidance, and the obvious alternative (events_list) is never referenced. The agent must infer that this is the detail-fetch counterpart to the list tool.

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

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

No annotations exist, so the description carries the full behavior burden. It usefully discloses ordering (newest first), the default limit of 50, and the mutual-exclusivity constraint on the three filter ids, but says nothing about whether limit is capped, how to page past 50 results, or what happens with zero matches.

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 one-line summary followed by a compact Args block; every line carries information. The docstring formatting is slightly heavy for a tool description but 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?

An output schema exists so return values need not be explained, and all five parameters are documented. What is missing is paging behavior: with a limit default of 50 and no offset/cursor documented, an agent cannot tell how to retrieve further events, nor whether events feed into event_show by id.

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 and mostly does: it defines all five parameters, explains the 'touching this id' semantics of the three filter ids, and gives concrete event_type examples (SOURCE_RETRACTED, SUBJECTS_SPLIT, TRUST_CHANGED, REVIEW_RESOLVED). It stops short of saying what form the ids take or listing the complete set of event types.

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 ('List operator events') plus ordering ('newest first') and filtering scope. It does not differentiate itself from siblings like event_show or the other *_list tools, but the verb+resource pairing is unambiguous about what it returns.

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 reader infers this is the enumeration tool versus event_show for a single event. The one genuinely useful routing rule is the parenthetical that at most one of particle/subject/corpus_entry may be supplied, but there is no explicit 'use this when' or named 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?

With no annotations provided, the description carries the full burden and does so well: it discloses that all epistemics are computed at render time and never stored, that hops/max_nodes are clamped by graph config with human-readable disclosures, that future as_of instants are rejected, that all_projects has no effect on an unbound server, and that the url field only appears when base_url is configured. This is exactly the behavioral context an agent needs for a tool with no annotation coverage.

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 mandatory-scope rule is front-loaded ahead of the argument list, and the Args/Returns structure is easy to scan. It is long and occasionally florid ('the anti-hairball invariant', 'the picture of the knowledge the agent consulted'), but those phrases are doing real disambiguation work rather than padding.

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

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

For an 11-parameter tool with zero schema coverage, the description covers scope exclusivity, aliasing and clamping behavior, ordering/filter semantics, and the conditional url field. Output schema exists and is still summarized usefully (nodes, edges, particles, supersessions, census, disclosures), so an agent can call this correctly without opening any other resource.

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 11 parameters, so the description must compensate entirely and does: it documents accepted id forms (exact case-insensitive names/aliases for subject_id, unique prefixes for inconsistency_id, region id or title for section), defaults ('default' is the canonical store), and edge semantics (bare date = start of day UTC, future rejected, hops clamped). Nearly every parameter gains meaning beyond its bare title and type.

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 ('Render') and a precise resource ('one scoped epistemic subgraph of the particle store'), and immediately constrains the scope modes. An agent can distinguish it from particles_list, query, or subjects_show because this returns a graph render rather than a flat listing or search result.

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 states the when-not ('a whole-store render does not exist; the anti-hairball invariant') and explains which scope argument selects which mode, effectively describing four alternative entry points. It does not, however, route the agent to sibling tools for simpler needs (e.g., particle_show for one particle), so it stops just short of full alternative 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?

With no annotations, the description carries the full burden and does so: read-only, no LLM call, no mutation, only ACTIVE particles considered, already-linked CO_EVIDENTIAL pairs excluded, threshold falls back to a named config key, and a `truncated` flag appears when the limit fires. These are exactly the behavioral traits an agent cannot get from schema or annotations.

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

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

The scope statement and mode are front-loaded before the Args/Returns detail, and every line carries information. The docstring-style formatting and cross-reference to `particles links suggest` add a little ceremony but no real waste.

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?

A read-only reporting tool with no annotations and three undocumented parameters is fully specified: what it scans, what it excludes, how the threshold resolves, how truncation surfaces, and even the return shape (with an output schema present, that last part is bonus).

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 0%, and the description compensates fully: subject_id's None-means-all behavior plus a recommendation, threshold's 0.0–1.0 range and config default when omitted, and limit's meaning (max pairs across all clusters, default 100, triggers 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: 'Propose co-evidential candidate pairs within Subjects', and immediately scopes it as read-only. The 'within Subjects' framing lets an agent distinguish it from the sibling corpus_links_suggest 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?

Gives clear operational context: it is the REPORT mode of `particles links suggest`, produces candidates 'for operator review', and explicitly recommends passing subject_id to keep results focused. It does not explicitly contrast against corpus_links_suggest, so the sibling choice is left to inference from 'within Subjects'.

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 no annotations present, the description carries the full burden and does so: it declares the tool is read-only, that --fix is forced off, that LLM semantic checks are disabled, and what the agent is expected to do with results. It also discloses the response cap behavior (default 100, hard cap, truncated: True when it fires) and that summary always reflects full counts regardless of category filtering.

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 key constraint (read-only, no fixes, no LLM) is front-loaded before the Args block, and each argument paragraph adds real information rather than restating the schema. The Args/Returns layout is well structured, though the prose is slightly longer than strictly necessary.

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-required-parameter read tool with an output schema and no annotations, the description covers purpose, safety profile, parameter semantics, truncation behavior, and return shape. The Returns section slightly overlaps the output schema but adds the truncated flag and the summary_only shape variation, which are not otherwise obvious.

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, and it does for all three parameters. It explains category as a finding_type filter with concrete example values and notes summary is unaffected by it; summary_only as dropping the findings list and returning only summary plus run_at; and limit as a post-filter cap defaulting to 100 with a truncated flag.

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 sentence states a specific verb and resource ("Run structural lint checks over the particle store") and immediately scopes it with "no fixes, no LLM." That scope clause separates it from mutation-oriented or LLM-assisted siblings such as links_suggest and quality_report.

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 operational context — agents read findings and surface them to the operator, who decides whether to act — and describes a concrete workflow (use summary_only to learn what kinds of problems exist, then drill in with category). It never names a sibling alternative or states when a different tool would be preferable, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses the ordering and the limit default, which are useful, but it does not explicitly confirm read-only behavior, pagination semantics, permissions, 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?

The description is short and front-loaded: the core action and ordering appear first, followed by compact Args explanations. Every sentence adds useful information with no waste.

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 two-parameter list tool, the description covers the key call semantics, and the presence of an output schema means return values need not be explained. The main remaining gap is the absence of explicit read-only or permission context due to missing annotations.

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. It documents both parameters: limit as maximum entries with default 50, and source_type as an optional filter with an example value, though it does not enumerate all valid source_type values.

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: "List recent corpus entries," and adds the ordering "most-recently-deposited first." This clearly distinguishes it from sibling tools that list other resources, though it does not explicitly name an alternative.

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 implies usage by specifying recent entries and an optional source_type filter, but it does not say when to choose this tool over alternatives such as corpus_links_suggest or query. No explicit when-not or alternative guidance is provided.

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 no annotations, the description carries the full behavioral burden and does substantial work: it warns that each taxonomy embeds its full tag tree, that even a few large taxonomies can exceed the per-tool-result token cap, and that results are name-ordered so pagination is stable. It omits any permission/auth context or statement that the call is a read-only, non-mutating operation.

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 one sentence, followed by tightly scoped parameter notes. Every sentence carries information an agent needs to size its request correctly; there is no restatement of the tool name or 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?

An output schema exists, so return-shape explanation is unnecessary, and the description covers the real risk factors (payload size, pagination ordering). It leaves unstated whether results are scoped by permissions or whether there is a total-count signal to drive pagination termination, which an agent planning a full sweep would 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?

Schema coverage is 0%, so the description must fully compensate, and it does: both params get defaults, a definition of their effect, and the operational reason behind each. The limit explanation (embedded tag trees causing token-cap overflow) is exactly the kind of guidance the bare integer schema cannot convey, and offset is tied to the stable name ordering.

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 line states a specific verb and resource ('List every taxonomy') and adds a meaningful scope detail ('its full tag tree'), which tells the agent this is an exhaustive browse rather than a search. It does not name a sibling, but the sibling set (subjects_list, particles_list, etc.) is resource-disjoint, 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: the agent infers this is the way to enumerate all taxonomies with their tags. There is no explicit 'use this when... instead use X' routing, and no statement of when browsing is preferable to querying or searching.

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 no annotations, the description carries the burden well: it discloses the 200-result cap and its rationale (fingerprint matches share full content strings, which would blow token limits), and explains that all_projects is a no-op on an unbound server and that the result signals which view was used. Missing only note on ordering or error behavior for a malformed fingerprint.

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 purpose sentence followed by tightly packed Args/Returns blocks; nearly every line adds information an agent needs. The docstring formatting is slightly heavier than prose would be, but no content 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?

Given an output schema exists, the Returns block is a bonus rather than a necessity, and all parameters plus the cap and binding behaviors are covered. The one gap is that 'context fingerprint' is never defined nor is its source named, so an agent without prior knowledge may not know how to obtain one.

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 0% (bare typed properties), yet the description documents all three: fingerprint as full 64-char SHA-256 hex or a prefix of at least 8 chars, limit with default 50 and hard cap 200, and all_projects with its server-binding nuance. This fully compensates for 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?

States a specific verb and resource plus the filtering key: list particles sharing a context fingerprint. This implicitly separates it from particles_list (unfiltered listing) and particle_show (single particle by id), though neither sibling is named.

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

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

The mechanism is clear, but there is no explicit 'use this when you have a fingerprint, use X otherwise' routing, and no stated prerequisites for obtaining a fingerprint. Usage must be inferred from the one-line purpose and the all_projects caveat.

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 no annotations, the description carries the behavioral burden well: it describes the returned structure, explains restated_as and that content keeps its first wording, and states that zero or multiple prefix matches raise. It does not explicitly restate read-only/safety properties, but 'show' clearly implies a non-mutating retrieval.

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 with the tool's purpose, then cleanly structured into Args and Returns sections. The return-value detail is dense but each element adds useful semantics, especially around restated_as and content wording.

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?

Although an output schema exists, the description adds needed semantic context about provenance and restated_as, and it fully explains the single argument and error behavior. An agent has enough information to invoke this correctly and interpret key return fields.

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 explain the only parameter. It does so fully: particle_id accepts a full UUID or an unambiguous prefix of at least 8 characters, and ambiguous prefixes raise.

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 verb and resource: 'Show one particle with its provenance, subjects, and tags.' This clearly distinguishes a single-entity retrieval from list/search siblings such as particles_list and particle_search, though it does not explicitly name those alternatives.

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 single-particle scope, and the description helpfully notes that ambiguous prefixes raise an error. However, it does not explicitly say when to use this tool versus particle_search, particles_list, or other retrieval siblings, leaving selection mostly 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?

With no annotations, the description carries the full behavioral burden. It discloses important traits: embeddings are never included, responses are size-capped, subject resolution can raise on no-match or multi-match, and `all_projects` changes scope on bound servers. It does not explicitly state read-only/no-side-effect semantics, but the listing behavior is strongly implied and well contextualized.

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 with the core purpose and organized into Args and Returns sections. It is longer than strictly necessary, especially in the Returns block where an output schema already exists, but the added detail remains relevant and usable rather than redundant fluff.

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 five optional parameters, 0% schema description coverage, no annotations, and a rich output schema, the description is complete enough for an agent to call the tool correctly. It covers filtering semantics, pagination, scope behavior, error conditions, and what the response 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?

Schema description coverage is 0%, so the description must compensate, and it does. It documents each parameter: valid `status` values, `subject_id` resolution and join-table behavior including error cases, `limit` and `offset` defaults and pagination use, and the exact effect of `all_projects` depending on server binding.

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 opens with a specific verb and resource: 'List particles, optionally filtered by status or subject.' It also distinguishes this tool from siblings by calling it a lightweight alternative to `query` and `lint`, making its intended role clear without requiring schema inspection.

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 states when to use this tool (`when an agent just needs the IDs of particles in a particular state`) and gives concrete examples such as the open INCONSISTENCY queue, RETRACTED cleanup, and ACTIVE particles linked to a subject. It also names the alternatives it replaces for lightweight ID-only needs.

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 no annotations, the description does real work: it discloses that results are "Computed entirely from live DB queries — no LLM involvement," which tells the agent the call is deterministic, costs no model spend, and is safe to repeat. It also names the underlying signals (recorded llm_spend, curation precision with its denominator) so the agent knows facts are derived, not estimated. It stops short of stating read-only guarantees, freshness/latency, or whether the snapshot is expensive to compute — the main remaining gaps.

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 one-sentence purpose, then a structured enumeration of contents with backticked field names, ending with the cost/disclosure caveat. It is dense but readable and every clause identifies a distinct metric family. Slight redundancy: since an output schema exists, spelling out the returned fields in prose partly duplicates structured data.

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-parameter, read-only reporting tool whose return shape is already captured by an output schema, this description covers what the agent still needs: what dimensions are reported, that the numbers come from live DB queries with no LLM cost, and what "precision" is measured against. Nothing required to decide to call it or to interpret the headline metrics 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 there is nothing for the description to disambiguate; baseline 4 applies. One minor wrinkle: it says precision is measured "over the default window" even though no window argument exists, which could momentarily suggest a parameter that isn't there.

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 ("Return") and a specific resource ("extraction-quality dashboard snapshot"), then enumerates the exact metric families contained (particle counts by status/calibration_source/schema_version, structural-mix percentages, llm_spend, curation_precision). It is unmistakably distinct from data-access siblings like particles_list, query, or lint — an agent can tell this is the read-only quality aggregation endpoint 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?

Usage is only implied: the enumerated contents make it obvious this is the tool for quality/health monitoring rather than data retrieval, but there is no explicit "use this when you need X instead of Y" statement or exclusion against siblings such as query or particles_list. Adequate for routing a competent agent, but the selection rule 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?

With no annotations, the description carries the full behavioral burden and does so richly: deterministic modes use no embedding or LLM call, count/group_by reject simultaneous questions, future as_of instants are rejected, summary drops provenance/tags/properties/embeddings, grounded answers cite or label every sentence, and all_projects has no effect on an unbound server. It also discloses exclusions, coverage gaps, and retired-claim handling.

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 with a clear purpose and organized into Args/Returns, which suits a 22-parameter tool. It is necessarily dense, but some return-detail text is verbose and partially duplicates the output schema, so it is not maximally concise.

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 22 parameters, 0% schema description coverage, no annotations, and an output schema, the description is complete enough to call the tool correctly. It covers every parameter, mode interactions, rejection rules, response shapes, coverage gaps, and attribution behavior.

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 22 parameters, so the description must compensate entirely, and it does: every parameter is explained with meaning, accepted values, interactions, and defaults. Examples include predicate's exact-string/CURIE caveat, object_gt/object_lt normalization and disclosure, count/group_by rejection of question, and during_start's window 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?

The first sentence names a specific verb and resource: 'Run a tag-aware semantic query against the particle store.' It also explains the major operating modes (semantic question, deterministic structural listing, aggregates, predicate vocabulary, grounded answers). It does not explicitly differentiate itself from sibling tools such as particle_search, though it references particle_show for follow-up inspection.

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 explicit conditional guidance within the tool: omit question for deterministic modes, use summary when only answer and particle IDs are needed, use as_of for point-in-time beliefs, use during_start/during_end for windows, and notes that count/group_by reject a simultaneous question. It does not, however, say when to choose this tool over sibling search/list tools.

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?

No annotations are provided, so the description carries the full load. It explains the pagination rationale (token caps) and clarifies that order='degree' uses active particle counts with a name tie-break. It does not state read/write intent, but 'List' implies read-only. The added behavioral context is solid, though not exhaustive.

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 well-structured: a front-loaded purpose sentence, a short paragraph on pagination rationale, and a clear Args section. Every sentence serves a purpose. It could be slightly tightened, but overall it is appropriately sized.

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 a simple list tool with three parameters, no annotations, and an output schema that handles return values, the description covers purpose, pagination, parameter semantics, and ordering. 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?

Although the input schema has 0% description coverage, the description includes a detailed Args section explaining limit, offset, and order, including defaults and the meaning of order values. This fully compensates for the schema gap and gives the agent everything needed to invoke the tool correctly.

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 clear verb and resource: 'List subjects in the knowledge graph (alphabetical by canonical_name).' It distinguishes from a search by using 'List' and specifying the default ordering. However, it does not explicitly contrast with sibling tools like subjects_search or subjects_show, so it misses the top 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?

The description gives some usage context, e.g., using order='degree' to find hub subjects as a graph_view starting scope. But it offers no explicit when-to-use guidance relative to alternatives such as subjects_search or subjects_show, so the agent has to infer its place among 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?

With no annotations, the description carries the full burden and does disclose matching semantics (canonical_name or any alias, case-insensitive), result ordering (alphabetical by canonical_name), and that pagination is stable. It doesn't disclose error or empty-result behavior, which keeps it short of 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?

One-line purpose is front-loaded before the Args block, and each parameter sentence adds real information. The docstring-style 'Args:' formatting is slightly less scannable than prose 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?

Output schema exists so return values needn't be explained; matching, ordering, and pagination are all covered. The remaining gap is guidance on choosing this over subjects_list/subjects_show, which matters given the crowded sibling set.

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%, yet the description fully compensates: it explains what 'query' matches against with a concrete example ('speaker' -> alias 'the speaker'), why 'limit' exists (broad substrings like 'the' match thousands), and that 'offset' is safe because ordering is stable alphabetical.

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 (substring search over subject names and aliases) plus the matching mode (case-insensitive). An agent can distinguish it from subjects_list or subjects_show by the search semantics, but the description never names those siblings 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?

Usage is only implied: 'substring search' suggests search-when-you-don't-know-the-name, versus subjects_list for enumeration or subjects_show for a known subject. There is no explicit when-to-use, when-not-to-use, or alternative routing statement despite 16 sibling tools.

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 no annotations, the description carries the full burden and does so: ambiguity raises an error naming candidate subjects, remote engines restrict resolution to IDs and prefixes, results are capped and ordered by id for stable pagination, and particle_count reveals truncation against the token cap. These are non-obvious failure modes and limits an agent could not infer elsewhere.

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

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

The opening sentence front-loads the core behavior, and the Args/Returns blocks are dense with genuinely useful detail. The RST-style code markup and docstring formatting add a little visual noise, but no sentence is 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?

For a two-parameter lookup with no annotations, the description covers resolution rules, error behavior, truncation detection, and pagination escape hatch. Although an output schema exists, the Returns block still clarifies the meaning of particle_count and the ordering of particle_ids, which the schema alone would not convey.

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 0%, so the description must compensate and it does fully: subject_id accepts a full UUID, an unambiguous prefix of at least 8 characters, or a name/alias, matched case-insensitively and exactly, with the ambiguity conditions spelled out. particle_id_limit is explained as a cap with a stated default of 100 and the reason for its existence.

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 ('Show one subject') plus the associated payload ('particle IDs linked to it'). The singular 'one subject' implicitly separates it from siblings subjects_list and subjects_search, so an agent can select it without reading either schema.

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

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

Explicitly routes the agent to particles_list(subject_id=…, limit=…, offset=…) when the linked list is truncated, which is a concrete alternative with a triggering condition. It also warns that a remote engine resolves IDs and prefixes only, which governs how the tool can be called. It never says when to prefer subjects_search to resolve an unknown reference, so it falls just short of full when/when-not coverage.

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