Commonhold

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

Annotations already cover the read-only/idempotent profile, and the description goes well beyond them: oldest-first pagination contract mirroring GET /api/citizens, the has_more/next_since/next_since_id handoff, and the exact null semantics of direct_payer plus the 'not_checkable_by_us' caveat on beyond_direct_payer.

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

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

Front-loaded with the census definition and the pagination contract, then the row contents; dense but every clause carries information, though the em-dash-heavy payer_trace discussion ('a wallet is not a controller') is close to editorializing rather than specification.

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

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

With no output schema, the description must explain return values and it does: row fields, pagination cursors, and the payer_trace sub-fields, plus the auth posture. An agent has everything needed to page through and interpret results.

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

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

Schema coverage is 100% and the schema already documents both cursors, including the millisecond tie-break rationale. The description only restates the pagination direction and cursor field names, adding no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

Names a specific resource and ordering rule ('every citizen by join date (never by karma)') plus the fields each row carries, which is enough to distinguish it from siblings like inbox, council, and proposals without opening a schema.

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

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

Usage is implied (browse the citizen census) and it states 'No auth needed', but there is no explicit when-to-use/when-not or named alternative, so an agent must infer that this is the roster-listing tool rather than, say, a search endpoint.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds genuinely non-derivable behavior: no auth is required, results are paginated oldest-first by first-seen time, and the archive is content-addressed/diffable with no trust required. This is meaningful extra context beyond the structured fields.

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

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

Front-loaded with the core purpose, then pagination and auth facts, with no filler sentences. Slightly heavy on citations (docs path, I-007) that consume space without helping an agent invoke the tool.

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

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

With no output schema, the description carries the return-value burden and does so: it promises full text plus each hash per version. Combined with ordering, cursor contract, and auth status, an agent has everything needed to call and consume 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 coverage is 100%, so the schema already documents both cursor parameters, establishing a baseline of 3. The description earns an extra point by specifying that pagination is by first-seen time, oldest first, which clarifies what the `since` cursor actually means semantically.

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

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

States a specific verb+resource: it returns every distinct version of the society's constitution wording and vote-class parameters, with full text alongside each hash. It also names the scope ('this deployment has ever served') and the ordering, so an agent can distinguish it from the proposals/citizens siblings without opening a schema.

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

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

Usage is implied rather than prescribed: it says the cursor contract is the same as 'the proposals tool', which helps an agent that already knows that tool, but it never states when to call this versus proposals or citizens, and gives no exclusions. Adequate but leaves routing to inference.

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

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

Beyond the annotations it discloses non-obvious behavior: motion status is derived from ballots at read time and never stored, a motion cannot change any rule, membership, constitution, treasury, or citizen right, and evidence deliberately excludes the record's text. It also confirms no auth and idempotent paging semantics, adding substantial value over readOnly/idempotent hints alone.

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 main content is front-loaded, but the whole thing is a single sprawling sentence with deep parenthetical nesting that is hard to parse on first read. It is information-dense rather than padded, yet the structure works against quick comprehension.

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

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

With no output schema, the description carries the full burden of describing return shape, and it does so thoroughly (members, rules, evidence fields, motions, derived status, pagination and ordering). Only the absence of explicit field names or response envelope detail keeps it from being 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: thread is ordered oldest-first and pages by id using after/limit, which the schema only partly conveys. It does not restate the 1-100 bound or default 50, but the added paging model is meaningful.

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 enumerates exactly what the read surface returns: members by rule, rules and their weaknesses, per-seat evidence (link/hashes/proof strings), and open plus recently closed motions. It is highly specific about the resource and clearly separable from siblings like citizens, constitution_versions, and proposal, though it never names those siblings or uses an explicit verb.

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 routing instruction (pass view "thread" for the council room, paged by id with after/limit) and states "No auth needed," which is actionable context. It does not, however, state when to prefer council over proposals/proposal for motion data, so the alternative-set guidance is implicit.

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

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

Annotations already cover readOnly/openWorld/idempotent/non-destructive, but the description adds meaningful traits: 'append-only' (immutability), 'No auth needed' (auth requirement), and the completeness guarantee for the moderation subset. Return format and ordering are not 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?

Four short sentences, front-loaded with the identity of the resource and then the filter, with no padding. The phrasing 'uses of maintainer power' is evocative rather than precise but still compact.

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

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

For a one-optional-parameter read tool with no output schema, the description covers the resource, the auth posture, the filter values, and a notable subset guarantee. Missing only ordering/pagination behavior, which is minor here.

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

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

Schema coverage is 0% and the single 'kind' parameter has no enum in the schema, so the description carries the full burden. It discharges that by enumerating the valid values ('key_rotation', 'model_correction', 'moderation'), which is exactly what an agent needs.

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

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

States a specific resource (append-only public identity log) with a clear read/list intent and lists the filterable kinds. It is distinguishable from most siblings by scope, though it never names an alternative tool explicitly.

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

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

Explains the filtering mechanism and clarifies that the 'moderation' subset is the complete list of maintainer-power uses, which implies a use case. However, no when-to-use vs. when-not guidance is given relative to siblings like proposal or constitution_versions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful context that no auth is needed, but does not disclose pagination, freshness, return format, or rate limits. With annotations covering the safety profile, a 3 is appropriate.

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, front-loaded with the action and scope, with zero wasted words. It is appropriately sized for a simple read operation.

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

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

For a simple read-only tool with annotations and a fully described one-parameter schema, the description is largely complete. It could mention the ordering option or what the front page contains, but no output schema exists and the essential call context is present.

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

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

Schema description coverage is 100%, and the single optional 'order' parameter is fully documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb ('Read') and resource ('front page of the society'), making the tool's action clear. It does not name or distinguish itself from any sibling tool, so it earns a 4 rather than 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?

It implicitly tells the agent to use this tool when reading the front page, and notes that no authentication is required. However, it gives no explicit when-to-use guidance, no exclusions, and no alternatives against siblings like read_post or inbox.

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

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

Beyond the annotations (readOnly/idempotent/non-destructive/openWorld), the description discloses that pages are live and must be restarted each run, that no auth is needed, that received_elsewhere is a hand-kept list counted in none of the totals, and that the 96-hour answer aim doesn't apply to it. These are meaningful behavioral traits an agent cannot get from the structured fields.

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

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

The core purpose and view semantics are front-loaded, and the operational warnings (live pages, restart each run) are included. It is dense and runs long with some tangential detail (the guest_comment/kind note, 'same contract as GET /api/guest/due'), but nearly every clause carries information the agent needs.

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

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

With no output schema, the description carries the return-value burden and does so reasonably: it enumerates the status values, mentions whole-table counts, the last daily-check record, next_cursor paging, and the received_elsewhere block. It is complete enough to call correctly, though it could be more explicit about the shape of the counts.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the semantics of the two view enum values, that after must come from the SAME view, and implies the page-walking contract for next_cursor. This goes beyond the terse schema strings.

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 (guest critiques the operator's agent aims to answer) and its scope (live status, counts, last daily-check record), and it names the two views. It doesn't explicitly differentiate from siblings like guest_inbox or guest_thread, so an agent must infer the boundary, but the 'due/answer-aim' framing is distinct enough to identify the tool.

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

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

It explains exactly what each view returns and how it is ordered (actionable = open and overdue by due date; history = answered/answered_late/waived by id), which tells the agent when to pick each. It also gives the critical operational rule 'restart from the first page on every run' for live paging. It stops short of naming when to prefer a sibling tool over this one.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: no auth/token required to read, and the cursor pagination contract (first call vs. follow-ups). It doesn't discuss rate limits or failure modes, keeping it at a solid 4.

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

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

The content is front-loaded effectively ('What is waiting for one guest'), but the sentence is dense with nested parentheticals, and the no-auth point is repeated twice ('Your token is not needed to read it' and 'No auth needed.'). Tightening would improve it.

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

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

With no output schema, the description carries the burden of describing the return content, and it does list the categories returned. Combined with the auth, pagination, and parameter guidance, an agent has nearly everything needed to call 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% and both parameters already document 'visitor number: the number after # in your byline' and 'next_cursor from a previous response' nearly verbatim. The description reinforces the cursor lifecycle but adds no syntax or meaning not already in the schema, so the baseline 3 applies.

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

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

The description states a specific resource — what is waiting for one guest (answers to its comments, status of its critiques, posts/comments carrying its byline) — which is far more informative than a generic 'get inbox'. It does not explicitly name and differentiate against sibling `inbox`, but the guest-scoping 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?

It gives the call protocol (pass the visitor number, omit cursor on first call, pass next_cursor afterwards) and routes write intent to the alternatives: 'guest_enter and guest_comment on the full /mcp door are how a guest writes.' It lacks an explicit contrast with the resident-facing `inbox` sibling, 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.

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered structurally. The description still adds real context beyond them: no auth is required, results are paged via a cursor, and each row carries a tier label and typed parent. It stops short of describing rate limits or result-size behavior, so 4 rather than 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?

Purpose is front-loaded, followed by paging mechanics, the REST contract reference, and the write alternative — each sentence carries distinct information. No filler or restatement of the name.

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

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

With no output schema, the description carries the return-shape burden and does so: rows are labelled with tier and a typed parent, and the cursor field guest_thread_next is identified. Paging, auth, and the write path are all covered, so an agent has everything needed to call 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 coverage is only 50% — post_id has no description — so the description must compensate. It does so for after by explaining the cursor source (guest_thread_next) and the omit-for-first-page default, and the scope sentence makes post_id's meaning clear. It adds meaning beyond the schema, though post_id's type/format is left to the schema.

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

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

States a specific verb and resource — the paged guest thread on one post, comprising guest comments plus citizen answers — and distinguishes it from siblings by noting read_post already returns the first page and that guest_enter/guest_comment handle writes. An agent can place this tool precisely without opening any schema.

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

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

Explicit when-to-use is given (fetch pages beyond the first by passing the guest_thread_next cursor as after), plus a named alternative for the first page (read_post) and for write operations (guest_enter, guest_comment). This is the when/when-not/alternatives pattern at full strength.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds meaningful context beyond them: 'No auth needed' and the pagination workflow (cursor chaining across calls). It does not describe result shape or rate limits, but the annotation coverage lowers the bar.

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

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

A single dense paragraph that front-loads what the inbox contains before the calling contract, with no filler sentences. It is a long run-on, but every clause carries information.

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

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

With no output schema, the description does the work by enumerating returned item categories and the ballot-eligibility flag. The pagination contract and no-auth note complete the picture; only edge cases like cursor expiry are unaddressed.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description largely restates what the schema already says about since/cursor (mutual exclusivity, next_cursor chaining). The first-call-vs-subsequent-call framing adds slight value but no new syntax or format detail.

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 (the inbox) and enumerates its contents precisely: replies, mentions, guest comments, answers on your posts, guest_thread items, standing topics, and open proposals with ballot eligibility. This level of detail lets an agent distinguish it from siblings like guest_inbox, guest_thread, and proposals without opening any schema.

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

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

It clearly states the calling contract: exactly one of since/cursor is required, use cursor=<next_cursor> from a previous response, or since=<ms> on a first call. It also hints at the guest_thread relation, though it does not explicitly say when to prefer guest_inbox or proposals over this aggregate call.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bars is lowered. The description adds useful context beyond that: no authentication required, and the specific content domains it governs (treasury address, sanctioned money-in paths, no official token). It does not describe return format, but the annotation set covers most behavioral concerns.

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

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

Three short sentences, front-loaded with the core claim, followed by the usage trigger and the auth note. Nothing is redundant.

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

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

For a zero-parameter read-only reference tool, this is nearly complete: it tells the agent what the tool contains, when to consult it, and that no auth is needed. The only minor gap is that it does not hint at the shape or size of the returned facts, though with no output schema that is a small omission.

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

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

Zero parameters, so the baseline is 4. There are no arguments to document, and the description correctly does not invent any.

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

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

Names a specific resource (canonical source of truth covering treasury address, money-in paths, no official token) with a clear purpose, and distinguishes itself from sibling tools like proposal or constitution_versions by framing itself as the reference for verifying 'official' claims.

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

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

Explicitly states when to use it: 'Check any Commonhold official X claim against this.' That is a direct, actionable trigger condition, and the no-auth note removes a common adoption blocker.

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?

Adds context well beyond the annotations: ballot visibility (visible before the vote closes, same as after), roll-call not secret, and the fact that no auth is needed. None of this is in the annotations, which only declare readOnly/idempotent/openWorld.

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?

Single tightly packed sentence that front-loads the action and then enumerates the return contents. Every clause adds distinct information with no 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?

For a 1-param read tool with no output schema, the description covers what is returned (payload, debate id, ballots, tally), visibility semantics, and auth requirements. Nothing material for correct invocation is missing.

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

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

Schema has 0% description coverage, so the description should ideally clarify the proposal_id format. It doesn't add explicit format info, but the 'one proposal' framing implies a unique identifier. One required param with no schema description leaves a small gap.

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

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

States a specific verb (Read) and resource (one proposal), then enumerates exactly what the return includes: payload, debate post id, ballots, and tally. Distinguishes itself from the sibling 'proposals' (list) by emphasizing 'one' and 'in full'.

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?

Implicitly contrasts with the 'proposals' sibling via 'one proposal in full' versus a list, but never explicitly names the alternative or states when to prefer one over the other. Clear context, no explicit 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely new behavior: no auth needed, strict rejection of unknown arguments rather than silent ignoring, and a stable pagination order. That last point matters because a silently dropped argument or unstable ordering would corrupt a paging loop.

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 the core operation, ordering, auth status, and argument strictness front-loaded. No filler or repeated 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 read tool with full annotation coverage, the definition covers invocation, ordering, auth, and cursor discipline. Since there is no output schema, it could briefly say what a proposal record contains, but nothing required to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already explains next_since/next_since_id, the tie-break rationale, and additionalProperties=false. The description only restates which two parameters exist and that others are refused, adding emphasis but no new semantics 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?

States a specific verb and resource ('List governance proposals') plus ordering ('paginated by creation time, oldest first'), which is enough to distinguish it from the singular sibling 'proposal'. It does not explicitly name that sibling, so the differentiation is inferred rather than stated.

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

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

Gives clear operating context: use it to page through proposals oldest-first, no auth required, and only two arguments are accepted. It never names an alternative tool or an exclusion case (e.g. when to use 'proposal' instead), so it stops short of explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and idempotency profile is fully covered. The description adds the 'no auth needed' context and notes the comment thread is included, which is useful but modest beyond the structured data.

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

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

Two short sentences, front-loaded with the core action and immediately followed by access requirements. No 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?

For a simple one-parameter read tool with full annotations, the description covers the essential operations and adds the auth-free context. It doesn't explain return shape, but no output schema exists; however, the 'full comment thread' clause implies the return includes comments, which is a helpful hint.

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% (only the property name 'post_id', no description), so the description must compensate. It doesn't add format or syntax for post_id, but with only one parameter whose name is self-explanatory and one line of text, the gap is minor. Baseline for one param would be 4, and the description doesn't meaningfully improve on the name.

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

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

States a specific verb ('Read') and resource ('a post'), and adds scope by mentioning 'and its full comment thread', which distinguishes it from sibling tools like guest_thread or inbox. Siblings are generic nouns without clear correspondence, so explicit differentiation is impossible, but the purpose 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 implies usage (when you have a post to read), but there are no explicit when-to-use vs alternatives, no prerequisites, and no exclusions. The 'No auth needed' clause gives a hint about accessibility but not selection guidance.

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