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

Beyond the readOnly/openWorld annotations, the description discloses the data source (on-chain logs, no third-party indexer), that results are filtered against live contract state, and that full proposal descriptions are returned. It's missing any note on cost, rate limits, or scan size, which matters for an unbounded log scan.

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 mechanism, then the no-indexer guarantee, then applicability. Mostly earns its space, though the Tally-shutdown justification is closer to marketing rationale than invocation 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 usefully states the return shape (full proposal description) and the compatibility surface (OpenZeppelin Governor, Compound Bravo). For a three-parameter read tool this is largely sufficient; result size or pagination behavior is the remaining gap.

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

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

Schema coverage is 100%, so governor, states, and lookback are already documented, including the default state set and the lookback derivation rationale. The description's mention of 'filtering by the contract's live state' loosely ties to the states parameter but adds no syntax or behavior 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 ('discovers proposals by reading ProposalCreated logs straight from a Governor contract') and explains the filtering mechanism. It doesn't differentiate itself from the near-identically named sibling governor_list_proposals, which an agent would also consider.

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 'supported way ... Tally shut down in March 2026' line implies when to prefer this tool, and the compatibility note scopes its applicability. But it never explicitly contrasts with governor_list_proposals or governor_get_proposal, so the agent must infer which sibling to pick.

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 only say readOnly and open-world; the description adds the decisive fact that the upstream service is gone, plus an implicit hint that this path may need an API key while the alternatives do not. It doesn't say what a call actually returns now (error, timeout, stale cache), which is the remaining gap.

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

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

Two sentences, zero waste, with the depreciation warning front-loaded before the redirect. Every clause carries operational value.

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 dead legacy endpoint the agent needs the deprecation notice and the exit path, both of which are present. What's missing is the failure mode on invocation and whether historical tallies are recoverable elsewhere.

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 documents tallyId, onchainId and the governorId-alongside-onchainId constraint. The description adds no parameter guidance, 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?

States a specific verb and resource (fetches a proposal's title, description and tallies) and pins the source (Tally-compatible hosted API). Explicitly separates it from governor_find_proposals and governor_proposal_state, so an agent can route 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?

Gives an explicit when-not (the backing API shut down in March 2026) and names two concrete alternatives with the axis to choose between them (description vs. live on-chain state). The 'prefer X for Y' mapping leaves nothing 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?

Annotations only say readOnly and openWorld; the description adds the crucial facts that this hits an external hosted service that may be dead and that an API key may be required — context not available in structured fields. It stops short of describing response shape or pagination, but for a deprecated read-only list tool that is a minor gap.

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

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

Three tight sentences, front-loaded with the legacy status and ending with the actionable alternative. No filler, though the deprecation notice is nearly repeated via 'Tally shut down' and 'Legacy path'.

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

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

It covers the important migration/deprecation and auth context, but with four parameters, only half documented, and no output schema, the description leaves the agent without guidance on what the proposals response looks like or how limit/organizationId interact. Adequate for steering away, incomplete for actually calling 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 only 50% and the description mentions no parameters at all. The two undocumented parameters (limit, organizationId) and the Tally id format get no compensating explanation, so an agent must infer usage from the schema alone.

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

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

Names the specific verb+resource (lists proposals) and the specific backend (Tally-compatible hosted API), and immediately labels it legacy, which separates it cleanly from governor_find_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?

Explicitly states to prefer governor_find_proposals because it reads the contract directly and needs no API key, plus the condition under which this path fails (Tally shut down, now Cactus). When-to-use and when-not-to-use are both present.

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 readOnlyHint and openWorldHint already declared, the description adds real value by revealing the read source (reads the Governor contract directly) and that no API key is needed, which is important auth/routing context. It doesn't cover failure modes or rate limits, but that's minor against the 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?

Two sentences, front-loaded with the operation and its returned fields, then the usage cue and auth note. Every clause earns its place with no filler.

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

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

There is no output schema, but the description compensates by enumerating the returned values (state, voted status, voting power, quorum, tally). Combined with the schema-documented inputs and annotations, an agent has everything needed to call and interpret 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?

Schema description coverage is 100%, so governor, proposalId, and decimals are already documented in the schema. The description adds no parameter-level detail beyond what structured data provides, so the baseline of 3 applies.

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

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

States a specific verb (reads) and resource (the Governor contract for a proposal) and enumerates exactly what is returned: state, Safe's voted status, voting power at snapshot, quorum, and running tally. This distinguishes it functionally from siblings like governor_get_proposal or governor_list_proposals, though it does not name them 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?

Gives clear timing guidance with 'Call this before voting,' which tells the agent when to invoke it. It does not name an alternative tool or state when not to use it, so it falls short of the explicit alternatives-based 5.

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

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

Annotations already mark this as a non-read-only, non-idempotent, open-world operation. The description adds material context beyond that: it is a real on-chain transaction, costs gas, and is irreversible. It does not mention the return/confirmation format, but there is no output schema to defer to.

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

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

Two tight sentences with zero waste. The irreversible-transaction warning is front-loaded and the prerequisite follows, making the key facts easy to scan.

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 gas-costing, irreversible mutation with no output schema, the description covers the essentials: mechanism, cost/irreversibility, and preconditions. Minor gaps remain (e.g., what skipChecks does behaviorally, expected confirmation behavior), but the schema handles the parameter-level caveats.

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

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

Schema coverage is 100%, so each parameter (including reason's gas cost note and skipChecks' fork caveat) is already documented in the schema. The description only alludes to castVoteWithReason, adding no detail beyond the structured fields, 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?

States a specific verb (votes) and resource (Governor) and names the exact mechanism (castVoteWithReason from the Safe). This clearly distinguishes it from the snapshot_vote siblings, which operate off-chain.

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

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

Explicitly routes the agent to governor_proposal_state first and states the preconditions (proposal Active, Safe has voting power). A clear prerequisite plus the named check tool leaves little 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutating nature is already known; the description adds real value by disclosing the threshold mechanic and that execution can occur on-chain as a result. It omits permission/ownership requirements and expected failure modes, which for an on-chain-signing tool would be worth stating.

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 action and its consequence; no redundant restatement of the name or title.

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

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

No output schema exists, and the description conveys the meaningful outcome (threshold reached → executed) well. It does not describe what is returned or how a below-threshold signature is reported, leaving a modest gap for a single-parameter 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?

Only one parameter, with 100% schema coverage that already describes the hash format and points to safe_pending_transactions as its source. The description adds no further parameter detail, 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?

States a specific verb and resource ("adds the agent's signature to a queued Safe transaction") and immediately explains the consequence (threshold execution on-chain). This distinguishes it from the listing sibling safe_pending_transactions, which the schema names as the source of the hash.

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

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

"Use this to help along a vote that was proposed but not yet executed" gives a clear usage condition. It does not explicitly state exclusions (e.g., don't call when already executed or when the agent isn't an owner), so it falls short of a full when/when-not/alternatives treatment.

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 and openWorldHint, so the description's job is to add operational meaning — and it does: the agent's own ETH balance is the gas source for on-chain votes, while Snapshot votes are gasless. It also surfaces the execution-authority fact (sole owner vs. needing confirmations), which materially affects downstream tool choice.

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

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

Three tight sentences, each carrying distinct information: return fields, gas semantics, invocation priority. Slightly suboptimal that the most actionable instruction ('Call this first') is buried at the end rather than front-loaded.

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

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

With no output schema and no parameters, the description must carry the return-value burden itself, and it does by enumerating every reported field. It also supplies the interpretive context (what the balances mean for voting) that an agent needs to act on the result.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline for zero params is 4. Nothing in the description misleads about inputs.

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 verb ('Reports') and a precisely enumerated resource: chain, owners, threshold, nonce, both ETH balances, and whether the signer key is a sole-executing owner. The scope is clearly a read-only configuration/readiness check, which separates it from siblings like safe_pending_transactions and safe_confirm_transaction.

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

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

'Call this first' gives an explicit ordering instruction that tells the agent when to reach for it relative to the rest of the Safe/Snapshot workflow. It also explains the gas distinction that determines whether on-chain voting is even viable. It stops short of naming a concrete alternative or a when-not-to-use condition.

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 and openWorldHint=true, so the safety and external-service profile is covered. The description adds that the source is the Safe Transaction Service, which is useful, but says nothing about authentication requirements, pagination, result limits, or how the endpoint is scoped (which Safe or network).

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

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

A single front-loaded sentence with no filler. The resource and qualifying state both appear before any subordinate clause, so the key information survives a truncated read.

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 parameters and no output schema, the description carries the full descriptive burden, yet it never says which Safe or network the results belong to, nor what a returned entry contains or how many come back. For a zero-argument list tool scoped to an external service, that scope ambiguity is a real gap an agent may trip over.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it doesn't waste words on parameter 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?

Specific verb (Lists) plus a well-defined resource (transactions queued on the Safe Transaction Service) with a state qualifier: waiting for confirmations or execution. That state qualifier distinguishes it from a generic transaction history or from safe_confirm_transaction. It stops short of naming a sibling, so it is 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?

The word 'queued' plus 'waiting for confirmations or execution' implies the use case (finding transactions that still need action), but no explicit when-to-use, when-not, or alternative is stated. An agent could reasonably infer it should call this before safe_confirm_transaction, but that inference is left unstated.

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 and openWorldHint=true, so safety is covered. The description adds real value by disclosing the returned contents — body text, voting system, indexed choices, current scores, and the Safe's voting power — which matters since there is no output 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?

One sentence, front-loaded with the action and payload, ending with the actionable usage cue. No filler.

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

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

With no output schema, the description carries the return-value burden and does so well by listing the fields an agent will get back. It omits edge behavior (invalid/unknown proposalId, missing proposal), which keeps it just short of 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 coverage is 100% and the single proposalId parameter is documented as a 0x… hash in the schema. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetches a Snapshot proposal in full') and enumerates the payload fields, so an agent knows exactly what it retrieves. The 'in full' framing implicitly separates it from siblings like snapshot_list_proposals, but no sibling is named 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?

'Read this before voting' gives a concrete usage condition tied to the voting workflow. It stops short of naming alternatives (e.g., snapshot_list_proposals for discovery), so selection between siblings still requires 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds two useful behavioral facts (sort order and default state filter) but says nothing about result volume, pagination behavior, or what a proposal record contains.

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

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

Two tight sentences, no filler, with the resource and ordering front-loaded ahead of the default-behavior note. Every clause earns its place.

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

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

A simple three-parameter read tool with no output schema, so the bar is modest. Still, an agent gets no signal about whether 'limit' caps the page or total results, and no sense of the returned shape, which the description could cheaply have supplied.

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% — the space id and state enum are documented in the schema, and the description usefully restates that the default state means 'open for voting'. The limit parameter (default 10, max 50) is not explained in either place, so the description only marginally improves on 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 ('Lists proposals in a Snapshot space') plus ordering ('newest first'), so the core action is unambiguous. However, it never distinguishes itself from close siblings like snapshot_open_proposals or snapshot_query, which an agent must choose between.

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?

'Defaults to proposals that are currently open for voting' implies the default filter behavior but gives no explicit when-to-use or when-not-to-use guidance. With snapshot_open_proposals and snapshot_query in the sibling set, a routing sentence is conspicuously absent.

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 and openWorldHint, so the safety profile is covered; the description adds real value beyond them by disclosing sort order (soonest deadline first), the per-proposal inclusion of the Safe's voting power, and the implicit 'all spaces with voting power' default. It does not explain truncation/pagination behavior, which is a gap given a per-space limit exists.

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

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

Two sentences with the scope and ordering front-loaded, followed by the routing hint. No filler, and every clause carries information an 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 readOnly/openWorld annotations but no output schema, the description does the right work by describing what is returned (open proposals with the Safe's voting power, deadline-ordered). The remaining omission is pagination/cap semantics for limitPerSpace, which matters for a zero-required-param list 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 only 50%: `spaces` is documented in the schema but `limitPerSpace` (default 20, max 50) has no description anywhere. The description's 'across every Snapshot space the Safe holds voting power in' hints at the default filtering behavior of `spaces`, but it never mentions restricting spaces or the per-space cap, so it does not compensate for the coverage gap.

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

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

States a specific verb (Lists), resource (open proposals for voting), and precise scope (every Snapshot space the Safe holds voting power in), plus ordering (soonest deadline first) and payload (the Safe's voting power). This clearly separates it from generic siblings like snapshot_list_proposals and snapshot_query.

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

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

Explicitly frames the tool as 'the whole of the Safe's Snapshot ballot' and prescribes the next step: use it to decide what needs a vote, then snapshot_get_proposal to read one. It lacks an explicit when-not statement (e.g., versus snapshot_list_proposals or snapshot_query), which keeps it short of a 5.

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

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

Adds substantial behavior beyond annotations: only query operations are allowed, responses over 1 MB are refused, and results over 50k characters are truncated. Annotations already declare readOnly/openWorld, but the response-size and operation-type constraints are valuable 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?

Front-loaded with the core purpose, then constraints and schema reference in a compact paragraph. Every sentence earns its place by clarifying scope, limits, or safe usage.

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?

Complete for an open-ended GraphQL query tool with no output schema: it explains allowed operations, size limits, truncation behavior, pagination guidance, and points to the external schema reference. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the query and variables parameters are already documented. The description adds meaningful usage semantics beyond the schema: use first/skip, select only needed fields, and keep responses within size limits.

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 — runs GraphQL queries against the Snapshot hub API — and enumerates the domains it can query. It explicitly positions itself as the fallback for questions the fixed read tools do not cover, distinguishing it from sibling read 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?

Gives explicit when-to-use guidance: for questions the fixed read tools do not cover, with concrete examples. It also gives when-not guidance by stating that mutations and subscriptions are rejected, and recommends pagination/field selection.

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 and openWorldHint, so the description is not obligated to restate safety, yet it usefully discloses the three discovery sources (configured spaces, followed spaces, prior votes), which explains why the tool is open-world and potentially slow. Return shape and cost/latency are left unstated.

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

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

Two tight sentences, front-loaded with the outcome and followed by the call-to-action condition; no filler or redundancy.

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

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

For a zero-required-parameter, read-only discovery tool with no output schema, the description conveys enough to invoke it correctly, though it never sketches what the result set looks like (space ids, names, voting power values).

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 both parameters are fully documented in the schema and the baseline of 3 applies. The description only hints at the 'spaces' parameter via 'on top of the ones discovered automatically' and never mentions includeZero.

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 ('Finds') and a precisely scoped resource ('every Snapshot space where the Safe holds voting power'), and the phrase 'without needing a list up front' separates it from sibling tools like snapshot_voting_power that require a known space id.

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?

'Start here when you do not know where this Safe votes' gives an explicit entry-point condition, but there is no complementary when-not guidance (e.g. use snapshot_voting_power when the space is already known) beyond the implied contrast.

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 write (readOnlyHint=false), non-destructive, open-world. The description adds real context beyond them: this operates on a pre-existing Safe message rather than creating one, and the typical reason it is needed is a signature shortfall. It stops short of saying what happens if the message was already submitted or whether the call is safely repeatable.

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

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

Two sentences, no filler, and the state that makes the tool necessary is front-loaded before the parameter instruction. Every clause earns its place.

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

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

For a single-parameter submission tool with no output schema, the description covers the precondition and input origin well. It leaves minor gaps: what a successful call returns and how it behaves on a message that was already submitted, which an agent might want before retrying.

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?

Only one parameter and schema coverage is 100%, so the schema already documents the format and origin of safeMessageHash. The description restates that the hash comes from snapshot_vote without adding syntax, validation, or lifecycle detail, 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?

States a specific verb (finishes/submits) and resource (a vote whose Safe message already exists), and scopes it to the incomplete-signature case. This cleanly separates it from snapshot_vote, which is where the message is originally created.

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 trigger condition clearly: the Safe message was created earlier but not submitted, usually due to missing owner signatures. It implies snapshot_vote is the originating call and that this is the recovery path, though it never explicitly says 'do not use this to start a new vote.'

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

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

Annotations declare this is a non-read-only but non-destructive, open-world operation; the description adds real context beyond that: it is gasless, requires a Safe EIP-1271 signature round-trip, goes to the Snapshot sequencer, and a repeat call silently replaces the prior vote. Failure modes and timing of the signature wait are not described, keeping it below a 5.

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

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

Four sentences, front-loaded with the action and its mechanism, then the prerequisite, then the replacement caveat. No filler.

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

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

For a mutation tool with no output schema, the description covers the signing flow, prerequisite lookup and re-vote semantics, which is enough to call it correctly. What an agent gets back on success/failure, and how long the signature wait may take, are unstated.

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 baseline is 3; the description adds genuine meaning by tying the meaning of 'choice' to the proposal's voting system and directing the agent to inspect the proposal before choosing an index. It does not restate the choice shapes, but the schema already does.

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 and mechanism: casts an off-chain gasless Snapshot vote on behalf of the Safe via EIP-712/EIP-1271. An agent can distinguish this from sibling vote tools like snapshot_x_vote or snapshot_submit_pending_vote because the signing path is spelled out.

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

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

Gives an explicit prerequisite: read the proposal with snapshot_get_proposal first so the choice index and voting system match. It also clarifies the re-vote case (voting again replaces the earlier vote). It stops short of routing the agent away from the other sibling vote-submission tools, so no explicit 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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavior context by explaining that results are broken down by strategies and that zero means the vote carries no weight, but it does not discuss data freshness, required auth, or failure behavior.

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

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

Two short sentences, front-loaded with the core purpose and followed by a decision-relevant caveat. There is no redundant or wasted text.

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 query, the description gives enough to understand the high-level output: voting power broken down by strategies. However, with no output schema and no parameter documentation, it leaves out return-value shape, parameter formats, and any error or edge-case behavior.

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

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

Schema description coverage is 0% for both required parameters, so the description must compensate. It barely does: it implies that 'space' refers to the space whose strategies are used and that 'proposalId' identifies the proposal, but it gives no format, naming, or lookup guidance for either parameter.

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

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

The description states a specific verb and resource: it reports the Safe's voting power on a specific Snapshot proposal, broken down by strategies. This clearly distinguishes it from siblings like snapshot_vote (casting a vote) and snapshot_spaces_with_voting_power (listing spaces).

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

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

Usage is implied by the zero-power note, which helps an agent decide whether a vote would matter, but the description never explicitly says when to use this tool rather than snapshot_vote or snapshot_get_proposal. No alternatives or exclusions are named.

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 flag this as destructive, non-idempotent and open-world, but the description adds real context beyond them: execution behavior varies by Safe threshold (immediate at 1, queued with to/data/value above that) and the final signer's confirmation executes it. It doesn't cover failure modes or whether a cancel can be undone on-chain.

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, front-loaded with the core action and mechanism. The WalletConnect aside and the threshold explanation are dense but each earns its place; the final sentence carries several clauses that could be split.

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

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

No output schema exists, yet the description covers the outcome (immediate execution vs. queued Safe transaction) and the key precondition, which is everything an agent needs to know before invoking a destructive on-chain tool. Schema covers the parameters fully.

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 space, proposalId, reason and skipChecks, including the URL-omits-proposalId rule. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Cancels (vetoes) an on-chain Snapshot X proposal') plus the exact on-chain call it makes (Space.cancel(proposalId) from the Safe). This clearly separates it from siblings like snapshot_x_vote, snapshot_x_proposal, and safe_confirm_transaction.

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 a hard precondition ('Only works when the Safe is the space controller') and positions itself against the manual WalletConnect alternative. It stops short of naming sibling tools (e.g. safe_pending_transactions for queue follow-up, snapshot_open_proposals to find the id), so it is clear but not fully routed.

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 and openWorldHint=true, so safety is covered; the description adds meaningful behavior beyond that, namely that data is read on-chain from the space contract, that voting power is evaluated at the proposal's snapshot block, and that Safe-specific state (already voted, is space controller) is included. It says nothing about RPC failures or staleness of 'live status', which keeps it from a 5.

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

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

Two sentences, front-loaded with the verb and source, then the returned data, then the workflow. Every clause carries information an agent would otherwise have to infer.

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

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

No output schema exists, and the description compensates by listing the returned fields (status, tally, snapshot-block voting power, voted flag, controller flag). Combined with the schema's parameter documentation and the read-only annotations, an agent has everything needed to call and interpret this 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 description coverage is 100% and both parameters are documented in the schema, including the address / prefixed-id / URL forms of `space` and the URL-implies-no-proposalId rule. The description only echoes 'from its space contract' and adds 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?

States a specific verb and resource ('Reads a Snapshot X (snapshot.box) proposal straight from its space contract') and enumerates exactly what information comes back, so the agent knows the payload without opening a schema. It distinguishes itself functionally from the write siblings it names, but never explicitly contrasts with the confusable read siblings snapshot_get_proposal / snapshot_query.

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 a concrete call sequence: use before snapshot_x_vote or snapshot_x_cancel_proposal, and again afterwards to confirm the vote landed or the proposal shows Cancelled. That is real when-to-use guidance, though there are no exclusions and no routing advice against the other proposal-reading 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?

Adds substantial context beyond the annotations: on-chain, costs gas, final, Snapshot X forbids changing a vote, strategies resolved automatically, and the vote is simulated from the Safe before signing. This tells the agent the irreversibility and pre-flight behavior that the hint flags alone (non-idempotent, non-destructive) cannot convey.

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

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

Five tight sentences with no filler; the action, mechanism, and irreversibility warning are front-loaded and the read-first prerequisite closes 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?

Covers mechanism, cost, finality, and simulation for an 8-parameter mutation with no output schema. The remaining gap is what happens after submission — whether this executes immediately or becomes a pending Safe transaction needing co-owner confirmation, which the sibling safe_pending_transactions/safe_confirm_transaction tools suggest is relevant.

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 every parameter is already documented, and the description adds only the note that strategies are resolved automatically (relevant to strategyParams) and that skipChecks exists for broken forks. Baseline 3 applies since the schema does the heavy lifting.

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 ('Votes For, Against or Abstain on a Snapshot X proposal as the Safe') and immediately explains the mechanism (EthTx authenticator → Space.vote with the Safe as voter). The gasless EIP-712 contrast distinguishes it from the off-chain sibling snapshot_vote.

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

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

Explicitly says to read the proposal with snapshot_x_proposal first, and explains that this is the path for smart-contract wallets because a Safe cannot produce a gasless signature — which implicitly tells the agent when to prefer it over the gasless vote path. It does not name snapshot_vote as the excluded alternative outright.

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 and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: results are newest-first and include the vote choice and reason. It does not discuss pagination or auth requirements, keeping it below a 5.

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

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

Two tightly written sentences with no wasted words. The purpose and ordering are front-loaded, followed by the usage rationale.

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 read-only tool with annotations and no output schema, the description covers purpose, return content, and when to use it. However, with five optional filter parameters and low schema coverage, the description leaves too much unexplained about how to target a specific proposal, platform, outcome, or result limit.

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 20%, with just the 'venue' parameter documented, so the description needs to compensate. Instead it provides no guidance on limit, outcome, platform, or proposalId, leaving most filter semantics undocumented.

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

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

The description states a specific verb and resource: it returns votes this Safe has already cast through Safe-MPC. It also specifies ordering ('newest first') and returned content ('choice and the reason'), which distinguishes it from mutation siblings like snapshot_x_vote or governor_vote.

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

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

It gives clear usage context: read it before deciding so the Safe votes consistently with precedent, and to check whether a proposal has already been handled. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description is free to add real value — and it does, by disclosing the external dependency on safe-mpc-watch and the critical gotcha that an empty result may mean the watcher isn't running rather than no pending items. Return shape is not described, but with a simple list output that is a minor omission.

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

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

Two sentences, no waste, and the core purpose is front-loaded ahead of the operational caveat. Nothing could be cut without losing 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?

Purpose and the empty-result caveat are covered, but for a tool whose only knob is a six-value status enum, leaving that filter entirely unexplained is a real gap. No output schema exists, so a brief note on what a queued entry looks like would also have helped.

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

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

Schema description coverage is 0% and the single status parameter (pending/dispatched/voted/failed/expired/all) is never mentioned in the description. The phrase 'which are due now' hints at the default pending view, but the agent gets no explanation of what each enum value filters, which is the one thing the description needed to compensate for.

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

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

States a specific verb and resource — a read of the watcher's queued vote schedule — plus what each entry contains (due time, due-now flag). It is distinguishable from vote_log by being a forward-looking queue rather than a historical record, though no sibling is named 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?

Implied usage is clear (inspect the pending queue before a decision), and the note about safe-mpc-watch gives useful context. But there is no explicit when-to-use vs vote_log or snapshot_pending_vote siblings, and no guidance on when to prefer each.

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