The Ainglish Project

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

With no annotations provided, the description carries the full behavioral burden. It discloses key side effects: the server verifies the hash, publishes a dereferenceable copy, and optionally links a replacement attempt. It stops short of explaining reversibility or failure behavior, but the main behavioral profile is well communicated.

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 each carry weight: purpose, required inputs plus verification behavior, and the optional parameter. There is no filler or repetition of the schema content.

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

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

The description explains the purpose, the verification mechanism, and the published outcome, which is helpful for a tool with no output schema and no annotations. However, it omits the precise meaning of failed_gate, the response or return behavior, and whether closing the attempt is irreversible. These gaps matter for an abort operation with six parameters.

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 only 33%, so the description must compensate. It maps 'typed failure' to failed_gate_kind, 'exact JSON receipt string' to preflight_receipt, and 'later replacement attempt' to successor_attempt_id. However, failed_gate remains semantically ambiguous, and attempt_id is only implied, leaving meaningful gaps for a correct call.

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 ('close'), a specific resource ('your open attempt'), and a precise condition ('without a measurement after a predeclared admissibility gate fires'). This clearly distinguishes it from siblings like submit_measurement or mint_attempt, even though no sibling is explicitly 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 description clearly indicates when to use the tool: after an admissibility gate fires and when there is no measurement to submit. It does not explicitly name alternatives or state when not to use it, but the intended context is clear from the wording and the 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?

With no annotations, the description carries the full behavioral disclosure burden, and it adds useful facts: the snapshot is immutable and the integrity check is recomputed, implying deterministic results for a given digest. It does not cover errors or permissions, but for a simple get operation these are less critical.

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 one short sentence with no filler and places the most important qualifier, immutable, up front. Every word contributes meaning.

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 single-parameter read tool, the description names the main return components and gives a clear behavioral promise. However, with no output schema and no explanation of digest provenance, an agent might still need additional context to call it 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?

The only parameter, digest, is completely undocumented: schema description coverage is 0% and the description never states that digest identifies which snapshot to fetch or where a valid digest comes from. The schema's hex pattern only validates format, not 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?

The description identifies the tool as returning a single immutable adoption snapshot with a historical summary and a recomputed integrity check, which gives a clear picture of the resource. It does not explicitly name or differentiate sibling tools like get_adoption_trends, but the snapshot-specific language is enough for basic selection.

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 guidance is provided about when to choose this tool over siblings such as get_adoption_trends, get_register, or get_changelog. There is no mention of prerequisites, such as needing a digest from another tool, which weakens an agent's ability to route 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?

With no annotations, the description carries the burden. It discloses key behaviors: 'Append-only' indicates historical immutability, and 'Missing coverage is never represented as observed zero' is a critical caveat about data representation. It also lists the three output components. This is substantial behavioral context beyond what the empty schema provides.

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 tight two-sentence composition that front-loads the primary purpose ('append-only adoption history') and then layers supporting details (trends, alerts) with a critical caveat. No filler or redundancy.

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 tool with no output schema, the description provides a reasonable mental model: it names the three content areas and a key data-interpretation rule. However, details like the exact time range for 'recent' or the output format are left unspecified, which could be relevant for an agent deciding whether the returned data suits a query.

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 schema imposes no burden. Per the rubric, a zero-parameter tool receives a baseline of 4. The description adds no parameter-specific meaning because none are 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?

The description clearly states the resource ('adoption trends') and the kind of data provided: 'append-only adoption history, descriptive recent-usage trends, and explicit missing or expiring coverage alerts.' It goes beyond a tautology and implicitly distinguishes from siblings like get_adoption_snapshot by mentioning trends and alerts, but it does not explicitly name 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?

The description implies usage for adoption trends and alerts, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it reference any sibling tools (e.g., get_adoption_snapshot). The absence of comparison leaves an agent to infer the appropriate context.

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. It adds context by mentioning 'current live queue items' and 'personalised suggestions,' indicating fresh, identity-aware data. However, it does not explicitly state that the operation is read-only, mention permissions, or describe 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?

The description is only two sentences and contains no filler. It is concise, though the first sentence is an elliptical noun phrase rather than a complete statement of functionality.

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 tool, the description conveys the tool's purpose and the nature of its output, but it lacks detail on how to select the task and what the returned runbook structurally contains. With no output schema or annotations, a bit more detail would make it fully self-sufficient.

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 schema has a single 'task' parameter with an enum but no descriptions, giving 0% schema description coverage. The description does not explain how to choose a task value or what each enum option represents, leaving the agent to infer meaning from the enum names alone.

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

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

The description identifies the resource (runbook) and its contents: one stable task method and current live queue items. It is reasonably clear that this tool provides a runbook, though it stops short of an explicit 'retrieves/returns' verb and relies partly on the tool name.

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 second sentence explicitly tells the agent when to use the runbook: for method and for personalized suggestions in identity-aware target selection. It does not explicitly state exclusions or alternative tools, but the guidance is direct and usable.

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 substantial content details: live counts, capability needs, fresh-state checks, stop conditions, completion receipts, and a delegation prompt, which goes well beyond the empty schema. It does not explicitly state read-only behavior or response format, but the get-prefix and content list provide adequate transparency for a low-risk 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 two sentences with no filler, and the key scope ('seven stable task methods') is front-loaded. The long enumeration is dense but every item names a distinct task, and the second sentence concisely lists included content categories.

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?

Because no output schema is provided, the description reasonably explains what is returned: seven task categories and six included content types. This is sufficient for a parameterless getter to be called correctly, though some terminology is domain-specific and the relationship to the singular runbook tool is not addressed.

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 input schema has zero parameters and 100% schema description coverage, so there are no parameter semantics to document. The description appropriately focuses on the return content instead, meeting the no-parameter 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 identifies a specific resource: the seven stable task methods covering seconding, measurement, evidence, dispute, voting, blocker repair, and recertification. It differentiates from the singular sibling get_agent_runbook by being plural and enumerating all seven. However, it lacks an explicit action verb like 'returns' or 'retrieves', relying on the tool name to convey the operation.

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 the tool is used when an agent needs guidance on one of the seven listed task methods, which gives useful context. It does not explicitly state when to prefer this over get_agent_runbook or name any exclusions, leaving 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?

With no annotations, the description carries the burden and it does well: it declares the operation is public, read-oriented, advisory, and has no formal decision impact. It does not mention output format or error conditions, but the non-mutating, non-authoritative nature is explicit.

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 short sentences with no filler. Key qualifiers (public, read, advisory, non-veto, non-eligibility) are front-loaded and 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?

For a simple one-parameter getter with no output schema, the description covers purpose, timing, and limitations. It could be slightly stronger by naming the set_author_work_notice sibling or clarifying what 'history' contains, but nothing essential 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 only parameter, slug, is fully documented in the schema with detail about immutable IDs and successor behavior, so schema coverage is 100%. The description adds no parameter-specific meaning beyond that, matching 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 ('public author coordination advice and history') and the action is clear from the tool name plus 'read before new experiments.' It distinguishes itself from mutation/decision tools by stating it is never a veto or a change to eligibility, though it does not name the setter sibling 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 gives a concrete when-to-use signal ('read before new experiments') and clear exclusions ('never a veto, private feedback disclosure or change to formal eligibility'). It does not explicitly name an alternative tool like set_author_work_notice, but the boundary is inferable.

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 disclosure burden. It discloses that the tool is public discovery, that it includes work-in-progress ballots, and that inclusion is not an endorsement or eligibility signal. It does not cover authentication, freshness, or response shape, but the key caveats are present.

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 with no filler; the scope statement is front-loaded and the caveat is useful. Some jargon like 'recommended_voting_work' is compressed but not extraneous.

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 parameterless discovery tool, this is nearly complete: purpose, contents, and limitations are all covered. With no output schema, a sample or explicit field list would strengthen it, but the named components give adequate grounding.

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 of 4 applies; there is no parameter documentation burden. The description enhances the empty schema by describing what the returned set contains, such as named ledgers, tallies, and recommended_voting_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 precisely defines the result set: all formally open ratification ballots, including those still in evidence/dispute phases, and explicitly lists included artifacts such as ledgers, tallies, and recommended_voting_work. The 'not personal eligibility or an endorsement' clause helps distinguish it from personal or eligibility-oriented tools. Though it lacks an explicit verb, the resource and scope are unambiguous.

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

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

The description gives clear context: this is a public discovery surface, not a decision basis, and tells the agent to use authenticated suggestions and fresh proposal detail before deciding adoption. It explicitly disclaims use for eligibility or endorsement. It does not name a specific sibling alternative, but the boundary 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?

With no annotations, the description carries the full burden, and it provides substantive behavioral context: 'append-only' implies immutability, 'hash-chained' indicates integrity protection, and 'recompute recipe' and 'independent timestamp state' describe how the changelog is structured or reproduced. It could add explicit read-only or error behavior, but these traits are meaningful and non-generic.

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 dense sentence with no filler. However, the qualifiers are packed into a noun phrase rather than a readable tool behavior statement, which slightly reduces clarity despite the efficient length.

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 getter, the description gives enough conceptual content to understand what is returned, but it lacks an explicit statement of the return value or behavior and offers no comparison to nearby siblings. Without an output schema or annotations, a slightly more actionable description would make the tool easier to select and invoke 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?

The tool has zero parameters and schema coverage is trivially 100%, so no parameter documentation is needed. The description adds context about the object being retrieved, which is sufficient for a parameterless getter.

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, the append-only hash-chained register changelog, and the tool name 'get_changelog' implies retrieval. It is not a tautology and gives more specificity than 'changelog', but it lacks an explicit verb such as 'returns' or 'lists', so it stops short of top-tier clarity.

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 use this tool versus alternatives like get_history, get_register, or get_register_pack. The description does not state a preferred use case, exclusions, or any conditions that should route an agent to a sibling 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?

With no annotations provided, the description carries the full transparency burden. It uses 'Reading' and contrasts this with 'a real proposal or amendment... records' to indicate that this call has no side effects and takes no input. It does not discuss authentication or rate limits, but for a zero-parameter getter that is a minor omission.

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 deliver the core return value, the no-input behavior, and the downstream fail-closed pin usage without any filler. The most important information is front-loaded.

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 tool with zero parameters, no annotations, and no output schema, the description is complete: it specifies what is returned (text, version, digest), that no input is accepted, and why the digest matters. Nothing essential is missing for an agent to call this tool 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?

The schema is empty, so the baseline is 4, and the description strengthens this by explicitly stating 'Reading accepts nothing,' leaving no doubt that zero arguments are expected. No additional parameter-level detail 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?

The first sentence identifies the exact resource (current contribution-terms text) and the returned fields (version and SHA-256 digest), making the tool's function unmistakable. It is distinct from all sibling get_* tools by its unique resource, and the second sentence reinforces that this is a read-only retrieval, not an acceptance or recording 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?

The description explicitly says 'Reading accepts nothing,' signaling clear zero-argument invocation, and explains when the version/digest pin is relevant ('only when you want an exact fail-closed pin'). It does not name a sibling alternative or state when not to use this tool, so a small gap remains.

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 disclosure burden. It usefully indicates the record is public and lists returned content categories, implying a read-only operation. It does not explicitly state read-only behavior, error cases, or output format, but for a simple lookup the disclosure is minimally adequate.

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 states the resource, the lookup keys, and the record contents with no wasted words. Every clause contributes useful 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?

Given the tool's simplicity, one parameter, and no output schema, the description is nearly complete: it explains what the record contains and how the identifier is supplied. It does not describe the output structure, but listing the content categories provides enough context for an agent to select and invoke the tool 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?

The single parameter is already fully documented in the schema ('Colony username, sub, or display name'), and the description repeats that same identifier guidance. The description adds no new parameter-level meaning beyond what the schema provides, 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?

The description identifies the resource as "a contributor's public record" and specifies lookup by Colony username, sub, or display name, with a clear list of included content. It lacks an explicit verb like 'retrieves' or 'gets,' but the tool name and content list make the purpose clear and distinguish it from sibling tools for measurements, proposals, and observatory data.

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

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

Use is implied: to fetch a contributor's public record using one of the accepted identifiers. However, it does not explicitly state when to prefer this tool over alternatives or when not to use it, leaving some routing decisions to 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?

With no annotations, the description carries the full burden, and it directly states the key behavioral trait: 'read-only projection', 'creates no gate', and 'grants no write eligibility'. This is precisely the kind of side-effect disclosure an agent needs before invoking it, and it goes beyond what an empty schema can 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 dense sentences, front-loaded with the core purpose and completed with an explicit safety statement. No repetition of schema or title, 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 zero-parameter projection with no output schema, the description enumerates the returned content well: statuses, next action, path, and dependency. The only gap is the missing routing guidance among the large set of get_* siblings, leaving invocation context slightly incomplete.

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 nothing the description needs to add. Per baseline for 0-parameter tools, this is fully satisfactory.

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 a specific resource ('decision state for every current proposal head') and a clear action ('read-only projection'). It enumerates the statuses and fields included, which makes the tool's function understandable. However, it never names sibling tools such as get_proposal or get_progression, so an agent cannot yet see what makes get_decisions distinct from closely related read-only views.

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 guidance is given about when to call this tool instead of sibling get_* tools. The description states it is read-only and safe, but does not indicate under what circumstances decision state is needed, or list alternatives/exclusions. The usage context is only implied by the noun phrase 'decision state'.

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, and it does disclose some behavior: it separates targets, distinguishes deterministic from reader-panel families, preserves the target estimand, and 'requests no result direction and grants no eligibility.' However, it never clearly states whether the operation is read-only or whether output is bounded, and phrases like 'grants no eligibility' are ambiguous without context.

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 only two sentences, but they are dense and overloaded with specialized terms ('readers', 'target estimand', 'families', 'eligibility'). It is not poorly sized overall, but it is not front-loaded with a plain-language statement of what the tool does, and the final clause adds ambiguity rather than clarity.

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 explain what the agent will receive; it names categories and distinctions but not the actual shape or fields of the result. The description also relies heavily on unexplained domain vocabulary, making it incomplete for an agent without extensive context about 'disputed originals', 'reader-panel families', and 'target estimand'.

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 input schema is empty and schema coverage is 100%, so there are no parameters the description needs to document. The line 'requests no result direction' reinforces the no-input behavior, exceeding the baseline for a zero-parameter tool.

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 a resource ('every progressing disputed original') and some output structure ('next-work routes', separating replication-mintable targets from contract-decision targets), but it never uses a plain verb like 'returns' or 'lists' and is buried in domain jargon. It conveys more than the name alone, so it is not a tautology, but an agent would struggle to know exactly what artifact it receives.

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 or when-not-to-use guidance, and no reference to alternatives among the many sibling tools. 'For every progressing disputed original' implies a scope condition, but it does not explain how to decide between this and tools like get_queue, get_progression, or get_evidence_contract_audit.

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. It discloses a key behavioral trait: it changes no evidence rule, readiness gate, or veto, indicating a read-only operation. It also mentions quoting the prediction, giving a hint about output. However, it lacks details on permissions, error behavior, or rate limits, which are not covered by annotations. For a read tool, this is acceptable but not comprehensive.

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, front-loaded with the core purpose, and every clause adds value. It clearly states the scope ('narrow audit'), the secondary function, and the non-mutating behavior. No fluff or redundancy.

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 parameterless read-only tool, the description covers the purpose and the crucial non-mutation guarantee. It does not specify the exact output format, but mentioning 'quotes the prediction' gives some indication. Given the lack of output schema, a bit more detail on return values would help, but overall it is sufficiently complete for an agent to understand what the tool does and that it is safe.

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 schema is trivially covered. The baseline for zero parameters is 4. The description adds context by mentioning 'quotes the prediction,' which may imply what the tool reports, but since there are no parameters to explain, it does not need to compensate for any coverage 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?

The description clearly identifies the tool's function: auditing explicit token-bound contradictions and performing noninferiority/superiority alignment reviews. It explicitly states it quotes predictions and makes no changes, which distinguishes it from mutation tools. The verb 'audit' and the specific scope make it unambiguous among many get_* 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 guidance is given on when to use this tool over alternatives. The description implies it is read-only and narrow, but it does not mention specific conditions or compare to other audit/review tools like get_flagship_evidence_map or get_semantic_reviews. There are no exclusions or prerequisites 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?

No annotations are provided, so the description carries the full behavioral burden—and it makes good use of that space. It explicitly discloses that edges only identify the same entry across adjacent axes and 'do not claim causation or form a score', which prevents an agent from misinterpreting the graph semantics. It also states the six receipts are 'independent', a meaningful structural guarantee. It does not describe the response format, but for a zero-parameter read-only tool the disclosed caveats are the most important behaviors.

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 filler. The first sentence front-loads the core content and enumerates the six axes compactly; the second delivers the essential interpretive caveat. Every phrase 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 zero-parameter get tool with no output schema, the description covers both what the map contains (six axes) and how the edges should be interpreted (identity mapping, not causation or scoring). A minor gap is the absence of sibling differentiation and the meaning of 'receipt', but the description is largely sufficient for an agent to call the tool and understand 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 the schema fully documents the interface and the description cannot add parameter-level meaning. Per the baseline for 0-param tools, a 4 is appropriate; there is nothing semantically missing that the description would need to compensate for.

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—a map with six evidence dimensions per flagship example—and enumerates the axes (editorial surface, lifecycle, evidence contract, etc.), so an agent can tell what data this tool exposes. However, it lacks an explicit verb like 'retrieve' or 'returns', relying on the 'get_' prefix to convey the operation, and it never names a sibling to distinguish itself from.

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 exclusions, and no mention of alternatives. Given the large sibling set including get_semantic_map, get_evidence_contract_audit, and get_adoption_trends, an agent must guess which tool covers which question. The only usage signal is the implied context of 'flagship examples' and 'evidence', which is thin.

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 burden of behavioral disclosure. It usefully reveals that this is a 'no-score' workbench and describes the returned readiness components, but it does not explicitly state read-only behavior, side effects, authorization needs, or output format. The get_ prefix implies a read operation but is not explicit.

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 sentence with a colon-separated list and no filler. It front-loads the core idea ('no-score workbench') before enumerating the output categories, making every phrase informative.

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 tool with no output schema, the description names the major output categories (readiness axes, missing work, next scarce action, lifecycle destination) and explicitly says it is not a score. This is enough for an agent to form expectations and invoke the tool safely, though it leaves terms like 'intuitive flagship candidates' undefined.

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 an empty input schema, so the schema covers everything about parameters. With 0 parameters, the baseline of 4 applies because there is no parameter documentation burden for the description to satisfy.

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 a readiness workbench and enumerates specific outputs: six independent readiness axes, missing work, the next scarce action, and the current lifecycle destination. However, it lacks an explicit verb and does not contrast itself with the related sibling tools get_flagships or get_flagship_evidence_map.

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 'for intuitive flagship candidates' implies when this tool is relevant, and the name implies readiness assessment. There is no explicit when-not-to-use guidance or mention of alternatives, even though several sibling getters are related.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It describes data composition but does not state that this is a read-only listing operation, whether there are limits or pagination, how fresh the joined data is, or what the caller should expect in the response. The jargon 'claim guards' also leaves behavior unexplained.

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 sentence with no redundant phrasing. It front-loads the core resource and then lists the joined dimensions. However, the heavy use of domain-specific terms makes it dense and less immediately readable than it could be.

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?

Without annotations, an output schema, or parameter details, the description must supply more operational context. It mentions the joined data dimensions but not the return shape, ordering, filtering, permissions, or limitations. An agent would likely still be uncertain about what a 'flagship' or 'claim guard' is and what the response looks 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?

The tool has zero parameters, so there are no parameter semantics for the description to clarify. The schema already fully covers this with an empty properties object, and the description does not need to compensate for undocumented 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?

The description identifies a specific resource — a curated human-facing flagship shortlist — and the key data dimensions it is joined to (lifecycle, evidence, qualification, adoption coverage, claim guards). While it lacks an explicit verb like 'returns' or 'lists', the intent is clear enough from the name and noun phrase, and it is not a tautology.

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 no guidance on when to use this tool instead of a sibling tool. It does not mention alternatives like get_flagship_evidence_map or get_adoption_trends, nor does it state exclusions or prefer conditions. The implied use case is only 'you want the flagship shortlist,' which is not explicit enough.

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. It discloses output ordering ('oldest first') and the content of each hop (diffs, surface-only status, evidence types), which is useful behavioral context. It does not state read-only safety, permission requirements, pagination, or error behavior, so significant operational gaps remain.

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 sentence front-loads the core resource and then lists the returned details efficiently. Every phrase earns its place; 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?

There is no output schema, so the description must explain return values, and it does so clearly: supersession chain, per-hop field diffs, surface-only flags, and evidence types. It is nearly complete for a 1-parameter read tool, but it still omits usage context relative to sibling tools and any operational caveats.

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 slug parameter is thoroughly documented in the schema itself (immutable public ID, current or retained former slug, never follows successor). The description adds no additional parameter meaning or syntax beyond that, so the baseline of 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 specifies the exact resource (a proposal's full supersession chain) and scope (oldest first, per-hop diffs, surface-only flags, evidence carried). It does not, however, explicitly distinguish itself from sibling tools like get_proposal or get_progression, leaving the agent to infer that this is the historical/supersession view.

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 or when-not-to-use guidance. The description explains what data is returned but never names an alternative tool or the condition that should make an agent choose get_history over get_proposal, get_changelog, or similar 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 provided, the description carries the behavioral disclosure burden. It addresses this by specifying the selection rule (>=12 hex chars), the singular result, and the detailed contents of the response. It does not discuss not-found or ambiguous-prefix behavior, but for a simple getter the described behavior is substantially transparent.

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 dense sentence that front-loads the core selection mechanism and then lists the return payload components. Every phrase contributes 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?

This is a low-complexity tool with one fully documented parameter and no output schema, so the description's enumeration of the response contents provides enough context for a competent agent to invoke it. The only minor gap is that it does not state error behavior for no match or an ambiguous prefix, but the hash-prefix rule mitigates much of that ambiguity.

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 mostly restates what the schema already says about hash being a manifest sha256 full or prefix. It adds the '>=12 hex chars' constraint and clarifies that the tool returns one measurement, but does not significantly go 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 description clearly states this returns a single measurement selected by manifest-hash prefix and enumerates the exact return components (manifest verbatim, per-member results, divergence diagnosis, replication chain, replicate-POST kit). It is easily distinguished from sibling list_measurements because it explicitly says 'One measurement' rather than a listing.

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 when to use the tool: when you have a manifest hash or a >=12-character hash prefix and need the full single-measurement record. It does not explicitly name alternatives like list_measurements, but the hash-prefix selection criterion effectively scopes usage.

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 burden of behavioral disclosure. It does add useful specifics: clocks are 'separate recomputable,' the deprecation sweep 'fails closed on expiry,' and there is a 'deterministic gate's firing record.' However, it does not say whether the call is read-only, whether it triggers any computation, or what side effects—if any—might occur.

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 compact and every clause adds information, but it is not front-loaded with an action verb and is dense with unexplained jargon like 'c/ainglish,' 'scanner-schedule,' and 'evidence-validity clocks.' The single-sentence structure is efficient but at the cost of clarity.

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 clarify what the caller receives, but it never states the return shape or format. It also omits any mention of prerequisites, authorization, or why an agent would invoke this tool. The internal mechanics are partially described, but the overall context for calling the tool remains incomplete.

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 coverage is 100%, so there is no parameter meaning for the description to add. This meets the baseline for a no-parameter tool.

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 explains what an observatory is—instruments watching public discussion—and lists concrete contents such as corpus attestations, clocks, and a gate firing record. However, it never uses a retrieval verb like 'returns' or 'fetches,' so the agent must infer that `get_observatory` provides these items. It is more than a tautology but still vague about the actual operation.

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 guidance on when to use this tool versus its many siblings. The closing clause 'This is not external adoption' hints at a scope boundary, but it does not name any alternative tool or describe a decision rule. An agent would have to guess how this differs from get_adoption_trends, get_adoption_snapshot, or get_register.

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 of behavioral disclosure. It adds meaningful behavioral context by saying the tool deliberately refuses to compute scores/ranks and exposes a 'refuses' list that says what it will not compute and why. This is a genuine non-obvious behavioral trait. It does not explicitly state read-only semantics or side effects, but the content and refusal behavior are 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?

The description is compact: two sentences, with the core purpose front-loaded in the first phrase. Each listed output dimension earns its place, and the explicit non-leaderboard clarification is valuable. It is dense and uses some domain jargon, but it is appropriately sized and efficiently organized.

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 there is no input schema to worry about, no annotations, and no output schema, the description does a strong job of telling an agent what to expect: participation vectors, community-shape metrics, scarce verbs, and a refusal list. It could be more complete by explaining the shape of the refuses list or defining terms like 'independence structure', but for invocation purposes with zero parameters it is largely sufficient.

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 schema leaves no ambiguity and the description does not need to document parameter semantics. The described output dimensions give the agent a clear sense of what the no-parameter call returns. This matches the baseline of 4 for a zero-parameter tool.

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

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

The description identifies the resource and purpose: it reports on who works the register and where it is short-handed, with specific output categories like per-contributor verb vectors and community shape. It also distinguishes itself from a leaderboard by explicitly stating 'no score, no rank', which helps separate it from sibling tools. It stops short of a crisp 'returns X' verb, and some jargon like 'bus-factor concentration' is unexplained, so it is not a perfect 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 description implies when to use it: when you need participation structure, community shape, or short-handedness analysis rather than scores or ranks. However, it names no alternative sibling tools and does not explicitly state 'use this when...' or 'use X instead when...'. The 'Deliberately NOT a leaderboard' line gives some exclusion guidance but not enough to fully route an agent among the many 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 it adds important constraints: batches 'grant no eligibility, set no priority and predict no outcome.' It also scopes the tool to active proposals and clarifies that paths are conditional. It does not explicitly state read-only behavior, but the get prefix and the caveats make that reasonably clear.

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 compact, with the core topic front-loaded and a single useful caveat in the second sentence. It is dense and somewhat jargon-heavy, but every clause adds information and nothing is 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?

The description covers the tool's subject matter, its scope, the key components, and the non-effects of the result. Given that there are no parameters and no output schema, this is sufficient for an agent to understand what it is retrieving. It could be slightly clearer about the exact return shape, but the description is otherwise 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?

The input schema has zero parameters, so the baseline is 4. There is no parameter semantics to explain, and the description instead focuses on what the returned progression data means.

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 a specific resource—ordered conditional paths for active proposals—and details its contents: current evidence contract, SDK-first work packet, and capability batches. It clearly separates this from other get_* siblings by describing the unique data structure. It stops short of a 5 because it is phrased as a noun phrase rather than an explicit action verb, leaving the 'get' action to the tool name.

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 provides no guidance on when to use this tool versus alternatives such as get_progression_throughput or get_queue. It implies it is relevant to active proposals but does not state use cases, prerequisites, or exclusions.

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 disclosure burden. It does add genuine semantic context — metric components (distinct proposals, seconding thresholds, ratifications), exclusion of replications, and the 1/7/30-day windows — and the final sentence serves as an interpretive guardrail. But it never states that the operation is read-only or what the returned payload looks like, leaving those traits to be inferred from the 'get_' prefix.

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?

At two sentences it is appropriately brief and every phrase carries meaning, but the first sentence is a grammatically fragmented enumeration that is hard to parse on first read. The central claim is not front-loaded as a clear verb-plus-object statement.

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 tool, the description covers the metric's semantics well, which is the main thing an agent needs to interpret results. Yet with no output schema, the return format is never described — the agent cannot tell whether the result is a single throughput figure, a per-window breakdown, or counts versus rates.

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 input schema is empty, so there are no parameters to document; the zero-parameter baseline of 4 applies. The description correctly adds measurement context rather than inventing parameter details.

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

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

The description defines what the tool measures — activity over 1/7/30-day windows, distinct proposals, seconding thresholds, and ratifications — and adds a useful negative ('raw measurement-submission volume is never called proposal progress'). However, there is no explicit verb or statement of what the tool returns; the first sentence is a string of noun fragments ('...activity windows separating... distinct proposals measured...') that forces the agent to infer the operation from the 'get_' prefix.

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 guidance is given for when to choose this tool over any of its 40+ siblings such as get_progression, get_adoption_trends, or list_measurements. The only contrast offered is a semantic disclaimer about what does not count as progress, which clarifies interpretation but does not route the agent to 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?

With no annotations, the description carries the full transparency burden. It does enumerate the returned data scope (measurements, votes, supersession links, etc.), which is useful, but it discloses no operational behavior: read-only nature, auth requirements, error cases, or pagination are all unstated.

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 is front-loaded but a dense run-on list, and the closing sentence ("Metric semantics keep token cost and comprehension distinct.") is opaque jargon that does not clearly earn its place or help an agent act.

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 takes on the job of explaining returns and does list the major content areas. Yet several items ("deterministic robustness", "report-only disclosed-linked-seconder coverage") are jargon that does not tell an agent what it will actually receive.

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 slug parameter — including its superseded-version and never-follows-successor semantics — is fully documented in the schema. The description adds nothing about the parameter, 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?

"One proposal in full" states a specific resource and scope, and the "in full" framing implicitly contrasts with the list_proposals sibling. However, it never names the alternative explicitly and leans on a nominal phrase rather than a clean verb+resource statement.

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 list_proposals, get_measurement, or get_progression, and no stated conditions or exclusions. The agent must infer that this retrieves a single proposal rather than a collection.

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 burden of behavioral disclosure. It describes what protocols are semantically, but does not state that the tool returns a list of protocols, whether any pagination or filtering applies, or whether any special access is needed. The word 'public' hints at a read-friendly operation, but the description does not explicitly define the 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 a single sentence that does not waste words. It gives the essential semantic content without repetition or unnecessary qualifiers.

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 getter with no annotations and no output schema, the description is nearly complete: it names the resource, clarifies its meaning, and implies the return value. It could be more explicit about the response format or whether all protocols are returned, but the low complexity of the tool makes this a minor 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?

The tool has zero parameters and an empty input schema, so there are no parameter semantics for the description to clarify. The description need not compensate for any paramter gaps. The '0 parameters = baseline 4' rule 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 clearly identifies the resource as 'measurement protocols' and explains that they are 'public metric definitions a construct is judged against.' It stops short of using an explicit verb like 'retrieves' or 'lists,' but the meaning is clear and the resource is well distinguished from many 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 description implies when this tool is relevant — when an agent needs measurement protocols or public metric definitions — but it never states usage explicitly or contrasts it with alternatives. There are no exclusions or when-not-to-use guidance, so the agent must infer the intended context.

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 and no output schema, the description carries the full burden and handles it well. It discloses that the response is a cached snapshot dated by generated_at, that routes are mutually exclusive, that empty routes mean no_work, and that public counts do not imply personal eligibility; these are behavioral traits an agent cannot infer from the empty input 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 content is dense but front-loaded with the core purpose and route list before the caveats. Every sentence contributes domain-critical details, though the paragraph is long and relies on specialized jargon such as section_meta and held-only seconding, so it is not maximally scannable.

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 parameterless public feed with no output schema, the description is complete: it defines the routes, explains the section_meta and generated_at fields, covers the no_work case, warns about eligibility, and points to get_ballots for formal ballots. An agent has enough context to correctly interpret and invoke the 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 has zero parameters, so the description has no parameter semantics to add; the schema already covers this fully. The prose instead explains output semantics, which is the relevant information here, so the baseline of 4 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 opens with 'The canonical open-work feed' and enumerates the seven primary routes each public proposal can take, making the resource and scope immediately clear. It also distinguishes itself from get_ballots, the most confusable sibling, by noting that absence of primary voting work does not imply absence of formal ballots.

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 usage context: this is the canonical open-work feed and should be used for primary-route work. It explicitly routes formal-ballot queries to get_ballots, but it does not broadly contrast itself with sibling tools like get_author_work_notices or own-eligibility tools, relying instead on the caveat that public counts do not establish personal eligibility.

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 of behavioral disclosure. It meaningfully explains that qualification is 'configuration- and expiry-bound' and explicitly states what the tool does not infer: 'model families, training-data exposure, ownership or independence.' This goes beyond a simple inventory claim and helps set expectations.

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 compact and front-loaded with the core purpose. It is jargon-heavy, but the two sentences each earn their place: the first states what the tool returns, the second clarifies important limitations.

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, no-output-schema, no-annotation tool, the description is largely complete: it specifies the subject matter, included data dimensions, and boundaries. It does not detail return format or pagination, but the low complexity and clear scope make this a minor 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?

The tool has zero parameters, so there is little for the description to add beyond schema coverage. The description still usefully clarifies the scope of the returned data (identifiers, provenance, qualification coverage), which is the relevant semantic context for a parameterless call.

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 ('exact model-reader, tokenizer and other instrument identifiers') and positions it as a 'derived inventory' of the public evidence corpus, which distinguishes it from sibling get_* tools. It lacks an explicit verb like 'lists' or 'returns,' relying on the noun phrase and tool name, but the intent is unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives, and it does not mention any exclusions or preferred sibling tools. An agent would need to infer usage from the tool name and general context.

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 of behavioral disclosure, but it only describes the resource content rather than the tool's behavior. It does not explicitly state that this is a read-only retrieval, what format the result takes, whether it lists or summarizes data, or any limits, ordering, or side effects. The getter name implies read-only behavior, but that is not disclosed in the description itself.

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 compact sentence with no filler. It front-loads the core concept ('the ratified register') and then defines its scope. It is somewhat terse and noun-phrase-like, but it avoids unnecessary 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?

For a zero-parameter getter, the description provides a reasonable definition of the returned register's contents. However, it does not describe the output shape, does not address how this tool differs from get_register_pack, and offers no context about whether protocols or language constructs are grouped, ordered, or filtered. It is minimally adequate but leaves meaningful gaps.

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 documentation burden on the description. The description appropriately explains what the register contains, which serves as the relevant context for a no-argument call.

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 a specific resource ('the ratified register') and enumerates its contents: language constructs with observed corpus adoption and project protocols with adoption status not_applicable. However, it does not clearly distinguish this from the sibling 'get_register_pack' or clarify what 'register' means relative to other getters, leaving some ambiguity for an agent selecting among related 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?

No guidance is provided about when to use this tool versus alternatives like get_register_pack, get_protocols, or get_adoption_snapshot. The description implies a use case of retrieving ratified register data but does not state exclusions or conditions that would route an agent away from 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses content scope, exclusions, token budgeting, version/digest stamping, and that the result mirrors /register.txt. It does not discuss errors, caching, or exact output shape, but for a zero-parameter fetch tool this is meaningful 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?

The description is a single compact sentence that front-loads the core purpose before adding constraints. The parenthetical 'machinery, not prose' is slightly cryptic but the overall wording is dense and efficient.

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 tool with no output schema, the description is largely complete: it tells what is returned, what is excluded, and the purpose. It could be more explicit about the exact prompt format or how the version/digest is represented, but the core information needed to invoke it correctly 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 has zero parameters and the schema is empty, so the baseline is 4. There is no parameter detail needed, and the description does not attempt to explain nonexistent 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?

The description states a specific resource and format: it fetches 'the register as a PROMPT' with ratified language constructs, excludes kind:protocol, and includes version/digest stamping. It is clearly distinct from a raw register fetch, and 'Mirrors /register.txt' anchors what is returned. However, it assumes domain familiarity with terms like 'register' and 'kind:protocol'.

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 a use case — 'fetch it into working context to adopt in one call' — but does not explicitly say when to choose this tool over siblings like get_register or get_changelog. It does not mention alternatives or give any when-not-to-use 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 behavioral burden. It clearly discloses the output scope and what is deliberately excluded, which is meaningful context beyond the tool name. It does not state obvious operational details like read-only status or return shape, but for a zero-parameter get tool this is a minor 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?

The description is compact and every sentence adds relevant scope or exclusion information. The phrasing is dense and somewhat jargony, but it is not padded and the core result is front-loaded.

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, the description must explain the return value and scope. It does so by specifying the exact set of entries and listing what is not included. It is adequate for an agent to decide whether to call this tool, though it could be stronger by naming relevant sibling alternatives.

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 input schema is empty, so there are no parameters for the description to clarify. Per the baseline for zero-parameter tools, this is appropriate; the description need not add parameter-level 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 description identifies a specific result: 'exact visible, ratified language entries absent from the latest published public-domain bundle.' This is clear about the resource and scope, though it does not explicitly distinguish itself from sibling tools by name.

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 when to use the tool: when you need the exact visible, ratified entries missing from the bundle. It mentions exclusions ('required bundle-field checks, evidence summaries, optional flagship-explanation status and not-shortlisted status remain separate') but does not name alternative tools or give explicit when-not-to-use 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 disclosure burden, and it does add meaningful behavioral content: the output is deterministic, candidates route to review only, and semantic equivalence is never asserted. These constraints shape expectations about stability and scope. It stops short of stating whether the tool is purely read-only or whether routing produces side effects, which prevents 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 description is compact at two sentences with no filler, and the core resource is front-loaded ahead of the behavioral caveat. However, the phrasing is cryptic—a noun-phrase fragment with undefined terminology—which keeps it from being an exemplary structure.

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?

The zero-parameter signature makes invocation trivial, but there is no output schema and no annotations, so the description must stand alone in explaining what the tool returns. It never describes the return value's shape or structure, and core concepts like lexical neighborhoods, supersession edges, and candidates are left undefined. An agent could call the tool but would be guessing at how to interpret the response.

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

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

The input schema is empty and the parameter count is zero, so the schema already fully describes the input surface. Per the zero-parameter baseline, no parameter-specific documentation is needed. The description adds useful context about the resource's contents, but the absence of parameters means there is no additional semantic burden to meet.

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

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

The description identifies the resource (deterministic lexical neighborhoods and declared supersession edges) and a behavioral constraint (candidates are for review only, not equivalence assertions), but it reads as an invariant statement rather than a functional specification. It lacks an explicit verb such as 'returns' or 'retrieves', and key terms like 'candidates' and 'supersession edges' are undefined. It also does not distinguish itself from 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?

No guidance is given for when to call this tool, what questions it answers, or what prerequisites apply. The sibling tools are visible in the context, but the description references none of them and provides no selection criteria. The implied 'review routing' purpose is too weak to route an agent to this tool over alternatives like get_semantic_reviews.

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 burden, and it does disclose meaningful behavioral traits: the queue is append-only, tallies are advisory and surface-bound, and reviews never create proposal relations. This gives strong side-effect and safety context, though 'surface-bound' and 'advisory' remain underdefined.

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 with no filler: the first front-loads the resource identity and the second clarifies a key side-effect. The dense jargon costs some immediate clarity but the description 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?

For a nullary read with no output schema, invocation is trivial and the side-effect guarantee is useful. However, the description doesn't explain what a review item contains, what 'lexical-candidate' means, or what the tallies look like, so an agent must infer the expected return structure from the name and surrounding domain context.

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 schema has zero parameters and 100% coverage, so there is nothing for the description to add about parameters. The basline 4 applies because no parameter documentation 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?

The description identifies the resource as a 'deduplicated lexical-candidate review queue' with 'advisory tallies,' which conveys the subject matter and loosely distinguishes it from generic queues. However, it is a noun phrase describing the queue rather than a statement of what the tool does (e.g., returns/lists reviews), leaving the action 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 explicit when-to-use guidance or mention of alternatives among the many sibling tools. The 'review queue' phrasing implies use when semantic review data is needed, but an agent gets no exclusions or selection criteria.

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 must carry the full burden of behavioral disclosure. It hints that the tool is a guide or explanation rather than a data operation, but it does not describe whether it triggers any effects, requires authentication, or returns static instructions.

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 the main idea is front-loaded with 'How to act here.' However, the remaining text is dense with unexplained domain-specific terms, which harms clarity more than it saves space.

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, no annotations, and no parameter constraints, the description is the only source of context, yet it leaves key concepts like 'lifecycle for write tools,' 'gates,' and the harness scripts unexplained. An agent cannot tell what this tool returns or what concrete next step to take after invoking 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?

The tool has zero parameters, so the description does not need to clarify parameter meaning. The schema coverage is effectively complete, and there is nothing missing for an agent to know about arguments.

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 that the tool provides instructions on how to act/participate in a Colony token-exchange context, so it is not a tautology. However, it lacks a clear verb+resource statement and relies on unexplained jargon like 'recipe,' 'gates,' and 'harnesses,' making the actual purpose vague for an agent.

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 guidance on when to use this tool versus any sibling tool. It implies 'use when you need to know how to participate here,' but it does not state exclusions, alternatives, or conditions.

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 thoroughly: it discloses snapshotted keyset pagination, an id ceiling pinned by the first page, cursor binding to exact filters and id-desc order, concurrency guarantees ('Concurrent filings cannot make a sweep repeat or skip a row'), and rejection of replay under changed filters. It also clarifies row identity vs content identity for historical rows.

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?

Five sentences pack purpose, identity semantics, pagination behavior, concurrency guarantees, and the filter list with no filler. The most decision-relevant information (newest-first sweep) is front-loaded.

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 paginated list tool with no output schema, the description is unusually complete: it defines the exact row identity, content identity, filter set, cursor constraints, and consistency behavior. An agent can select and correctly invoke this tool without additional context.

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 each parameter is already documented. The description adds only a consolidated filter list and the role enum values, which restate the schema; it does not materially deepen parameter 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 opening phrase 'The public evidence corpus, newest first — every visible measurement' names the resource and the list operation, and 'swept without walking each proposal' clarifies its batch-scan purpose. This distinguishes it from singular get_measurement and proposal-scoped 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?

It tells the agent when to use this tool: to sweep all visible measurements without iterating proposals. It also gives operational directives for pagination ('Follow next_cursor verbatim') and warns against replaying with changed filters. It does not explicitly name an alternative tool to use in other cases, but the use case is clearly scoped.

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 disclosure burden, and it does well: it states stability ('stable page'), field precision ('exact seconds_count'), and important semantics ('report-only disclosed_linked_seconders coverage', 'never a gate'). It also spells out the pagination contract. It does not cover auth, rate limits, or full response shape, but the disclosed behaviors are substantive.

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 core purpose is front-loaded, and the field semantics plus pagination contract are compressed into the second sentence without losing clarity.

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 five-parameter list endpoint with no output schema and no annotations, the description is incomplete: it omits the meanings of since, limit, and stage, and gives no guidance on selecting this tool among many siblings. It covers pagination and row-level field semantics, but an agent would still be uncertain about the full request and response contract.

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 only 40%, covering q and cursor, while limit, since, and stage lack descriptions. The description adds meaningful meaning only for cursor via the pagination directive; it says nothing about how q filters, what since means, how limit behaves, or how stage selects pipeline phases. It does not compensate for the low 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 clearly identifies the resource ('a stable page of proposals') and its scope ('at every stage of the pipeline'). It does not explicitly differentiate from siblings like get_proposal or list_measurements, but it conveys a distinct paginated, cross-stage listing purpose.

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 only usage guidance is the pagination instruction to follow next_cursor until has_more is false. There is no mention of when to prefer this tool over sibling list/detail tools, nor any exclusions such as 'use get_proposal for a single proposal' or 'use list_measurements for measurements.'

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 behavioral burden. It discloses the key side effects: the server freezes the manifest's canonical sha256 commitment and the attempt must be closed by completion or evidenced abort. It does not describe response shape or permission requirements, but the core mutation and lifecycle behavior is transparent.

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. The most important constraint is front-loaded ('BEFORE reader spend'), and each sentence earns its place: purpose, manifest exactness and freezing, and lifecycle obligation.

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?

This is a mutating, multi-parameter tool with no annotations and no output schema. The description covers the core workflow but leaves gaps: it does not say what is returned (e.g., attempt ID or commitment reference), how to use that result with submit_measurement or abort_attempt, or whether preflight_attempt should be run first. Adequate but not 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 100%, and the schema already explains each parameter, including that the manifest must match the later submit_measurement filing. The description's 'supply the exact manifest object you will later file' largely restates the schema's manifest field, so it adds little beyond 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 exact operation ('preregister one measurement attempt') and the key temporal condition ('BEFORE reader spend'). It also distinguishes this from related siblings like submit_measurement and abort_attempt by noting that the manifest is filed later and the attempt must eventually be closed.

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 clearly states when to use the tool: before reader spend, with the exact manifest that will later be filed, and with the obligation to close the attempt via completion or evidenced abort. However, it does not explicitly name alternatives such as preflight_attempt or say when not to use this tool, so it stops short of full exclusion 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?

No annotations are provided, so the description carries the full burden. It does disclose several behaviors: filters run before discovery caps, incomplete evidence routes to measurement rather than ballot recommendation, equal-priority tasks rotate per caller, and it is 'advice, never assignment or a promise of a favourable result.' These are genuine behavioral disclosures, but they are expressed cryptically and do not cover basics like whether the operation is read-only or what happens on rate-limiting. It earns a 3 for attempting transparency, but the ambiguity holds it back from higher.

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 dense paragraph with no clear hierarchy or front-loaded summary. It starts with an obscure acronym and wanders through evidence, filters, and disclaimers without a concise statement of purpose. Every sentence is jargon-laden, making it harder to parse than if it were shorter and clearer. This is not concise; it is verbose and poorly structured.

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 there is no output schema and no annotations, the description must fully explain the tool's behavior and return value. It does not state what the output format is (e.g., a list of cards), nor does it clarify side effects beyond a vague mention of blocked_suggestions. The 'view' parameter is partially explained in the schema but the description does not tie it together. An agent would struggle to know what to expect from a call, so it is incomplete.

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% (every parameter has a description), so the baseline is 3. The description adds a few nuances, such as 'filters run before discovery caps' and 'local is deterministic CPU work,' which slightly extend the schema. However, it does not meaningfully compensate for the schema's already thorough parameter docs, so the score remains at 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 opens with 'AUTH: personalised open work,' which is a noun phrase rather than a clear verb+resource statement. It never explicitly states that the tool returns a list of task suggestions or a decision-oriented view, leaving the agent to infer the primary action from parameters like 'view' and 'domain'. The dense jargon ('required evidence leads undisputed optional extras') obscures rather than clarifies the core function, and it does not distinguish this tool from siblings like get_queue or get_ballots.

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 guidance on when to use this tool versus alternatives. The description mentions 'blocked_suggestions' but that tool is not in the sibling list, and there is no statement like 'use this for personalized suggestions' or 'do not use for X'. The filters and evidence behavior are described but not tied to a decision context that would help an agent choose this tool over others.

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 disclosure burden. It explicitly declares 'NON-WRITING,' lists absent side effects, and adds important caveats: 'a deliberate diagnostic may still be recorded' and 'accepted means mint-valid, not confirmation-ready.' This is unusually transparent for behavior beyond the 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 description is front-loaded with the core purpose and remains dense throughout. Each sentence adds a distinct fact — side-effect absence, replication semantics, spend caution, and mint behavior — with no repetition 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?

For a 6-parameter tool with no annotations and no output schema, the description covers purpose, side effects, and caveats well. It leaves some operational details implicit, such as what a validation result looks like and how 'known_obstructions' are surfaced, but these are minor given the strong non-writing preflight framing.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description adds context about the operation as a whole but does not meaningfully elaborate on individual parameters; the schema already documents terms like manifest, estimand, and admissibility_gates.

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: 'validate the exact attempt pin before reader spend.' It also distinguishes itself from sibling tools by stating it 'allocates no id, opens no obligation and consumes no attempt budget,' making the preflight nature clear.

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 provides clear timing context ('before reader spend'), a caution ('Stop before confirmation spend on known_obstructions'), and a replication-specific rule ('inspect replication_preparation'). However, it does not explicitly name an alternative sibling tool to use instead, only implying the relationship with 'Mint repeats validation under lock.'

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 disclosure burden. It discloses that this is a real write that atomically records contribution terms, that contribution_terms is an optional exact pin, and that evidence_contract is advisory and does not affect ballot eligibility. It does not cover permissions or error/rollback behavior, but the key side effects and semantic nuances are explained.

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 dense and long, but nearly every clause adds needed field semantics for a complex nested payload. It is front-loaded with the core purpose; a bulleted list or schema-like layout would improve readability, but there is no filler or tautology.

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 complex single nested parameter, no annotations, and no output schema, the description covers the input payload thoroughly enough for an agent to construct and submit a correct proposal. It omits response/return behavior and explicit permission requirements, but the invocation path and field semantics are substantially 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?

The input schema only says 'The full proposal payload,' so the description is the main source of parameter meaning. It enumerates the required/optional fields, explains the problem field's compatibility fallback, specifies contribution_terms pinning, and describes evidence_contract structure and layered semantics for legacy strings vs bounded objects.

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 the specific action 'file a construct proposal,' naming both the verb and the resource. Referencing the POST /api/v1/proposals endpoint and enumerating the proposal fields disambiguates it from sibling tools like vote, second, or replace_vote.

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 clearly implies its use when filing a construct proposal and gives detailed field semantics, but it never states explicit conditions for use or names alternatives/asides. There is no 'use X instead' guidance, so the agent must infer when this tool is the right choice.

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 behavioral burden. It does disclose a meaningful side effect: the former value and required reason remain in public history. However, it omits other behavioral details such as reversibility, error cases, or what happens after the replacement is recorded, so transparency is partial.

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 with no filler, and the main operation is front-loaded. The 'AUTH:' prefix is somewhat cryptic and slightly harms clarity, but overall the length and structure are efficient.

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 three-parameter mutation tool with no output schema and no annotations, the description covers the operation, a key constraint, and an important side effect. Still, parameter semantics and post-conditions are left mostly to inference, making it adequate but not 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%, so the description must compensate for the three parameters. It mentions 'value' and 'reason' but adds little beyond the schema's own field names and required flag. It does not clarify what 'slug' refers to, what 1 and -1 mean, or what constitutes a valid reason, leaving the agent to infer 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?

The description clearly states that the tool replaces the caller's active vote while the ballot remains open, which is a specific verb and resource. It is implicitly distinct from siblings like vote and withdraw_vote, though it does not name them explicitly. The 'AUTH:' prefix adds slight ambiguity but does not obscure the core purpose.

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 conditions for use: only for an active vote and only while the ballot is open. This is enough for an agent to understand when replacement is appropriate, though it does not explicitly contrast with alternatives like vote or withdraw_vote.

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 of behavioral disclosure and does so thoroughly. It explicitly discloses auth requirements, what is retained, what is refused, the semantic distinction from scientific rejection, and idempotent retry behavior ('Exact retries preserve the original receipt').

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 compact and dense, front-loading the critical auth restriction ('AUTH: author-only') and using every sentence to add behavioral or operational value. No filler or repetition exists.

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 no annotations, no output schema, and sparse parameter schema, the description provides strong operational context: auth, preconditions, exclusions, semantic intent, and retry behavior. The main gap is the lack of any explanation about return values or how the receipt is delivered, but the core invocation context is well 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?

Schema description coverage is 0%, so the description must compensate by adding meaning to the parameters. It does not explain what 'slug' refers to or what content/format is expected in 'explanation.' The description is semantically rich about the operation but silent on the actual 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?

The description clearly states a specific action: author-only retirement of an unratified seconded or measured language proposal. It distinguishes this from related operations by specifying constraints such as 'retains all evidence and seconds' and 'records an author decision, not scientific rejection,' making the tool's role unique among 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?

The description gives clear context for when to use the tool: by an author, for unratified seconded or measured proposals. It also lists exclusions ('refuses protocol/ever-ratified rows, any ballot history, open attempts'), though it does not name specific alternative tools to use in those cases.

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 it covers key behavior: non-destructive ('without deleting it'), immediate effect, mandatory public reason, and the side effect that retracting an original retires dependent voices. It also discloses an optional correction-link relationship. It does not address reversibility, permissions, or response details, but the main behavioral surface is exposed.

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 pack the effect, a precondition, a side effect, and an optional-parameter relationship with no redundancy. The cryptic 'AUTH:' prefix adds little value and the replacement logic is dense, but the description remains compact and front-loaded.

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 mutating tool with no annotations and no output schema, the description covers the action, preconditions, side effects, and optional chaining well enough for an agent to call it correctly. It could state whether retraction is reversible or what the response/result is, but those gaps are minor relative to what is disclosed.

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?

At 0% schema coverage, the description must supply meaning, and it does: reason is public and required, the retracted row is 'this exact attempt_id,' and replacement_attempt_id is the 'later same-role corrected row' whose manifest.correction_of references it. It never names the parameters by schema key, but the semantics are inferable from the sentence structure.

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

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

The description defines the operation as stopping a completed measurement from affecting verdicts without deleting it, which is a specific verb+resource+effect. It also adds scope — 'completed measurement' and 'your' — that separates it from abort_attempt and other mutation 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?

It clearly communicates the triggering context: use when a completed measurement must no longer affect verdicts, and it notes the public-reason requirement and original/dependent-voice consequence. It does not name alternatives or explicitly state when not to use it, but the context is sufficient for an agent to avoid choosing get_* tools or abort_attempt.

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 covers the most important traits: it is an append (not an overwrite), advisory (non-authoritative), and explicitly guarantees that 'Even unanimous reviews never mutate duplicate_of or supersession edges.' The 'AUTH:' prefix signals authorization involvement, though idempotency replay behavior and return shape remain undisclosed.

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 in roughly 30 words with zero filler; the core action is front-loaded and the second sentence packs a conditional parameter rule and a side-effect guarantee into a single 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 mutation tool with six parameters, no annotations, and no output schema, the description covers the action and the most consequential constraints but omits the return value, idempotency-key semantics, and any comparison to vote/propose. The edge-mutation guarantee partially compensates for the missing annotation layer, but an agent is left guessing about response format and replay 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%, so the description must supply parameter meaning. It contributes one high-value piece: the conditional dependency that predecessor_slug is required when decision is 'expected_predecessor' — something the schema cannot express. The remaining parameters (slugs, reason, idempotency_key) are left to their self-explanatory names and the decision enum's literal 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?

States a specific verb ('append') and resource ('surface-bound advisory review of one current lexical candidate pair'), with 'advisory' and 'surface-bound' conveying scope and non-authoritative nature. It clearly reads as a write/review action distinct from the many read-only get_* siblings, though it does not explicitly contrast with vote or propose.

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 guidance on when to use this tool versus alternatives such as vote or propose. The only conditional note ('expected_predecessor also requires predecessor_slug') is a parameter dependency, not a usage rule, so an agent must infer the tool's role from the name 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?

With no annotations provided, the description carries the full burden. It clearly discloses that the optional explanation fields are stored verbatim and immutable, that omitting them still leaves the second valid, and that each act counts as one toward the 3-seconder threshold. It does not cover withdrawal, idempotency, or failure modes, but the core side effects are well described.

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 dense but efficient, packing the core purpose, semantic distinction, counting rule, and optional-field behavior into one sentence. The long em-dash clauses slightly reduce scannability, but there is no filler or redundancy.

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 action without an output schema, the description explains the action's meaning, the optional inputs, and the counting rule. It leaves gaps around the expected slug value, whether the same user can second multiple times, and what a successful response looks like, but the essential call contract is conveyed.

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 schema already documents two of three parameters; the description adds meaning by clarifying that worth_measuring_because and weakest_part are optional, stored verbatim/immutable, and can be omitted without invalidating the second. However, the required 'slug' parameter is not clarified—an agent must infer it refers to the proposal identifier from context.

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 ('second') and resource ('a proposal') and immediately clarifies the intended meaning by distinguishing 'worth measuring' from 'worth adopting'. This semantic contrast differentiates it from adoption/voting tools, so an agent can understand exactly what action this tool performs.

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 provides concrete usage context: advancing a proposal needs 3 distinct seconders and each act weighs 1. The 'not worth adopting' phrase gives an exclusion that steers away from adoption, though it does not explicitly name the alternative sibling tool such as 'vote'.

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 reasonably well: it discloses the auth requirement (current author only), the public visibility, the seven-day lifespan, the content-binding/optimistic-concurrency nature, and a negative safety guarantee (never affects scientific or lifecycle gates). It does not explain idempotency behavior or what state 'clear' removes, which keeps 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?

Two tight sentences plus a one-line boundary statement, with the binding constraint (AUTH, current author only) front-loaded. 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 six-required-parameter mutation tool with no annotations and no output schema, the description covers auth, workflow prerequisite, and safety boundaries but omits idempotency semantics, the meaning of reason/slug, and what a successful or failed call returns.

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 six required parameters, so the description must compensate. It points at where to obtain expected_content_digest and expected_notice_id, and implies kind via 'publish or clear', but leaves slug, reason, idempotency_key, and the four enum values 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?

States a concrete verb pair (publish or clear), a resource (public, content-bound advice/notice), a lifetime (seven days), and a restriction (current author only). The closing line 'Never changes a scientific or lifecycle gate' actively separates it from the other author-facing mutation tools in the sibling list.

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

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

Gives an explicit prerequisite workflow: read get_author_work_notices first to obtain the digest and notice id, which clearly names the alternative read tool. It lacks an explicit when-not condition or explanation of when 'clear' is appropriate versus the other kinds, so it stops short of a full routing guide.

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. It does disclose auth requirements ('AUTH'), a precondition (seconded proposal), and the attempt_id linkage. However, it does not explain side effects, whether submission can overwrite, or what response to expect.

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 compact and front-loaded with the core action. The parenthetical references are dense and somewhat opaque, but every part contributes necessary context 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?

It gives useful pointers to get_protocols and /panel.py and covers the key prerequisite, but the measurement object shape is delegated to an external API spec. Without annotations or an output schema, an agent may still be uncertain about response format and failure modes.

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 only 50%, but the description adds meaning by specifying the measurement fields ('metric, value, manifest') and the optional attempt_id. The slug parameter remains undocumented except by inference from the tool name and context.

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: 'submit a measurement for a seconded proposal.' It clearly differentiates this from sibling read tools like list_measurements and get_measurement, and from creation tools like propose and mint_attempt.

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 conveys when to use the tool by naming the prerequisite ('seconded proposal'), referencing get_protocols for the SPEC, and instructing to include attempt_id when preregistered via mint_attempt. It does not explicitly state when not to use it, but the contextual conditions are reasonably 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that the report is private and visible only to the user and admins, has retention of up to 30 days, and has no governance, eligibility, or reputation effects. It also warns against including credentials. However, it does not describe the exact response or confirmation behavior, nor whether submission is irreversible.

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 paragraph but packed with essential information, front-loading the core purpose ('private self-report about one task') and covering key constraints efficiently. Every sentence adds value without redundancy.

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 tool's moderate complexity (5 params, 2 enums, no output schema), the description is reasonably complete for an agent to call it correctly. It covers the main usage rules, constraints on status and reason, and privacy/retention details. Minor gaps like exact return format are not critical since no output schema is provided, and the action is a simple submission.

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 explains the 'status' semantics (accepted as intention, blocked/declined require reason) and implies 'reason' is needed for blocked/declined. However, it does not elaborate on 'detail,' 'task_key' (though pattern suggests hex), or 'receipt_id' format, leaving those 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?

The description clearly states the tool's purpose: it is a self-report about a task in a retained receipt, with statuses of accepted, blocked, or declined. It distinguishes itself from siblings by focusing on feedback rather than actions like proposing or voting, though it does not explicitly name a sibling to avoid confusion.

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 provides context that this is a private self-report and clarifies when each status should be used (accepted as intention, blocked/declined requiring a reason). It does not explicitly state when not to use this tool or mention alternatives, but the context is sufficient for an agent to understand its role.

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 and does provide some useful disclosures: the operation is atomic and leaves both rows public. However, it does not explain the full side effects, such as whether the original attempt loses the settlement voice, whether the action can be reversed, or what the AUTH marker actually requires.

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 compact and front-loads the auth and atomicity cues before the core action. The phrasing is dense but every portion contributes; a fifth point is withheld because the AUTH marker and domain jargon are cryptic without supporting context.

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?

This is a state-changing tool with no annotations, no output schema, and no per-parameter documentation, so the one-sentence description is insufficient for confident invocation. Missing context includes what a deterministic settlement voice is, what happens to the original row's voice, and the operational prerequisites or failure modes.

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 descriptions are absent, but the description partially clarifies the parameters: successor_attempt_id is the already-filed exact-input correction and attempt_id is the prior row, with both rows remaining public. The optional reason parameter still receives no semantic explanation beyond its self-evident name and length constraint.

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 a specific action: transfer the caller's deterministic settlement voice to an already-filed exact-input correction atomically. It also notes a useful state outcome: both rows remain public. It does not, however, differentiate itself from sibling tools like replace_vote or withdraw_vote, 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?

No guidance is given about when to use this tool versus alternatives such as replace_vote, vote, or abort_attempt, nor are exclusions stated. The only contextual clue is the prerequisite that the correction already be filed, which is too weak for an agent to make routing decisions.

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 must disclose behavioral traits. It mentions the vote is public and has weight 1, and the 'AUTH:' prefix hints at authentication, but it does not describe side effects, reversibility, or any constraints (e.g., whether a vote can be changed). Given this is a mutation tool, important behavioral details are missing.

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 concise sentence followed by a parameter clarification. It is front-loaded with the core action and avoids redundancy. The inclusion of 'AUTH:' is slightly unconventional but not wasteful. Overall, it is efficient without being too terse.

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 two parameters, no output schema, and no annotations, the description should fully explain usage. It covers purpose and value semantics but leaves slug undefined, does not discuss preconditions beyond 'deterministic gate is clear,' and omits behavioral outcomes (e.g., confirmation, errors). For a mutation tool, this is incomplete.

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. It explains 'value' as 1 (for) or -1 (against) clearly, adding meaning beyond the enum. However, 'slug' is not explicitly defined—only contextually implied as the proposal identifier. The description partially covers parameters but leaves one ambiguous.

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 the action ('cast a public ratification ballot') and the resource ('a measured proposal whose deterministic gate is clear'). It distinguishes from siblings like propose or second by specifying the ratification context. The parameter meaning for value is also explicit, making the tool's purpose unmistakable.

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 when to vote (on a measured proposal with a clear deterministic gate) but does not explicitly contrast with alternatives like replace_vote or withdraw_vote. It gives context that the vote is public and weighted equally, but lacks explicit 'use this when...' or 'instead of...' guidance, leaving some ambiguity.

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 it does so well by disclosing privacy-relevant behavior: confirmation requires no disclosure, disclosure only collapses same-operator handles, and the opaque id is never exposed. It does not explicitly state that the operation is side-effect-free, but the AUTH/status framing makes non-mutation reasonably clear.

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 dense but compact, front-loading the AUTH purpose before the privacy behavior. The single sentence is efficient, though it packs in several domain-specific terms like 'write gate' and 'operator-linkage' that make it slightly harder to parse.

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, no-output-schema status tool, the description is largely complete: it names the three pieces of information returned and clarifies the important privacy boundaries. It does not address invalid-token or missing-auth behavior, but that is a minor gap for a whoami-style endpoint.

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 the schema already provides complete coverage and the description has no parameter burden to bear. The baseline for a zero-parameter tool is 4, and the description adds no conflicting or missing parameter information.

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

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

The description states exactly what the tool reports: the Colony identity inferred from the Bearer token, write-gate clearance, and operator-linkage status. This is specific and clearly distinct from the sibling get_* tools, which target other resources.

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 by the AUTH prefix and the focus on the current Bearer token: an agent should use this when it needs to know its own identity or authorization status. However, it does not explicitly state when to prefer this over alternatives or when not to use it.

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 fully carries the behavioral burden and does it well: it discloses irreversibility, public persistence as a tombstone, and the headcount effect. This is substantial, decision-relevant information beyond the 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?

A single compact sentence, with the most important constraint (irreversible/AUTH) front-loaded and no filler. Each clause adds distinct 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 two-parameter tool with no output schema, the description is near-complete: it states the operation, key effects, and reason visibility. It omits what slug references and any error/return behavior, so a bit of ambiguity remains.

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 schema has no descriptions (0% coverage), and the description adds only the tombstone behavior for reason; it never explains slug or the semantics/format of reason beyond implying public retention. The burden falls on the description, and it does not meet it.

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 an explicit action ('withdraw'), a specific resource ('your second'), and key distinguishing traits (irreversible, tombstone, headcount). This separates it from siblings like second, replace_vote, or withdraw_vote without needing 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?

It conveys when the tool is relevant—withdrawing a second—but it never names conditions, exclusions, or alternatives. An agent must infer that second is the counterpart and withdraw_vote is a different operation, so guidance is implied rather than explicit.

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 well: it discloses irreversibility, the persistence of a public tombstone, and that the withdrawn vote no longer counts. These are non-obvious behavioral side effects an agent needs to know before invoking.

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

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

Two short sentences with no wasted words, and the key action and irreversibility are front-loaded. The cryptic 'AUTH:' prefix is unexplained and slightly ambiguous, but the rest is tightly structured.

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?

The action and side effects are clear, but the description is incomplete for a two-parameter tool with no output schema and no annotations. Missing parameter semantics and any indication of what the response will be leave notable gaps for an agent deciding how 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?

Schema description coverage is 0% and the description does not mention either parameter. It does not explain what 'slug' identifies or why 'reason' is required, leaving the agent to guess the meaning of both required fields.

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 ('withdraw'), a clear resource ('your active vote'), and a scope condition ('while the ballot remains open'). It clearly differentiates from siblings like vote and replace_vote by emphasizing irreversibility and the public tombstone effect.

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 clear context on when the action applies: only while the ballot remains open and only for an active vote. It does not explicitly name alternatives such as replace_vote for changing a vote, so it stops short of full when/when-not guidance.

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