The Ainglish Project

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 discloses that the tool closes an attempt without a measurement (indicating it is a write/mutation), requires authentication via 'AUTH:', produces an auditable record via receipt hash, and supports an optional link to a successor. This provides useful behavioral context beyond just the name and 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 description is two sentences long and front-loaded with the key action. Every clause adds value—authentication requirement, core action, receipt hash audibility, optional successor reference. Minor improvement could be separating the auth hint more clearly.

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 three required parameters, zero schema coverage, no output schema, and no annotations, the description covers the main semantics but does not explain return values or side effects (e.g., whether the abort triggers other processes). It is adequate given the tool's narrow scope but could be more 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, which it does well. The description explicitly explains the purpose of preflight_receipt_hash (makes abort auditable) and successor_attempt_id (point to later replacement). attempt_id and failed_gate are implied by context but not detailed; still, the description adds meaningful semantics beyond the bare 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 uses specific verb 'close your open attempt without a measurement' and identifies the resource as 'attempt'. It distinguishes the action as an abort after a predeclared admissibility gate fires, which sets it apart from sibling tools like mint_attempt, submit_measurement, 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?

The description states when to use the tool: after a predeclared admissibility gate fires. It mentions that the receipt hash makes the abort auditable and optionally allows pointing to a later replacement attempt via successor_attempt_id. However, it does not explicitly state when NOT to use it or provide alternatives among siblings.

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

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

No annotations exist, so the description must fully disclose behavior. It only cryptically describes the changelog's nature (append-only, hash-chained) but does not explain what the tool actually does (e.g., returns data, triggers a recompute) or side effects like performance or access needs.

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

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

The description is too terse and cryptic, sacrificing clarity for brevity. While short, it fails to convey a clear functional purpose; better to add a few more words to clarify behavior.

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 tool has no parameters and no output schema, so the description is the sole source of behavioral info. It fails to explain what the agent will receive or how to use the result, leaving the agent underinformed.

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 description coverage is 100%, so schema handles this dimension fully. Description adds no value but is not penalized since baseline is 3 when coverage is high.

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 mentions 'append-only, hash-chained register changelog', which hints at the tool's purpose, but it does not clearly state a verb or functional action (e.g., 'retrieve changelog data'). The phrasing is overly technical and ambiguous, making it hard to distinguish from sibling tools like 'get_history' or 'get_register'.

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. With 20 sibling tools including 'get_history' and 'get_register', the lack of usage context or exclusions is a significant gap.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the operation is read-only ('Reading it accepts nothing') and hints at the output structure, but it does not discuss authentication, rate limits, or potential side effects beyond the implicit safety. The description adds value beyond the name but lacks depth expected for a tool with zero annotation coverage.

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

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

The description is two sentences with no wasted words. The first sentence states the return value, and the second provides crucial usage guidance. Every sentence earns its place; the content is front-loaded 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?

Given the tool has no parameters, no output schema, and no annotations, the description is nearly complete. It describes the return value (text, version, digest) and explains the behavioral implication (reading accepts nothing). A minor gap is that it does not explicitly state that the returned terms are the latest version, but 'current' implies that. Overall, it is sufficient for the agent to use 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?

There are no parameters, and the schema description coverage is 100% (trivially). The instruction sets a baseline of 4 for zero-parameter tools. The description adds meaning by explaining what the tool returns (text, version, digest), which is not captured in the empty schema. That extra context justifies the baseline score.

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

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

The description clearly states that the tool returns 'the exact current contribution-terms text, version and SHA-256 digest,' which directly describes the specific resource and operation. The verb 'get' is in the name, and the description reinforces it. Among sibling tools, none overlap this purpose, so it is well-differentiated.

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

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

The description explicitly tells the agent that reading the terms 'accepts nothing' and provides step-by-step guidance on how to use the output ('attach {version,digest,accepted:true} to a proposal'). It implies the usage context (before proposing) but does not mention when not to use this tool or compare it to alternatives. The guidance is clear and actionable.

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. The description indicates this is a read operation fetching public data, which is clear. However, it does not disclose potential limitations (e.g., what happens if the identifier is invalid, or if data is missing). No contradictions with annotations are present since none are provided.

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 that front-loads the purpose and lists key contents. It is not verbose. However, it could be slightly more structured by separating the identifier clarification from the content list, but as is, it is effective 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?

With one required parameter, no output schema, and no annotations, the description covers the basics adequately. It explains the identifier format and typical returned fields. However, it lacks completeness for edge cases (e.g., what if multiple fields are absent, or if the contributor doesn't exist). Given the tool's simplicity, this is sufficient but not thorough.

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

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

Schema coverage is 100% with one parameter described in the schema as 'Colony username, sub, or display name.' The description adds meaning by explicitly listing the acceptable identifier types (username, sub, display name) and the fields returned (proposals, seconds, measurements, public ballots). This goes beyond the schema's basic description, providing richer context for the parameter and expected output.

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 what the tool retrieves ('a contributor's public record') and specifies the identifiers accepted (Colony username, sub, or display name). It also lists the contents (proposals, seconds, measurements, and public ballots), which distinguishes it from sibling tools like get_proposal or get_measurement. However, it slightly overloads with multiple nouns and doesn't explicitly state it's a read-only lookup.

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 this tool—to fetch a contributor's public record using a supported identifier. It does not provide explicit guidance on when not to use it or alternative tools. Given the sibling context, alternatives like get_proposal or get_history are not mentioned, leaving the agent to infer usage without clear 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?

No annotations are provided, so the description carries full burden. It explicitly discloses what the tool returns: full chain, ordering, field diffs, surface-only flags, and evidence association. This provides comprehensive behavioral expectations without contradictions.

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 main result (supersession chain) and appends specific details in a clear list. Every component adds value without wasted words.

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 low complexity (one required parameter), full schema coverage, and no output schema, the description is completely adequate. It describes what the tool returns in sufficient detail for an agent to decide to invoke it and understand the output format.

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% with a single parameter 'slug', described as 'The proposal slug.' The description adds no further parameter details, but with full schema coverage and a straightforward parameter, the description's brevity is acceptable. Score 4 because the description still helps clarify the parameter's role in context of the tool's purpose.

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 verb 'get' and the resource 'a proposal's full supersession chain', specifying ordering (oldest first) and listing the exact information included per hop (field diffs, surface-only status, evidence). This distinguishes it from siblings like get_changelog or get_proposal, which might have overlapping but different purposes.

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 when you need the full supersession history with detailed per-hop diffs and evidence tracking. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., get_changelog for a simpler log). Given the context of 18 siblings, some exclusions would be helpful, but the purpose is sufficiently clear to infer appropriate use.

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 effectively communicates the tool's behavior: it is a read operation that returns detailed measurement data. It specifies the hash prefix requirement (>=12 hex chars) and the exact data payload, providing clear behavioral 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 a single sentence that efficiently lists the key data returned, but it is slightly dense with multiple data points which could be structured for easier parsing.

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 single parameter, full schema coverage, and no output schema, the description adequately details the tool's purpose and the nature of its return data. However, it could specify that the output is likely a JSON object or structure, which would improve completeness.

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 schema already documents the 'hash' parameter. The description clarifies the prefix requirement ('full or >=12-char prefix') but does not add significant meaning beyond what the schema provides.

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 includes the specific verb 'get' and the resource 'measurement by manifest-hash prefix', and lists the exact data returned (manifest verbatim, per-member results, replication chain, replicate-POST kit). This clearly distinguishes it from siblings like 'submit_measurement' or 'get_register'.

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 to retrieve a specific measurement by a hash prefix, but provides no explicit guidance on when to use it versus alternatives like 'get_history' or 'get_changelog', nor does it specify 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 provided, the description bears the full burden of behavioral disclosure. It hints at a behavioral trait ('the deprecation sweep fails closed on it') but does not state whether the tool is read-only, has side effects, or requires authentication. The return format and error behavior are also not addressed.

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, which is concise, but it is poorly structured. It is not front-loaded with the core purpose; instead, it uses a metaphorical phrase ('instruments watching the register') followed by a list in parentheses. Every word is not clearly earned.

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 absence of annotations and output schema, the description is the sole source of context. It fails to adequately describe what the tool returns, how the data is structured, or what triggers its use. For a zero-parameter monitoring tool, the description is incomplete for an AI agent to confidently invoke 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?

There are zero parameters, so the baseline is 4. The description adds meaning by naming three output components (corpus attestations, adoption-scanner liveness, gate_last_fired), which goes beyond the empty schema. However, the terminology is obscure and lacks explanation, reducing the value for an agent.

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 uses a noun phrase ('The instruments watching the register') rather than a verb+resource pattern, making it unclear that the tool retrieves data. It lists three specific items (corpus attestations, adoption-scanner liveness, gate_last_fired), but the overall purpose is vague and does not clearly distinguish from sibling tools like get_measurement or get_queue.

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. There is no mention of context, prerequisites, or exclusions. The description provides no actionable advice for the agent to decide between this and 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 provided, the description carries the full burden for behavioral context. It mentions that the tool returns computed metrics like 'bus-factor concentration RISK' and 'independence structure', and mentions a 'refuses' list that documents what it will not compute. This is helpful but lacks details on data freshness, computation time, or whether results are cached.

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 relatively concise at two sentences, front-loading the main purpose. The second sentence adds important caveats. Some technical jargon ('verb vectors', 'bus-factor concentration RISK') could be simplified, but the length is appropriate for the complexity.

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 complexity of the concept (analyzing contributor participation patterns) and the lack of an output schema, the description provides a reasonable overview of what the tool returns. However, it could elaborate on the structure of the output or what 'scarce verbs' means. The context signals show zero parameters and no output schema, which puts more burden on the description.

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 100% schema description coverage, so the schema already fully documents the lack of inputs. The description adds no parameter information, which is appropriate since there are none. The baseline of 4 is justified because the description doesn't need to compensate.

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

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

The description clearly states that the tool analyzes contributor participation patterns including verb vectors, community shape metrics, and identifies staffing gaps. It explicitly states what the tool is NOT (a leaderboard), which helps differentiate it from potential siblings like get_contributor or whoami. However, the purpose could be more precise about the resource being queried.

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 minimal guidance on when to use this tool versus alternatives. The 'Deliberately NOT a leaderboard' statement helps set expectations but doesn't explicitly suggest alternatives. With 18 sibling tools including get_contributor and how_to_participate, more contextual guidance would be beneficial.

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 fully disclose behavioral traits. It describes the output shape in detail (fields included: measurements, votes, language adoption, supersession links, robustness block), which gives good transparency about the return value. However, it does not mention side effects (likely none for a read), required permissions, error conditions (e.g., missing slug), or any filtering or pagination behavior. The description is adequate but not thorough for an unannotated tool.

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

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

The entire description is a single well-crafted sentence. It front-loads the core purpose ('One proposal in full') and enumerates the included data components in a clear, logical order. There is no fluff or redundancy. Every part earns its place by telling the agent what the tool returns.

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 has only one required parameter (no output schema), the description provides a complete picture of what will be returned: measurements, votes, language adoption, supersession links, and a robustness block. The list_proposals sibling exists, implying this is the 'details' counterpart for individual proposals. The description is sufficient for an agent to use this tool correctly 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% with a single parameter 'slug' described simply as 'The proposal slug.' The tool description adds value by implicitly justifying why the slug is needed (to identify which proposal to fetch in full) and frames the parameter's role in retrieving the comprehensive data set. It does not repeat schema boilerplate, but it provides context that the slug is the unique identifier for the proposal being expanded.

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

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

The description starts with 'One proposal in full:' which clearly states the verb (get/retrieve) and resource (proposal) with good specificity. It lists the distinct components included (measurements, votes, language adoption, supersession links, robustness block), which helps the agent understand the scope of the returned data. This distinguishes it from sibling tools like list_proposals (which likely returns a summary list) and get_measurement (which targets a specific measurement within a proposal).

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 implicitly tells the agent this is the go-to tool for retrieving complete proposal data, contrasting with list_proposals which probably returns only metadata. However, there is no explicit guidance on when not to use it (e.g., to avoid fetching large 'full' data when only a slug or ID is needed), and no alternatives are named. The context lacks usage boundaries.

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 full responsibility for behavioral disclosure. It fails to state whether the tool is read-only, what side effects occur, authentication needs, or expected behaviors. A bare definition of the data returned is insufficient.

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 wasted words. It is appropriately concise for a parameterless tool, but it could be improved by front-loading the verb and stating the action explicitly 'Get the measurement protocols...'.

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 tool has no output schema and no annotations, so the description must explain what the tool returns. It only defines the concept of protocols without stating that the tool returns a list of them. For a simple retrieval tool, the description 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?

The tool has zero parameters and schema coverage is 100% trivially. The description adds no parameter information because none is needed. Baseline for 0-param tools is 4, and the description meets that standard without deficiency.

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 measurement protocols are ('public metric definitions a construct is judged against') but does not explicitly state that the tool retrieves or lists them. The verb 'get' is implicit, but the description reads as a noun phrase definition rather than a clear action. It provides some context but lacks specificity about the tool's function, and does not distinguish from siblings like 'get_measurement' or 'get_observatory'.

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 offers no guidance on when to use this tool versus alternatives, no exclusions, and no prerequisites. It simply defines the concept without any contextual direction.

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 discloses behavioral traits: routing of incomplete evidence and the rule about proposer vs. independent agent measurements. However, it does not explicitly state that the tool is read-only, nor does it mention side effects, permissions, or rate limits. The information is helpful but incomplete for safe invocation.

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 consists of three sentences, but the first is dense with domain-specific jargon and multiple clauses. It is not streamlined; an agent might struggle to parse the key ideas. A more front-loaded and simpler structure would improve 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?

Given there is no output schema, the description should explain the return structure. It mentions 'with the action for each' but does not detail the format, fields, or possible values. The behavioral rules add useful context, but the output remains under-specified. For a parameterless tool, the description is moderately 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 is empty and schema coverage is 100%. The baseline for zero parameters is 4. The description does not explain parameters (none exist) but instead focuses on the tool's behavior. No additional parameter-level clarification is needed beyond what the schema provides.

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 that this tool returns 'the canonical open-work feed' and lists what items it includes (evidence, repair, ballot, re-certification) with actions. This distinguishes it from sibling tools like get_proposal or get_measurement, though the jargon may obscure the purpose for unfamiliar agents.

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 on when to use this tool versus alternatives. With 20 sibling tools, the description does not mention use cases, prerequisites, or scenarios where another tool would be preferable. The agent is left to infer the tool's role from its 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?

No annotations exist, so the description must carry the full transparency burden. It states the content of the register but does not disclose behavioral traits such as read-only-ness (though 'get' implies it), authorization needs, rate limits, side effects, or response format. Since it is a simple retrieval with no parameters, the lack of buthlavioral detail is less severe, but the description adds no transparency beyond the content. It does not contradict any annotations because none exist.

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 of moderate length, no waste. However, the structure is a noun phrase with a colon, which is slightly less readable than a verb-first declarative sentence. It is concise but could be front-loaded more clearly. Still, every word serves a purpose.

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

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

The description explains what the register contains but does not describe the output format (e.g., is it a list, an object, a JSON structure?) or provide any context about the 'ratified register' concept. With no output schema, the burden is on the description to inform about return values. It fails to do so. The domain is specialized and the description omits necessary foundational explanation for an AI agent to 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 input schema has zero parameters and schema description coverage is 100% trivially. According to instructions, 0 parameters baseline is 4. The description does not need to add parameter meaning since there are none. It correctly omits param reference.

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 defines the resource as 'the ratified register' and specifies its content (language constructs with adoption, plus project protocols with not_applicable status). The action 'get' is implied by the tool name and the noun-phrase description is interpretable as a retrieval operation. However, it lacks an explicit verb like 'retrieve' or 'list', and the jargon may confuse an agent unfamiliar with the domain. Still, it distinguishes from siblings like get_register_pack and get_protocols by defining the scope of the register.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. Among siblings (get_register_pack, get_protocols, get_changelog, etc.), there is no explanation of when get_register is appropriate or when to prefer another tool. No context signals about prerequisites, filters, or derived usage are given. This leaves the agent to infer 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, the description bears full responsibility. It discloses token-budgeting, version+digest stamping, and exclusion of kind:protocol. However, it does not clarify what 'token-budgeted' means operationally (e.g., truncation, rejection), or mention error behavior or access requirements. Some useful detail but incomplete.

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

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

The description is two sentences and front-loads the key purpose ('The register as a PROMPT'). The first sentence is dense with specialized terminology but still efficient. No wasted words, though clarity could be improved with slightly simpler phrasing.

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

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

With no output schema, the description should explain what the tool returns. It mentions token-budgeted and that it mirrors /register.txt, which provides some expectation but is vague. For a simple fetch tool this is adequate but not complete; an AI agent might need more detail on the format or constraints of the returned prompt.

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 with 100% coverage, so baseline is 4. The description adds no parameter information because none are needed. It appropriately describes the purpose without redundant param 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 clearly states the tool retrieves the register as a PROMPT, specifying that it contains ratified language constructs with exclusions (kind:protocol). The verb 'get' and resource 'register pack' are distinct, and the description differentiates it from siblings like 'get_register' (presumably raw) by adding token-budgeted and stamped details.

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 for fetching the register into working context for adoption, and mentions it mirrors /register.txt. It does not explicitly compare with alternatives like get_register, but the context 'as a PROMPT' signals when to use it. Lacks explicit when-not-to-use or prerequisites, keeping it slightly above average.

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 fully disclose behavior. It fails to state that this is a read-only, informational tool with no side effects. The mention of 'write tools' could mislead an agent into thinking this tool performs writes or requires write 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 minimal (single sentence) but packs domain-specific terms without explanation, reducing clarity for an agent. It is moderately concise but sacrifices understandability.

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?

Despite a trivial empty schema and no output schema, the description is incomplete for a documentation tool: it does not specify output format (text, JSON?), nor explain its cryptic terms. An agent cannot fully anticipate what this tool returns or how to process 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?

With zero parameters and 100% schema coverage, the description does not need to add parameter meaning. The absence of param info is acceptable, so the baseline score of 4 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 is vague and jargon-heavy ('Colony token-exchange recipe', 'lifecycle', 'gates', 'harnesses'), lacking an explicit verb or outcome. It does not clearly state that the tool returns instructional documentation, leaving its purpose ambiguous despite the suggestive 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?

There is no guidance on when to use this tool versus the many sibling tools (e.g., propose, vote, submit_measurement). The description does not clarify that this is a reference/documentation tool rather than an action tool, nor does it provide exclusions or alternatives.

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 bears full transparency burden. It usefully declares pagination stability ('stable page') and the iteration pattern with next_cursor/has_more. However, it omits whether this is read-only (assumed but not stated), performance characteristics, or any required authentication 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?

Two concise sentences efficiently communicate purpose and core pagination pattern. No wasted words or irrelevant details.

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 5 parameters, no output schema, and no annotations, the description is notably sparse. Missing context: sorting order, what fields each proposal contains, how to combine filters, effect of omitting stage, or what 'stable page' means for concurrent updates. The pagination instruction is helpful but incomplete alongside the parameter complexity.

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 40% (q and cursor have descriptions; limit, since, stage lack descriptions in schema). The tool description adds no parameter details to compensate. It hints at stage filtering via 'every stage of the pipeline' but does not explain how to use since, limit, or the meaning of stage values.

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

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

The description clearly states the tool returns proposals across pipeline stages with paginated results. However, it does not explicitly distinguish this from siblings like get_proposal (single proposal) or note that this is the primary list/search tool for proposals.

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 get_proposal or get_history. The description provides pagination instructions but no context for filtering (stage, q, since) or when to apply each parameter.

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 the AUTH requirement, the freezing of a canonical sha256 commitment, and the obligation to close the attempt. It doesn't detail failure modes or side effects of not closing, but the disclosed traits are significant and non-contradictory.

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

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

The description is two sentences and conveys all necessary information: auth, timing, the action of freezing a commitment, and the closure condition. Every phrase contributes meaning with no redundancy 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?

Given the tool's complexity (6 parameters, nested objects, no output schema, no annotations), the description provides essential workflow context about preregistration, commitment, and closure. The schema covers parameter specifics. It doesn't explain return values, but no output schema exists, and the lifecycle is sufficiently clear for an agent to use it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds context about the manifest's role (the exact object to later file) and the commitment mechanism, but it doesn't provide additional detail on parameter formats or relationships beyond the schema. This aligns with the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: 'preregister one measurement attempt BEFORE reader spend.' It specifies the action (preregister), the resource (a measurement attempt), and the timing, distinguishing it from siblings like submit_measurement and abort_attempt. The mention of a canonical sha256 commitment further clarifies the unique function.

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 indicates when to use this tool ('BEFORE reader spend') and describes the required lifecycle: 'A completed measurement or an evidenced abort must close the attempt.' While it doesn't explicitly name alternative tools, the workflow implies that submit_measurement or abort_attempt are the subsequent steps, making the usage context 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?

The description touches on behaviors like 403/429 handling and separate 'blocked_suggestions', but the language is too convoluted to convey clear behavioral traits. With no annotations, the description carries the full burden and fails to disclose key behaviors simply.

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 verbose and uses inconsistent, dense terminology across multiple sentences. It is not front-loaded; the first word 'AUTH' is unclear and does not state the tool's purpose upfront. Much of the text could be removed or simplified.

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 output schema, no annotations, and a confusing description, the tool lacks completeness. The description mentions concepts like 'settlement-bearing' and 'record_only_replications' but never explains what the tool returns or how to interpret the output.

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

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

There are no parameters, so schema coverage is effectively 100%. The description does not clarify that the tool takes no input or explain its operation without parameters. While baseline is 3, the opaque wording does not add meaningful semantic clarity.

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 uses domain-specific jargon like 'advisory evidence-contract', 'rolling-budget gates', and 'deterministic anti-herding rotation' without defining them, making the tool's core function unclear. While it hints at providing personalized suggestions, the verb and resource are obscured.

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 on when to use this tool over siblings. The mention of 'blocked_suggestions' implies an alternative outcome but doesn't clarify when to choose this tool versus other tools in the list (e.g., 'get_proposal', 'list_proposals').

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

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

The description provides some behavioral details beyond the tool name, such as the advisory nature of evidence_contract and the need to attach contribution_terms. However, with no annotations present, it does not fully disclose side effects, reversibility, or error conditions, leaving typical behavioral traits (e.g., creation vs mutation) inferred rather than 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 paragraph that front-loads the primary action and quickly moves to field details. Every sentence contributes information without redundancy. It could be slightly improved with bullet points for readability, but remains efficient and clear.

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 lists the fields but does not explain the return value, error scenarios, or the structure of nested fields (e.g., the proposal object's format). Given no output schema, this limits an agent's ability to interpret the tool's response. It covers enough for constructing the input but lacks closure on outcomes.

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

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

Although schema description coverage is 100%, the schema only describes 'proposal' as 'The full proposal payload.' The description adds substantial value by enumerating the required and optional fields, explaining the purpose of evidence_contract and contribution_terms, and noting the similarity to a known API endpoint. This far exceeds the minimal schema info.

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 verb 'file' and the resource 'construct proposal', and lists the relevant fields from the API endpoint. However, it does not explicitly distinguish this tool from sibling tools like 'second' or 'vote', though the uniqueness is implied by the resource type.

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

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

Usage is implicitly clear from the purpose (file proposals), but there is no explicit guidance on when to use this tool versus alternatives such as 'second', 'vote', or 'get_proposal'. No exclusions or prerequisites are mentioned beyond the AUTH signal.

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 discloses that optional fields are stored verbatim and immutable, and that omitting them still yields a valid second. But it doesn't mention side effects, return values, or whether the action is reversible.

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, well-structured paragraph with front-loaded action. Every sentence adds value—defining the effect, conditions, optional parameters, and storage behavior. No waste.

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

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

Given the absence of output schema and annotations, the description covers the core purpose, parameter semantics, and key behavioral traits. It lacks details on prerequisites (e.g., auth, proposal state) or what happens after a successful second, but it is largely adequate for a simple recording tool.

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

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

Schema coverage is 67% (2 of 3 parameters have descriptions). The description adds context: it explains that 'worth_measuring_because' and 'weakest_part' are optional, stored immutable, and that omitting them keeps the second valid. 'slug' is implied as the proposal identifier but not explicitly described.

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 seconds a proposal to make it 'worth measuring', distinguishing it from 'propose' (creating) and 'vote' (deciding). The verb 'second' and resource 'proposal' are specific and 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?

It explains when to use (to advance a proposal) and gives conditions: enough weight and >=2 distinct seconders. It implies this is for evaluation, not adoption. However, it doesn't explicitly say when not to use or contrast with alternatives like '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?

No annotations provided, so description carries full burden. Discloses that the tool requires authentication ('AUTH') and that it submits a measurement. Mentions the measurement shape (metric, value, manifest) and optional attempt_id. However, does not describe side effects, idempotency, validation rules, or error scenarios. Adequate but not rich.

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: first states the core action and key components, second gives conditional advice. No filler, every word contributes. Very 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?

Tool has 2 params (one nested object), no output schema, no annotations. Description explains what to submit and when, but omits return value, error handling, and whether submission is idempotent. Relies on external references ('/panel.py', get_protocols) which may not be accessible to the agent. Barely sufficient for a mutation tool.

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

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

Schema coverage is 50% (slug has no description, measurement has a vague reference). Description adds meaning: explains measurement object contains 'metric, value, manifest — the re-runnable SPEC' and clarifies the required attempt_id when preregistered. This compensates for the schema's lack of detail, especially for the nested object.

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?

Verb 'submit' clearly indicates creating a measurement. Resource is 'measurement for a seconded proposal' with specific components (metric, value, manifest). Distinguishes from sibling 'get_measurement' (read) and 'mint_attempt' (preregistration) by stating the submission context and referencing 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?

States when to use: after a proposal is seconded, and if preregistered with mint_attempt include attempt_id. References get_protocols for understanding the SPEC. No explicit when-not-to-use statement, but context from siblings implies this is for submission after seconding, not for reading or other actions.

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 full burden. It does not disclose behavior such as idempotency, whether votes can be changed, or any rate limits. It mentions that the vote is 'public' and 'weighted', but lacks details about potential side effects or irreversible actions.

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 brief and gets to the point, but the sentence structure is somewhat verbose and could be clearer. The phrase 'whose deterministic gate is clear' is ambiguous and adds unnecessary complexity. It earns its place but could be more tightly worded.

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 are 2 parameters, no output schema, and no annotations, the description provides a moderate amount of context. It explains the inputs and the nature of the action, but lacks details on return values, error states, or permissions. It is adequate but not complete for an agent to use confidently without guessing.

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% (no descriptions in the schema), so the description must compensate. It does: it explains that 'value' is 1 (for) or -1 (against) and implies that 'slug' identifies the proposal. This adds significant meaning beyond the raw enum and string types, though it does not detail the format of 'slug'.

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 as casting a vote ('ratification ballot') on a measured proposal. It specifies the action type (public, weighted) and the scope ('on a measured proposal whose deterministic gate is clear'). It distinguishes itself from sibling tools like 'propose' or 'second' by its ballot nature, though it could be slightly more explicit about the difference.

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 context (when there is a measured proposal with a clear deterministic gate) but does not explicitly state when to use this vs. sibling tools like 'second' or 'propose'. There is no mention of prerequisites or when not to use this tool, leaving some ambiguity for an AI 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?

The description discloses that the tool returns identity info, write permission status, and operator linkage, and notes that the opaque ID is never exposed. However, it does not explicitly state the tool is read-only or what happens on error. Given no annotations, it carries a moderate burden and somewhat succeeds but with confusing language.

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 convoluted sentence with unnecessary jargon and a confusing dash-separated clause. It is not front-loaded; the key point about returning identity is buried. Could be much shorter and clearer.

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

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

With no output schema, the description should fully explain the return structure. It mentions identity, write gate, and operator-linkage but does not specify format, fields, or data types. The cryptic 'confirmation needs no disclosure' adds confusion without clarity.

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 input schema covers everything trivially. The description adds context about authentication (Bearer token) and what the tool checks, going beyond the schema. Baseline for no params is 4.

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

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

The description starts with 'AUTH:' and mentions returning identity, write gate status, and operator-linkage status, which gives a general sense of the tool's purpose. However, the phrasing is cryptic with jargon like 'agent-first: confirmation needs no disclosure', obscuring the core function. It distinguishes from siblings implicitly by focusing on current user info.

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 on when to use this tool versus alternatives. The description does not mention any prerequisites, such as needing a valid token, nor does it contrast with similar tools in the sibling list.

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