TweakThis

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

Goes well beyond the annotations by disclosing real side effects: a needs_input question moves the item to needs_input state and releases the caller's claim until the developer answers and reopens. Annotations only say idempotent, non-destructive, non-read-only; the claim-release semantics are not derivable from them.

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 action, then the state-changing variant, then the remaining kinds, then the token requirement — a logical order with no filler. It is dense but every clause carries information; only the kind taxonomy sentence could be tightened.

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?

Output schema exists so return values need no explanation, and the description covers the main behavioral risks (state transition, claim release, token requirement). Minor gaps remain: whether commenting without a claim is allowed and any visible constraints beyond the schema's 8000-character 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?

With 100% schema coverage the baseline is 3, and the description earns a bump by explaining the lifecycle meaning of the kind/needs_input combination (blocking, claim release) and the operational requirement to pass claim_token while a claim is held. It duplicates some schema text (the needs_input blocking note) rather than adding to it.

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

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

States a specific verb and resource ('Adds your comment to a feedback item') plus the visible effect ('shown to the developer in the dashboard'), which separates it from siblings like submit_resolution and claim_feedback. The kind enumeration further clarifies what flavors of action this tool performs.

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

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

Gives clear situational guidance: use kind "question" with needs_input true when you need to block work, "progress" for status reports, "comment" otherwise, and pass claim_token while holding a claim. It never explicitly routes the agent away from submit_resolution for final results, so it stops short of full alternative coverage.

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 annotations: the 15-minute TTL, auto-assignment of unassigned items to the caller, return payload (claim_token, new version, assignee), renewal-vs-new-claim semantics, and the two distinct conflict outcomes (conflict_claimed vs conflict_stale) with remediation for the latter.

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 block that leads with the action and lease duration, then parameters, returns, and error codes in priority order. No filler; semicolons keep it dense without losing parseability.

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 the mutation's safety profile, concurrency semantics, the value needed for downstream submit_resolution, and failure modes. With an output schema present it doesn't need to over-detail the return shape, which it correctly only summarizes.

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 already 100%, so the baseline is 3. The description earns above baseline by explaining the interplay the schema states only in isolation: expected_revision/expected_version must be what you read, and claim_token switches the call from claim to renew.

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 (claims), resource (an open item), and explicit state transition (open → in_progress) with a 15-minute lease. An agent can distinguish this from release_feedback and submit_resolution 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?

Explicitly frames the when: before working on an item, to prevent concurrent work, and notes the renewal path via claim_token. It does not name release_feedback as the cleanup step after finishing, so the alternative-routing is clear for use but not for release.

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, and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: the signed link is short-lived and must be re-fetched, and results may be partially redacted. It doesn't mention size limits or rate limits, 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?

Front-loaded with the return payload and its components, followed by one short sentence on link expiry. No filler, and the most decision-relevant fact (what you get) comes first.

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

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

The tool is simple (one required param), an output schema exists, and the description still covers the return shape, redaction caveat, and link lifetime. Nothing an agent needs in order to call this 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?

With one parameter at 100% schema description coverage, the schema already explains that attachment_id comes from get_feedback attachments. The description restates that provenance but adds no format, encoding, or validation 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 ('Returns one image of a feedback item') and immediately scopes it by naming where the id comes from (get_feedback), which separates it from get_feedback and the other siblings. An agent knows exactly what it gets back: preview image content, dimensions, capture location, redaction status, and a full-size link.

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 clear precondition (attachment id from get_feedback) and an operational rule ('Call again for a fresh link') that tells the agent what to do when a link expires. It stops short of stating when not to use it or naming an alternative path, but for a single-purpose retrieval tool the context is unambiguous.

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, and the description still adds substantial context: the current revision and version are returned (needed for claim_feedback), missing/truncated context and stale revisions are flagged, and page data is labeled untrusted webpage evidence rather than instructions — a real prompt-injection warning. That is exactly the kind of disclosure annotations cannot carry.

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 purpose, then workflow, and every clause is substantive. The long middle enumeration of returned fields is somewhat over-stuffed into one sentence and overlaps with the output schema, but no sentence is filler.

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

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

With an output schema present, return values need no explanation, so covering purpose, the untrusted-data caveat, staleness signals, and the follow-up claim step makes the description complete for a one-parameter read 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 100% for the single feedback_id parameter, and the schema already says it comes from list_feedback, so the schema does the work. The description's only added hint is that revision and version from this item feed claim_feedback, which is indirect.

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?

Opens with a specific verb+resource and scope ("Returns one feedback item at its current revision") and immediately distinguishes itself from list_feedback by being the single-item read. The enumerated payload makes the tool's identity unmistakable.

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

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

Explicitly routes to the next step ("Then claim_feedback with the item's revision and version") and states a prerequisite ("Before editing, confirm your repository matches the project's repository hint"). It lacks an explicit when-not-to-use or a stated contrast with list_feedback, which keeps it below 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 declare readOnly/idempotent/non-destructive, so safety is covered; the description adds genuinely new behavior: results are summaries with shortened notes, capped at 20, ordered by recency, and paginated via next_cursor. It does not discuss auth or scoping limits, but the added context is substantial.

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 behavior (what, order, page size) and dense with actionable detail; every sentence carries guidance. It is slightly long, but nothing is filler, and the closing pointer to get_feedback 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?

With an output schema present, return values need not be explained, and the description still covers filtering defaults, pagination, truncation of notes, and the recommended next call. An agent has everything needed to call it correctly on the first try.

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 goes beyond the schema by explaining the omitted-status default behavior, recommending which assignee value to prefer in team contexts, and stating the condition under which session_id should be used.

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 published feedback of one project as summaries') plus ordering ('most recently updated first') and page size ('at most 20 per call'). It is clearly distinguishable from get_feedback, which it names as the full-context sibling.

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 guidance for each branch: default status returns open and needs_input, use status "open" for work still to do, use assignee "me"/"unassigned" in a team, use session_id when the developer supplied one. It also routes to get_feedback as the follow-up for detail.

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, closed-world, so the safety profile is covered. The description adds meaningful context beyond that: it discloses the permission scope (owner or member) and the shape of what comes back, including per-environment URL patterns and feedback counts. It does not discuss pagination or result limits, so not a full 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 and the invocation rule comes last, which is the right order. The middle field enumeration (id, name, workspace, role, URL, repo hint, subdirectory, environments, counts) is somewhat long and partly redundant with the output schema, which costs it a point.

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 an output schema present, the return-value list is not strictly necessary, but the description covers everything an agent needs to call it correctly: no params, membership-scoped, and an unambiguous rule for selecting the right project. Complete for a zero-param discovery 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?

Zero parameters, so there is nothing to misinterpret and no schema compensation needed. Baseline 4 applies; the description correctly implies the tool is unfiltered and scoped only by the caller's membership.

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 the developer's TweakThis projects') plus the scope (every workspace where the user is owner or member). This clearly separates it from the sibling tools, which all operate on feedback items rather than projects.

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 'Start here' and gives a concrete selection rule: pick the project whose repository hint matches your repo, never by name similarity alone. That is a real when-to-use directive plus an anti-pattern warning, not just implied context.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the exact state transition and the fact that the claim becomes available to another agent, plus the expectation to provide a short reason.

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. The state transition and handoff are front-loaded, and the final instruction about the reason is short and useful.

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 state-changing mutation with a required claim token and an output schema, the description covers the key transition, the reason parameter, and the intended handoff. It does not discuss invalid or expired claim tokens, but that is a minor omission given the schema and output schema.

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 all three parameters are documented in the schema. The description only reinforces the reason parameter ('Give a short reason'), which is already specified in the schema as at most 500 characters; it adds little beyond the structured fields.

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

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

States a specific verb and resource ('releases your claim'), the exact state transition (in_progress → open), and the handoff outcome ('so another agent can take it'). The phrase 'without resolving it' distinguishes this from submit_resolution and from claim_feedback, so an agent can identify its role without opening another 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 a clear condition for use: 'when you stop working on an item without resolving it'. It implies the contrast with resolving via submit_resolution, but does not explicitly name alternative tools or state when not to use it.

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

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

Goes well beyond the annotations by disclosing the state machine outcome (ready_for_review, developer may accept or reopen), that the claim is released, that links are stored but never fetched, and the two failure modes (conflict_stale, conflict_state). The idempotentHint is reinforced by the schema's idempotency_key documentation.

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 action and state transition in the first sentence, then details parameters and error codes. The embedded "Context used" template is verbose but genuinely required for correct invocation, so the length is mostly earned; a little tightening is possible.

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 preconditions, required payload shape, optional evidence/links, idempotency implications, and both conflict outcomes. Since an output schema exists, return values need not be described, leaving no significant gap for an 8-parameter workflow 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 already 100%, but the description adds real meaning: the conditional requirement for claim_token, the source of revision and version (from claim_feedback), and a concrete template for the required "Context used" section of summary. It also explains the optional evidence and link fields' intent.

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 (submits your fix) plus the resource and the resulting state transition (moves it to ready_for_review, claim released). This is clearly distinguishable from siblings such as add_comment, release_feedback, and claim_feedback.

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 clear precondition ("After you have changed the code") and clarifies when claim_token is and is not needed. It does not name alternative tools or say when NOT to submit, so it falls short of the explicit when/when-not/alternatives bar of a 5.

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