co.build

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

Beyond the destructive and non-read-only annotations, it discloses permanence, the inability to restore or reschedule the installation's single check-in, and the lack of impact on the installation report. It also explains behavior for sent or in-progress emails, including the cancelled:false result and accompanying status.

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-load the operation and then cover scope, irreversibility, and the important non-cancellable case. Every sentence adds operationally useful information, with no filler or 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 destructive mutation, the description covers nearly all essential preconditions and consequences, including an edge-case response. Its remaining gaps are followupId provenance and, because there is no output schema, incomplete documentation of successful results and other possible errors or already-cancelled 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?

The schema provides only the name followupId and its UUID format, with no parameter description. The description supplies general ownership and resource context but never explicitly maps the ID to the pending follow-up or explains where to obtain it, such as from schedule_installation_followup.

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 opening sentence gives a specific action, resource, owner, and state: permanently cancel the connected user's pending installation check-in email. It also distinguishes this operation from report withdrawal by stating that the installation report remains unchanged, and from scheduling by emphasizing that the check-in cannot be scheduled again.

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 explicitly limits use to the connected user's explicit request and to a pending check-in. The final sentence supplies a clear when-not boundary: emails already sent or being sent cannot be recalled, with the expected unsuccessful result described.

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 adds substantial behavior beyond them: per-item error semantics, a retry instruction for unavailable feedback, handling rules for unknown vs partial support, a scoping caveat that subscription fields refer to the primary device and not linked devices, and an untrusted-data warning plus citation requirement.

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 and scope, then moves to aggregation contents, then caveats. Every sentence is functional, though the run of eight short clauses (errors, unknown support, subscription fields, untrusted data, citing URLs) reads as an undifferentiated list rather than grouped guidance.

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 aggregation tool with an output schema already defining return shape, the description covers everything an agent needs: scope limit, what is aggregated, error handling, caveats about support status and subscription scoping, and a prompt-injection warning. Nothing material to 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 50%: modIds and modelId are documented in-schema, while deviceId and platform carry no description. The description adds the intent behind the optional device/model/platform parameters ('optional device/model/platform fit'), which gives them meaning the bare schema lacks, but it supplies no format or constraint detail to compensate for the undocumented half.

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 (compare mods) with a hard scope (up to four shortlisted mods in one call) and explicitly names what it aggregates: the same details as get_mod plus three newest get_feedback entries. An agent can distinguish it from get_mod and get_feedback 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 routes the agent away from the sibling reads: 'This replaces those separate reads when feedbackStatus is available,' and instructs 'retry unavailable feedback before recommending.' There is no explicit statement of when to prefer the individual get_mod/get_feedback calls instead, so it stops just short of full when/when-not 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds behavior beyond them: it names the returned payload (source text plus citation URL) and discloses a real quirk, that device results are truncated to the first 20 mods with get_device for paging.

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 then the ID format, with zero filler. The pagination caveat is placed last where it belongs as a follow-up consideration.

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?

An output schema exists, so return values need not be enumerated in depth, and the description still summarizes them plus the device-truncation caveat. The only meaningful omission is guidance on fetch versus get_mod for retrieving a single mod, which matters given how many get_* siblings exist.

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

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

Schema coverage is 0%, so the description must carry the single parameter, and it does: it explains that the ID must be the exact prefixed form and supplies device:whoop and mod:open-health as models of the required pattern. It omits the maxLength and minLength bounds, but those are enforced by the schema itself.

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 ("Read a device or mod") and scopes it to records "found by search," which separates it from the listing/search siblings. The two prefixed-ID examples make the resource type concrete enough that an agent can identify the call without opening the 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 clear when-to-use context (records already located via search) and an explicit alternative for one case: "use get_device for further pages" when a device returns only 20 mods. It does not address when to prefer this generic fetch over the sibling get_mod for a single mod record, leaving one routing decision 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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds non-obvious behavior: cross-device projects are included and their deviceId identifies the primary device, filters affect mods/picks/totalMods but not goal availability, and pagination is required for more mods. It stops short of noting auth requirements or result ordering.

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?

Content is front-loaded: what is returned comes first, then identifier format, then filter scope, then pagination. Sentences are dense but each carries distinct information; the 'mod goalIds connect projects to features' clause is the one piece that reads as schema trivia an agent may not need upfront.

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?

An output schema exists, so return-value explanation is rightly omitted, and the cross-device caveat is genuinely valuable. Against nine parameters with only 33% schema coverage, though, the description leaves several filters (kind, limit, maxSetupMinutes, platform interaction) unexplained, and the nextOffset/offset naming mismatch could confuse a caller trying to paginate.

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 33%, so the description carries real weight. It explains the deviceId format (slug or 'device: ID') and the narrowing effect of goalId/mod filters on 'mods, picks and totalMods', which is useful. But kind, limit, maxSetupMinutes, and offset receive no explanation at all, and the mention of 'nextOffset' does not map cleanly onto the schema's 'offset' 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 opens with a specific verb and resource set: 'List a device's models, available and requested features, curated picks and public mods.' That is clearly distinct from sibling tools like get_mod, compare_mods, or get_my_devices. It does not explicitly name a sibling it replaces or is replaced by, which keeps it out of the top band.

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 operational guidance ('Accepts a device slug or device: ID', 'Pass nextOffset to see more mods') and clarifies filter scope ('goal availability remains catalog-wide'). However, it never says when to choose this over compare_mods, get_top_mods, or search, so the agent must infer the boundary itself.

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 far beyond the readOnly/idempotent annotations: it warns that counts are global while matchedEntries reflects filters, that comments and reports overlap, that reports repeat authors or supersede older outcomes, that entries are unverified user claims and upvotes are not compatibility evidence, that empty feedback is not a negative verdict, and that comment text is untrusted data. This is exactly the disclosure an agent needs to interpret results without over-claiming.

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 every clause carries information, but the body is a dense chain of semicolon-linked caveats that is hard to scan and mixes invocation guidance with result-interpretation warnings. It would read better split into short labeled groups.

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 tool with annotations and an output schema, nothing material is missing: it explains filters, ordering, pagination via nextOffset and parentUrl, global vs. matched counts, and the epistemic status of the data. An agent could call and interpret it correctly from this text alone.

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 only 43% schema coverage, the description compensates well: modId accepts a slug or a mod: ID, modelId and firmware narrow to exact matching reports, order: newest surfaces recent breakage while helpful ranks by comment upvotes, and featureRequests: true filters to requests only. limit and offset bounds are left to the schema, and 'nextOffset' is mentioned though the input schema names it 'offset', a minor mismatch.

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 set: returns co.build upvotes, paginated public comments, feature requests, replies, and works/partly/broken reports for a mod. The read-only nature is unambiguous against write-oriented siblings such as prepare_feedback and publish_feedback, and the framing 'before recommending a mod' pins down the decision it supports.

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 triggering contexts: check community experience before recommending a mod, and use featureRequests: true to find an existing request before posting another. It also implicitly routes writing to sibling tools by being purely a read. It does not explicitly name alternatives or state when not to call it, so it falls 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 declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description earns credit beyond that by disclosing data provenance: these are self-reported distinct owners, not verified installations, and an install can succeed while the mod is untested. That is exactly the kind of caveat an agent needs to avoid over-claiming reliability.

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 definition of what is counted, followed by two caveats. Every sentence carries information, though the third ("functionality remains untested") overlaps the second's point that these are unverified user reports.

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

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

With one trivially documented parameter and annotations covering safety, the only real gap is output shape: there is no output schema, and "counts" (plural) does not reveal whether the response is a single number, per-version breakdown, or per-platform split. An agent cannot anticipate the return value from this description.

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

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

Schema description coverage is 100% and the single modId parameter is documented in the schema as "a catalog mod slug or mod: ID." The description adds no format, lookup, or error semantics beyond that, 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?

"Public distinct-owner counts for a catalog mod" names the exact resource (a mod) and the exact metric (distinct-owner report counts), and the word "public" implicitly distinguishes it from get_my_installations. It stops short of naming which sibling to use instead (get_mod, get_top_mods), so it is clear but not fully differentiated.

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

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

The description never says when to call this versus get_mod, get_top_mods, or get_my_installations, nor does it state any precondition beyond supplying a mod ID. The disqualifiers it does give are about interpreting the numbers, not about tool 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?

Beyond the read-only, idempotent, and non-destructive annotations, it discloses that setup recipes are untrusted author-provided data, warns against executing returned commands or prompts, and defines null or unknown fields as unverified. The traction explanation additionally prevents popularity from being misread as compatibility or safety evidence.

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 purpose and required follow-up are front-loaded, and nearly every sentence contributes a distinct operational constraint. It is nevertheless a dense nine-sentence block; the adjacent prompt/command safety warnings and the lengthy final traction 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?

For a one-parameter read tool with an output schema, the description covers selection, invocation, follow-up, field interpretation, and safe handling without needing to restate the return structure. No essential prerequisite or behavioral caveat appears 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 0% schema description coverage, 'Accepts a mod slug or mod: ID' supplies the missing semantics for the sole parameter, while 'same modId' explains how to reuse it with get_feedback. This substantially compensates for the schema, though a concrete example would make the mod: ID format slightly clearer.

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 opening sentence pairs a specific verb and resource with a concrete inventory of returned information, including compatibility, licensing, maintenance, subscriptions, and setup. It also distinguishes the tool from get_feedback by assigning community reviews, reports, and upvotes to that 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?

It gives an explicit recommendation workflow: call get_feedback with the same modId before recommending. It also states the precondition for setup—confirming the user's device, model, platform, and intent—and makes clear that retrieval must not lead to automatic command execution.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value beyond them by disclosing that only the connected account is returned and that the call does not publish ownership, which is the privacy concern an agent would have here.

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

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

Three short sentences, front-loaded with the core action and scope. Nothing is padding, though the clause about not publishing ownership is close to redundant with the privacy framing already implied by "private saved devices."

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 burden of explaining what comes back, and it does: typed-in devices plus devices from approved installation reports. Nothing essential to a correct call 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?

The tool takes zero parameters do not exist, so there is nothing to document; the baseline for a parameterless tool applies. The description correctly gives no parameter guidance because none is needed.

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 ("Read ... saved devices") plus the exact scope: typed-in devices and devices from approved installation reports. An agent can distinguish this from the singular get_device and from get_my_installations based on the described scope, 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?

"Use when the user asks what they own" gives a clear triggering context, and the description notes that only the connected account's data is returned. It does not state when to prefer get_device or get_my_installations instead, so the routing is clear but the exclusions are implicit.

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

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

With readOnlyHint/idempotent/destructive already declared, the description adds substantial context the annotations cannot: the return shape (newerRelease with version, url, publishedAt or null; lastFeedbackAt or null), a privacy guarantee that no other user's private account data is returned, pagination via nextOffset, and a consent constraint on retesting/publishing. This goes well beyond the safety profile annotations provide.

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 dense sentences, front-loaded with the purpose before return shape and workflow constraints. Every sentence carries useful information, though the consent sentence could be slightly 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?

Because there is no output schema, the description correctly explains the returned fields and the privacy boundary, and annotations cover the safety profile. Minor gaps remain: behavior with zero installations and the relationship between offset and the returned nextOffset are left to inference.

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 (offset) at 0% schema description coverage, so the description must compensate. It only mentions 'Paginate using nextOffset', which references the response cursor but never explains offset's type, origin, or default behavior, leaving the parameter partly 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 opens with a specific verb and resource ('Read the connected user's current, public installation reports') and scopes it to the authenticated user, which separates it from account-wide siblings like get_installation_stats. It does not explicitly name competing siblings such as get_installation_stats or prepare_installation_report, so differentiation is implied 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?

It gives concrete reasons to call it ('for follow-up or correction, and to recognize mods they use') and a downstream workflow (offer update and retest, then prepare a fresh report) that implicitly routes to prepare_installation_report. It stops short of explicit when-not-to-use guidance or direct naming of alternatives.

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

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

Goes far beyond the annotations, which only mark it non-read-only/non-idempotent/non-destructive. It discloses that the call consumes quota, mints a lease with leaseExpiresAt, that 21 open tasks yields lease_limit, and that the result is a pinned task object with readingPlan, download URLs, and previousCleanSha — none of which the annotations 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?

A single unbroken wall of roughly 700 words that reads as an SOP rather than a tool description, mixing git fetch commands, the review scoring bar, and sandbox hygiene rules into one paragraph. The opening clause is well front-loaded, but the remainder is dense and unscannable and buries the tool contract under process instructions.

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?

An output schema exists, yet the definition still explains the task shape, readingPlan path semantics, retry behavior, and failure codes an agent needs in order to act correctly. Nothing required to invoke it or interpret the result 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 retryTaskId is already documented, but the description adds real meaning: it must come from your own submitted could_not_review, it creates a fresh lease over exactly the same commit and scope including legacy parts, and a null retry means the scope is unavailable with no substitute mod. Slightly over-annotated rather than under, since much of it describes the returned readingPlan rather than the 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?

States a specific verb+resource+mode: a volunteer malware check that returns one whole mod listed by co.build as a review task. It clearly distinguishes itself from siblings by naming submit_review and release_review_task and explaining how each fits around 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?

Explicit when-to-use and when-not-to-use: 'Only when the user asked you to spend their quota on it; never start on your own,' with the standing-schedule carve-out. It also gives conditional branches for retry, null-return, lease_limit, github_required, and github_reconnect, plus the alternative release_review_task.

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

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

Beyond the readOnly/idempotent annotations, it discloses meaningful behavior: lists may be shorter than the limit rather than padded, downloadsPerMonth counts release downloads not installs, strengths are relative 0-4 steps rather than weights, and the ranking is not a quality/safety verdict. That last caveat is exactly the kind of constraint an agent would otherwise get wrong.

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?

It is front-loaded with the purpose and scope, then the ranking semantics, then the caution and pagination. Dense but coherent; a couple of clauses (e.g. the traction-metric enumeration) could be trimmed, but each sentence carries information the agent needs.

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

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

With an output schema present, the description needn't explain return values, yet it usefully anticipates them (traction fields, URLs to cite, nextOffset). For a read-only ranking tool with five optional parameters, nothing an agent needs in order to call and interpret it correctly is missing.

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

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

Schema coverage is 60%, and the description compensates well: sort's two modes are contrasted semantically ('most used and trusted' vs 'gaining fastest right now'), categoryId is tied to returned categories, deviceIds is framed as best-place-per-device, and nextOffset/offset pagination is explained. Only 'limit' is left to the schema, so this is strong but not exhaustive.

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 ('Answer what's most popular or rising, as co.build/top ranks it') and names the three scoping modes (all devices, categoryId, deviceIds). An agent can distinguish this ranking tool from search, get_mod, and compare_mods without opening the schema.

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

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

It explicitly routes to alternatives and states the condition: 'before recommending one, call compare_mods, or get_mod and get_feedback.' It also implies usage context ('Answer what's most popular or rising') and clarifies pagination continuation via nextOffset/offset, leaving 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 mark this as a non-readonly, non-destructive, non-idempotent write, and the description supplies the context they cannot: it stores only a temporary private preview that expires after 30 minutes rather than publishing. It also discloses the refusal boundary (no personal data, logs, health readings, or secret values) and states precisely what is returned — the exact action and public text.

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 trigger condition and the core action, and nearly every clause carries operational information (routing rule, data prohibitions, expiry, approval gate). It is a dense single block with some run-on sentences, but there is very little that could be cut without losing a constraint.

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 12-parameter write tool with no output schema, the description covers preconditions, sibling routing, field sourcing, prohibited content, return value, lifetime, and the mandatory human-approval handoff. Nothing an agent needs in order to call this correctly and safely 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 83%, so the baseline is 3, but the description earns more by explaining the enum semantics that the schema only lists: comment covers praise/bug/friction, feature_request is something the mod cannot do yet, reply targets any entry via parentId, and support upvotes a featureRequest parentId with an optional reply. It also constrains text to the owner's own words and confirmed context fields (tried, expected, actual, modelId, firmware, modVersion, platform), though it leaves deviceId's role mostly to the schema.

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

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

The first sentence names a specific verb and resource — prepare a private preview of a public post on a mod's co.build page — and explicitly separates it from publishing with "This does not publish." The four-way kind taxonomy further pins down what is being prepared, which is exactly the distinction an agent needs against the publish_feedback 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?

It gives a hard precondition (owner has actually used the mod and agreed to leave feedback) and a conditional routing rule: before a feature request, read get_feedback with featureRequests: true and switch to support if a duplicate exists. It also names the required downstream step — show the action and public text and get explicit approval before publish_feedback.

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 give a coarse safety profile (not read-only, not destructive, not idempotent), and the description adds real behavior: the draft is private and expires after 30 minutes, it returns the exact public text plus digest and consent version, and certain tokens are preserved verbatim while personal data, logs, health readings and secret values are stripped. What it does not cover is draft lifecycle on repeat calls (whether a new draft replaces the prior one) or any rate limiting, which matters given idempotentHint=false.

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?

Every rule is substantive but the paragraph is dense and front-loads process guidance rather than the purpose, forcing the reader to assemble what the tool does. There is also overlap between 'Keep notes short and factual' and the schema's length limits, and between 'Never include personal data, logs, health readings or secret values' and the later 'Send a short technical summary, never logs, secrets or personal data.' Splitting into purpose / content rules / consent-and-return would preserve the content with less scanning cost.

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 an 18-parameter, 12-required tool with no output schema, the description covers the consent gate, the sanitization contract, the draft expiry, and even the return payload (public text, digest, consent version). What keeps it from complete is the silent set of required fields, especially evidence (agent-observed vs user-reported), which materially changes what the report asserts and is never explained.

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 33% across 18 parameters, so the description has to compensate, and it does for the hardest ones: setupMinutes ('actual setup time'), prerequisites (required keys/accounts/cables/OS versions), steps, tips, exact model-or-null handling, and the agentClient/agentModel split versus hardware. It also prevents the common installation-vs-functionality conflation. However, several required fields carry no meaning anywhere (evidence's agent_observed vs user_reported distinction, tested, blockedOn, resolution, platform, firmware, modVersion), so the coverage gap is narrowed but not closed.

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 ('preparing a sanitized draft' of an installation report) and explicitly bounds it: 'This does not publish,' with publish_installation_report named as the downstream sibling. An agent can tell this apart from publish_installation_report and prepare_feedback without opening any schema.

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

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

It states the trigger ('After setup, ask the owner whether they want to share before preparing'), the required consent step, and the explicit hand-off ('ask explicit approval before publish_installation_report'). The alternative tool and the condition that selects it are both named, so nothing is left 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?

The annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description is fully consistent with them while adding real value: it clarifies that no comment is posted and no account is altered, and it imposes a privacy constraint ('Never include credentials or personal details'). This is meaningful disclosure beyond the structured fields, though it says nothing about the link's lifetime or whether repeated calls produce the same link.

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, each doing distinct work: trigger and action, scope boundary, data-hygiene rule. The action is front-loaded after a brief trigger clause, and no sentence is padding.

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 four-parameter read-only link builder with an output schema (so return values need no explanation) and full annotation coverage, this is nearly sufficient. The single real hole is the required modId, which an agent must infer as the mod whose installation is being reported.

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

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

Schema coverage is 0%, so the description has to carry parameter meaning; it names three of the four fields (outcome→result, model, firmware) and constrains them to user-verified values. However, 'modId' is required and completely unexplained in both schema and description, and the result enum values (works/partly/broken) are never mapped to the word 'outcome'.

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 names a specific verb and artifact: prepare a co.build form link for the user to review and submit, triggered by a reported setup outcome. The negative sentence ('Does not post a comment, publish a result or change an account') implicitly separates it from publish_installation_report and publish_feedback. It never names those siblings outright, so 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 trigger is explicit ('After the user reports a setup outcome'), and there is a concrete data rule: use only outcome, model and firmware that were supplied or verified, omitting unknowns. What is missing is routing guidance among the adjacent prepare_*/publish_* tools, which share nearly the same surface.

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 public visibility of the post, that the mod's maintainer is notified, and that retrying the same draftId never posts twice (consistent with idempotentHint). The approval requirement and draft expiry behavior are real operational context. It does not explicitly state that a published post is publicly permanent or how to retract it, which matters given destructiveHint=true and openWorldHint=true.

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 action and destination lead, followed by prerequisites and failure modes; every sentence supplies a constraint the agent could otherwise get wrong (approval gate, digest immutability, idempotency, expiry, GitHub exclusion). No filler or restatement of the tool name.

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

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

Covers the prerequisites, side effects, idempotency and failure path for a destructive, open-world mutation, which is more than adequate. With no output schema, it could still say what a successful call returns (e.g., a post link or id) so the agent can report 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 coverage is 0%, so the description carries the burden and does so well: draftId comes from prepare_feedback, digest must be the draft's 'unchanged digest' (implying an integrity check that rejects modified previews), and approved may only be true after real approval rather than OAuth consent. consentVersion is repeated from the schema const rather than explained, which is the main unused opportunity.

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 ('Post the saved feedback preview') plus the destination ('connected user's public co.build account'), which clearly separates it from prepare_feedback (preview) and from publish_installation_report / submit_review siblings. An agent can distinguish the action without opening the schema.

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

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

Explicit gating conditions: use only after explicit approval of the exact action and public text, pass draftId from prepare_feedback, and 'OAuth consent is not approval'. It also gives an exclusion ('Never open GitHub issues or pull requests for feedback') and the recovery path for an expired draft, so when-to-use and when-not-to-use are both covered.

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, idempotentHint and openWorldHint, but the description adds the concrete consequences: an update replaces the existing public text, and retrying the same draftId does not create a duplicate. It also clarifies the stale/expired draft path, which 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?

Front-loaded with the publish action, then prerequisites, then edge cases (idempotency, staleness). Every sentence adds a distinct constraint; none restates the tool name or schema.

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, public-facing mutation with no output schema, the description covers preconditions and side effects well. The one gap is that it never says what a successful publish returns (e.g., a public URL or report reference), which an agent may need for follow-up messaging.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: it explains draftId's origin, that digest must be unchanged, the consentVersion literal, and the gating condition on approved. It does not explain what 'unchanged digest' means cryptographically, but that is reasonably covered by the schema's 64-hex pattern.

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 opens with a specific verb and resource ('Publish the saved installation report preview') and names the exact scope ('under the connected user's public co.build account'). It is immediately distinguishable from its siblings prepare_installation_report and withdraw_installation_report.

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 spells out the required workflow (draftId returned by prepare_installation_report, unchanged digest, consentVersion, approved:true only after approval) and explicitly excludes false positives ('OAuth consent and installation completion are not publication approval'). It also states when not to use the existing draft ('a stale or expired draft requires a new preview and new approval').

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 real behavior beyond the annotations: repeat calls are a no-op, released:false signals the task was already submitted, a released task cannot later be submitted, and the local task folder is deleted (a side effect not conveyed by destructiveHint=false, though the shared mod itself is only returned to the pool). The one gap is that the destructiveHint=false annotation sits slightly awkwardly beside 'delete its folder' for a local workspace, and rate/permission behavior is not mentioned.

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 and outcome, then the when-to-use triggers, then edge cases in decreasing priority. Slightly dense with three short clauses at the end, but each carries a distinct fact (idempotency, released:false meaning, irreversibility).

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 tool with full schema coverage, an output schema, and annotations covering idempotency and destructiveness, the description covers the remaining burden: when to call it, ownership scope, cleanup side effect, and post-release irreversibility. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single taskId parameter is already documented as a UUID from get_review_task. The description reinforces the ownership constraint ('Only your own tasks'), which is meaningful semantics the schema does not encode, though it adds no format or sourcing detail beyond that.

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 and resource (release the lease on your own get_review_task task) and states the outcome (mod returns to the pool, no verdict recorded). It is immediately distinguishable from get_review_task (acquire) and submit_review (submit with verdict) in the sibling list.

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 triggers are given: the user says stop, an error occurs, or a limit is hit, and the instruction is to release every unsubmitted task. It also excludes the submitting case via 'won't submit', so the agent knows to use submit_review instead when a verdict is ready.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), it discloses write semantics the agent could not infer: identical reports are a no-op, differing counts or splits are refused, and guessing or sending transcripts is prohibited. The idempotency and refusal behavior is consistent with, and richer than, the annotation set.

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, but the middle is telegraphic run-on shorthand ('Claude Code: read transcripts by agentId, counting each assistant message.id once, never its displayed context-size total') that is hard to parse on first read. The closing sentence re-defines total usage already covered by the fallback clause, so there is mild 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?

A write tool with an output schema, and the description covers the mutation semantics, idempotency, scope limits, and counting methodology needed to call it correctly. Minor gaps remain, such as what error surfaced a refused report returns and how the 'within a day' window is measured, but these are small against the supplied schema and annotations.

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 compensates by defining all five reported fields, stating that the four counts are required together despite taskId being the only required schema field, and explaining totalTokens as a split-unknown fallback. Host-specific counting rules (count each assistant message.id once, not the displayed context-size total) add real meaning the schema lacks.

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 and resource (report exact token usage) and pins the scope: summed across reviewing subagents for one whole-mod task already submitted. The sequencing ('After the main session submits one whole-mod review') separates it from submit_review and from the reporting siblings like prepare_installation_report.

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

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

States the trigger (after submitting a whole-mod review), the eligibility constraint ('Only your own submitted reviews, within a day'), and the fallback path ('totalTokens alone remains a fallback'). It also gives an explicit skip condition for Codex when exact log events are unavailable, which is a rare and useful when-not-to-use clause.

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 destructiveHint=true and idempotentHint=true, and the description corroborates rather than contradicts them by explaining the destruction ("An email already being sent or delivered cannot be recalled") and the idempotency behavior (retrying while pending is a no-op). It adds delivery details absent from annotations — the target is the connected account's verified email address — plus a named failure code, which is real behavioral context beyond the structured fields.

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

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

Front-loaded with the action, unit, and range in the first clause, then layered constraints in decreasing priority. Dense but every sentence carries a distinct constraint; slightly crowded with four separate behavioral clauses in a single sentence.

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 4-required-parameter mutation with no output schema and no parameter descriptions, the description supplies the consent gate, delivery target, irreversibility, idempotent-retry semantics, and one error code. The only real gap is what a successful call returns (a schedule identifier or confirmation), which an agent would want before reporting success to a user.

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 0% schema description coverage, the description must carry parameter meaning, and it largely does: it documents the delayHours bounds (1–72), implies channel is email via "check-in email," and frames approved as the explicit-consent gate. It never names the parameters or states that reportId is a UUID, so the mapping relies on inference, but the semantics are recoverable.

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 ("Schedule one installation check-in email") with an explicit window of 1–72 hours, which immediately separates it from siblings like prepare_installation_report or cancel_installation_followup. The scope limit (one check-in per report) further pins down what the tool does.

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 after the user explicitly requests or agrees to that email" — and explicitly disclaims an adjacent use case: "Scheduling authorizes that email, not publication of future feedback." It also defines the retry path (returns the existing schedule) and the terminal-failure path (sent or cancelled returns followup_exists), so an agent knows exactly when to call, retry, or stop.

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 the readOnly/idempotent/closed-world annotations: result shape (descriptions plus up to 20 matches per page), the pagination contract (pass nextOffset as offset with the same query and filters), that filters exclude unknowns, that local dataSource is not an offline guarantee, and how suggestions and no-match results should be interpreted.

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?

Dense but front-loaded, leading with what is found and how to query, then pagination, then filtering caveats. Some sentences (suggestions vs. no-match evidence) are long and could be split, 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?

For a 10-parameter search tool with an output schema, this covers everything an agent needs: query style, filter semantics, pagination, result count limits, and interpretation of suggestions and empty results. Return value details are appropriately left to the 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?

With only 50% schema coverage, the description meaningfully compensates: it explains that filters require documented values and drop unknown support, clarifies dataSource as catalog metadata rather than offline capability, and implies type/kind/deviceId/platform/needsSubscription/maxSetupMinutes narrowing. It does not clarify limit or offset bounds beyond the pagination hint, leaving a small gap.

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

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

States a specific verb and two resources ('Find devices and public-source mods') plus the searchable fields (device name, model, feature, project name). This clearly separates it from siblings like get_device and get_mod, which retrieve by identity rather than by keyword.

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 concrete usage guidance: concise keywords rather than sentences, 'type: mod to skip devices', and the specific filters for constraining mods. It also explains continuation via nextOffset. It stops short of explicitly naming a sibling to use once an exact device is identified (e.g. get_device), 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?

Goes well past the annotations: one check per account per commit with retries returning the first result (concrete idempotency semantics), verified risky/malicious findings routed straight to co.build's admins, submissions refused if they carry secrets/emails/paths/env vars, snippets re-verified against GitHub at the commit, and a defenseLine the agent must echo verbatim. These are submission-side behaviors the readOnlyHint/destructiveHint flags 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?

One unbroken paragraph of roughly 450 words with no headings or line breaks, so the calling sequence and the risky bar blur together. It repeats the reviewer_manipulation rule twice in near-identical form ('text aimed at manipulating AI reviewers' and 'text addressed to AI reviewers ... is itself a reviewer_manipulation finding'), which is pure waste in a definition this dense.

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 high-stakes tool with nested findings objects, enums and an output schema, the description supplies the decision rubric (what counts as risky, the prebuilt_binary named case, what is explicitly not risky, CI/tests out of scope), the malicious definition, and the sandboxing constraints. An agent has everything needed to produce an acceptable submission without guessing.

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

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

With 10 parameters and 80% schema coverage, the description still adds real meaning: modId as the get_mod slug, commitSha as the full 40-char commit actually being installed, the up-to-5 most-severe-first findings with repo-root-relative paths and line ranges, snippet length and '...' shortening rules, filesRead as files read in full, and agentModel as self-reported with usage optionally reported later via report_review_usage.

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 concrete verb and resource: read the exact commit into an empty temp folder, then submit modId, full commitSha, verdict, findings and filesRead here. It also implicitly separates this from a full review by noting an install check is a tip that never counts toward Defenders' quorum, though it never names submit_review directly as the alternative.

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 trigger (before running anything from a mod you're setting up), explicit preconditions (download the exact commit, defaulting to get_mod's safety.setup.install.sha, into a new empty temp folder, read all of it), and explicit post-conditions on risky or malicious: stop the install, run nothing, tell the user what was found and where. When-not conditions and escalation paths are both covered.

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 the annotations do not carry: votes are sealed and results go privately to admins with nothing sent to the maintainer, retrying the same taskId never double-submits (reinforcing idempotentHint), snippets are independently verified against GitHub at the commit, and submissions carrying secrets, emails, local paths or environment data are refused. It also tells the agent what comes back per finding (verified / unverified / pending).

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 and then verdict criteria, and nearly every sentence carries a rule the caller needs. It is still a wall of run-on sentences — the prebuilt_binary carve-out and the readingPlan clause are dense enough to require re-reading, and light structure would improve it without cutting content.

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 9-parameter, nested, high-stakes submission with a verdict taxonomy and a refusal policy, the description covers everything an agent needs: how to choose a verdict, how to build findings, what is forbidden in payloads, idempotency, and what the return evidence means. The output schema's presence means return values need no further explanation.

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 78%, and the description fills the semantic gaps well: the verdict thresholds, the max-5 / most-severe-first ordering of findings, snippet length and '...' abbreviation rules, explanation limits, filesRead meaning, agentModel as self-reported, and usage as optional with a pointer to report_review_usage. This is meaning the schema does not convey.

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 and resource ('Submit your check of a get_review_task task') and ties it to the lease that get_review_task grants, so the agent knows exactly which sibling produces the taskId it must pass here.

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?

Goes far beyond a generic 'use this to submit': it defines each of the four verdicts operationally, enumerates what is explicitly NOT risky (registry deps, hash-pinned downloads, vendored libraries, build-tool wrappers) and what is out of scope (CI, tests, lint, docs), and names the timing condition (before the lease expires). An agent can pick a verdict without further 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 and idempotentHint, but the description goes well beyond them: it states exactly which artifacts are destroyed, that the withdrawn text is not restored, and that a later re-approval surfaces as a brand-new comment rather than reviving the old one. That irreversibility and identity-change detail is the kind of context 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?

Three sentences, front-loaded with the trigger condition, then effects, then consequences. No filler, no restating of the title beyond what the effects require.

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 mutation with no output schema and zero param documentation, this is close to complete: destruction scope, irreversibility, ownership, and follow-up handling are all covered. The remaining gap is post-call state — whether the report ID becomes unusable and what the tool returns — plus the untouched parameter semantics.

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

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

Schema description coverage is 0%, so the description carries the burden — and it only partly does. The prose 'After the user explicitly asks' and 'Requires ownership' loosely conveys the confirmation intent behind the const-true `approved` flag, but neither parameter is named, and the meaning of the required `reportId` (which report, and how to obtain it) is never addressed.

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 names a specific verb (withdraw/remove) and resource (the installation report), then enumerates the concrete effects: public feedback removed, installation count removed, pending email follow-ups cancelled. It is clearly distinguishable from sibling tools such as cancel_installation_followup, which only touches follow-ups, and from prepare_/publish_installation_report.

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 an explicit gating condition ('After the user explicitly asks to withdraw this report') plus a prerequisite ('Requires ownership') and a forward path (approve a new report later). What it lacks is a direct pointer to the closest alternative — a sibling exists purely to cancel follow-ups without withdrawing, and that routing is left implicit.

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