SettleIt

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

Annotations already declare non-read-only, non-destructive, idempotent, open-world. The description adds two things annotations cannot convey: the admin_token is required for authorization, and existing results are retained rather than removed. It stops short of saying what happens when closing an already-closed decision or whether in-flight responses are accepted.

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 terse sentences, zero filler, with the primary effect stated first and the auth prerequisite last. Nothing could be removed 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?

For a two-parameter mutation with no output schema, the description covers effect, data retention, and auth. Minor gap: no statement of the error condition when the decision is already closed or of what a successful response returns.

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

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

Schema description coverage is 100%, so both parameters (admin_token provenance, decision_id accepting an id or SettleIt link) are already documented. The description only restates that admin_token is required, adding no format or validation detail beyond the schema; 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?

"Stop accepting responses. Results stay visible." states a concrete verb (stop accepting) and the outcome (results preserved), which separates it from delete_decision by implication. It never names reopen_decision or delete_decision explicitly, so sibling 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?

The "results stay visible" clause hints at when to prefer this over delete_decision, but no explicit when-to-use or when-not-to-use guidance is given, and alternatives like reopen_decision are not mentioned. Usage is implied, not directed.

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 (writes, non-idempotent, non-destructive, open-world), so the description's added value is the return contract: a decision with a shareable `url` plus a private `admin_token` and `manage_url`. Flagging the token as something to 'keep private' is meaningful operational context. It does not discuss auth requirements, rate limits, or what happens on inference failure, so it stops short of a 5.

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

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

Front-loaded with the one-line purpose, then organized into the easy path, the exact-control path, the availability caveat, and the return values. Every sentence carries distinct information; the examples are compact and each demonstrates a different `type`.

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 six parameters, zero required, and no output schema, the description supplies exactly the missing pieces: which parameter combinations are valid, the type-inference behavior, and the shape of the return value including the sensitive admin token. An agent has everything needed to call this correctly on the first attempt.

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?

Adds substantial semantics beyond the 83%-covered schema: how `text` triggers type/option inference with four worked examples, the cardinality rules per type (2-5 poll options, 2-12 ranking options), that `question` alone yields a check-in, that availability requires `text`, and that `timezone` governs relative words like 'tomorrow'. These are cross-parameter interaction rules the schema cannot express.

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

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

States a concrete verb (create) plus the exact resource variants (poll, check-in, availability board, ranking) and the outcome (a shareable link). The creation operation is unambiguous against the lifecycle siblings close/delete/get/reopen/respond, and the subtype enumeration tells an agent exactly what can be produced.

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 between two invocation modes: 'Easiest: pass `text`' with worked examples per type, versus 'For exact control, pass `question` plus `options`'. It also states a hard constraint ('Availability must be created from `text`') and a prerequisite (timezone needed for correct local slots), leaving 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 already flag destructiveHint=true and idempotentHint=true, but the description goes further by disclosing what is actually destroyed (all responses), the external side effect (the share link stops working), irreversibility, and the admin_token auth requirement. That is precisely the extra context annotations 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?

Four short sentences, front-loaded with the action and its scope, then consequences, then the safety instruction, then auth. No sentence is redundant.

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

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

For a destructive two-parameter tool with no output schema, the agent has everything needed: what is deleted, what collateral effects occur, that it is irreversible, and what credential is required.

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

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

Schema description coverage is 100%, with both parameters documented including id/link formats, so the schema carries the semantic load. The description only adds that admin_token is an auth prerequisite, which is already reflected in the required list — baseline 3.

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 ("Permanently delete a decision") and immediately scopes the blast radius with "and all its responses." That cascade detail is enough to separate it from close_decision and reopen_decision, which are non-destructive state changes.

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

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

The description gives a procedural guideline ("confirm with the user first") that implies caution, but never names the obvious non-destructive alternative (close_decision) or states when deletion is the right choice versus closing. The when-to-use signal is implied rather than explicit.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations by specifying the exact result contents for each decision type and its role in supplying ids to respond_to_decision. No annotation contradiction 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?

The description is two tight sentences: the first front-loads the core read operation and result types, and the second adds the cross-tool dependency. Every clause provides useful selection or interpretation context without 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 one-parameter read tool with rich annotations and no output schema, the description supplies the missing return-value context by naming the result contents for each decision category. It is complete enough for an agent to call the tool correctly and understand what it will receive.

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

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

There is one parameter, and schema description coverage is 100%, with the schema itself documenting that decision_id accepts either an id or a SettleIt link. The description does not add parameter syntax or format details beyond the schema, 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 uses a specific verb and resource: “Read a decision and its current results.” It goes further by enumerating the result shape for polls, rankings, check-ins, and availability, so an agent can identify the tool without opening the schema. It also distinguishes the read operation from the write-oriented sibling respond_to_decision by noting that it returns ids needed for responding.

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 makes the usage context clear: read a decision and its current results, and use the returned option or slot ids before calling respond_to_decision. It does not explicitly list when not to use this tool or mention the other lifecycle siblings, but the read-only purpose is evident.

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 the safety profile (not read-only, idempotent, non-destructive, open-world), so the description's added value is the auth requirement ('Requires the admin_token') and the precise effect (clears an expired automatic close time) — both are things the annotations cannot express.

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, effect first and prerequisite second. 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 two-parameter state-transition tool with a fully annotated safety profile and no output schema, the description covers effect, trigger condition and auth. Minor gap: it doesn't say what happens if the decision wasn't auto-closed, or what state responses already collected remain in.

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 decision_id and admin_token are already fully documented. The description only restates that admin_token is required, adding no format or usage meaning 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+resource and the state transition: 'Accept responses again after closing'. The parenthetical clarifies which kind of closing it undoes, which separates it in practice from close_decision, though the sibling is never named.

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

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

Implies the when (after a decision has closed, specifically by an automatic close time that has passed) but gives no explicit when-not or alternative — e.g. what to do if it was closed manually rather than by timer.

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 beyond the annotations: re-answering with the same voter_id or name replaces the earlier answer, and matching is case-insensitive — this explains the idempotentHint and destructiveness the annotations only flag. It does not say what the tool returns or how invalid labels/ids are handled, so not quite 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?

Front-loads the scope sentence, then a compact bullet list keyed by decision type, then the replacement rule. Every line carries information, though the bullets repeat field names the schema already declares.

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 consent, field selection per type, and overwrite semantics for a 8-parameter mutation tool with no output schema. A brief note on the success response or error behavior on a bad option label would close 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% (baseline 3), but the description adds cross-field conditional logic the schema cannot express: which parameters pair with which decision type, that poll labels must match exactly, and that ranking order must list every option best-first.

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 ('Record one person's answer') and immediately constrains the actor ('only when that person asked you to'), which is the defining scope of this tool versus get_decision or close_decision. No sibling could be confused with it.

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-to-use rule (the person asked you to) and routes the agent to the sibling that tells it which fields apply ('get_decision shows it in respond.fields'). The per-type breakdown further tells the agent exactly which branch to take.

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