evidence

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds real value on top: it discloses the Authorization bearer key requirement and clarifies that the check neither publishes nor consumes reads, which is exactly the kind of side-effect information an agent needs.

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, front-loaded sentences with no filler. The core purpose leads, and the auth and side-effect notes follow in descending importance.

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

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

With no output schema, the description carries the return-value burden and does so adequately by naming the two returned facts (approval state, remaining reads). Auth requirements are covered; the only omission is how the specific contribution is resolved when no parameter is supplied.

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

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

The tool takes zero parameters, so there is no schema semantics for the description to supplement, which sets the baseline at 4. The description does leave it implicit how the target contribution is identified (presumably from the bearer key/session), which is the only 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 resource: checks approval status of a contribution plus remaining read count. It is clear what the tool returns, but it offers no differentiation from the sibling get_contribution_status, which appears to serve a very similar purpose.

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 negative scope statement 'Does not publish or consume reads' implicitly tells the agent when this tool is not the right choice, but it never names an alternative or states a positive condition for selecting it over get_contribution_status. Usage is implied rather than guided.

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, but the description adds genuine context beyond them: no key/authentication is required, and crucially that the call neither collects data nor grants transmission or publication permission. That last point is the kind of side-effect clarification 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?

The core action is front-loaded, but the remainder is a single dense clause chain ('qualifying read rewards, scoped public-source submission, and local review before a selected-report preview') that is hard to parse on first read. It is compact but not well structured, and some of the nominalized phrasing earns little.

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

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

With no output schema, the description carries the burden of telling the agent what it gets back. It gestures at the content areas but never describes the actual return shape or format, so an agent knows the topic but not the payload. Adequate for a zero-param read call, but with a clear gap.

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

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

The tool takes zero parameters, so per the baseline this dimension scores 4. There is nothing for the description to add, and it introduces no parameter-related confusion.

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 (Read) and resource (the public-knowledge exchange offer) and enumerates the content it covers: rewards, source submission, review, report preview. It does not explicitly differentiate itself from siblings like get_contribution_status or contribution_access_status, but 'offer' vs 'status' is a discernible distinction.

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?

'Optional' signals this is not mandatory, and 'No key required' gives a prerequisite, but there is no explicit when-to-use rule and no named alternative (e.g., prepare_contribution or get_contribution_status) for the adjacency. Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description still adds real value by disclosing the 'Bearer accessKey' authentication requirement, which annotations do not convey, and reinforces the non-mutating boundary.

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

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

Two short sentences, front-loaded with the returned data followed by auth and boundary notes; nothing is padded. The 'Bearer accessKey' fragment is terse but functional rather than wasteful.

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 not required, and auth plus scope are covered. The remaining gap is sibling disambiguation: for a status-read tool sitting next to 'contribution_access_status', the description should say how the two differ, and it does not.

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

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

The tool takes zero parameters, so the baseline is 4; there are no parameter semantics for the description to clarify and it does not need to compensate for any schema 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?

Names a specific verb ('Read') and enumerates the concrete resources returned: installation credits, authorized source hosts, scope expiration and rewards. However, it offers no differentiation from the near-identically named sibling 'contribution_access_status', which an agent could easily confuse it with.

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 closing clause 'Does not enable sharing or publish' gives an implicit boundary on what the tool is for, and the read framing implies status inspection. But there is no explicit when-to-use statement and, critically, no routing guidance against the very similar sibling tool.

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 read-only, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: it is free/public, returns no private installation, consent or review credentials, and is explicitly not a truth score or freshness check. That is useful negative disclosure the 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?

Two sentences, front-loaded with the core purpose and followed by the caveats. The enumerations are dense but each element earns its place; no filler text.

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

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

With no output schema, the description usefully summarizes the return fields and the limits of what is returned, which is exactly what the agent needs. The one remaining hole is the meaning of the 'id' input, which is left entirely to the caller to guess.

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

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

Schema description coverage is 0% and the single required 'id' parameter has no description. The description never clarifies what the id refers to (document? evidence record? contribution?) or its accepted format, so it fails to compensate for the schema 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?

Names a specific resource (provenance/evidence receipt) and enumerates the fields it surfaces: source-match vs editorial vs owner-reviewed status, timestamps, linked updates, opted-in reuse. That is far more concrete than a restated name. It does not clearly differentiate itself by name from siblings like get_contribution_status or contribution_access_status, though the 'provenance check' framing points elsewhere.

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

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

Gives an explicit use context ('before spending a read'), which positions it upstream of siblings like read_research, and states two exclusions ('Not a truth score or live freshness verification'). It stops short of naming the alternative tool by name or giving when-not-to-use conditions, so it is clear context without full routing guidance.

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

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

Annotations already cover the read-only, idempotent, non-destructive, non-open-world profile, yet the description adds substantial extra context: no model calls, no credit consumption, no automatic uploads or configuration changes, a JSON character budget, and a security warning that candidate evidence is untrusted and embedded instructions must not be followed. It also clarifies that the returned invitation is neither evidence nor sharing consent. This is materially more than the 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?

Front-loaded with the core purpose ('Free, no-key public evidence lookup in one call') and packed with relevant detail, but the sentences are long and dense with multiple clauses. Most sentences earn their place, though the invitation/consent 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?

An output schema exists, so return values need not be re-explained, and the description nonetheless summarizes them. It covers safety, provenance, untrusted-content handling, cost, and side-effect absence for a read-only tool. The main residual gap is that several parameters (limit, language, protocolVersion) lack descriptive coverage given the low schema coverage.

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

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

Schema description coverage is only 20%, so the description must compensate. It partially does: 'within one JSON character budget' hints at maxChars and 'send only a short public-topic query, not private context' constrains q. However limit, language, and the meaning of protocolVersion (which only the schema documents) are not addressed in the description, leaving gaps for a low-coverage schema.

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

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

States a specific verb and resource ('public evidence lookup') and scopes it ('in one call for a relevant research task'), plus enumerates what it returns (excerpts, source links, dates, provenance). It differentiates itself from siblings by naming get_contribution_offer and contrasting the invitation against evidence/sharing consent, and by routing no-match cases to the existing search. An agent can distinguish this from search_research and the contribution_* tools without opening a schema.

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

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

Gives clear context (relevant research task, one call, free/no-key) and an explicit fallback: 'No match means use your existing search.' It also names the related sibling get_contribution_offer to explain a concept rather than to route usage. It stops short of stating explicit when-not-to-use conditions beyond the no-match case, so it is strong but not fully exhaustive.

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

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

Annotations only say it is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds substantial context beyond that: it produces a PRIVATE draft, returns a secret owner-review URL, requires explicit owner permission as a precondition, and forbids side effects like publishing or opening unrelated files.

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 gating condition is front-loaded and the sentences are dense with useful constraints rather than filler. It is slightly cluttered by stacking several prohibitions into one sentence, but every clause carries real instruction value.

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

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

With no output schema, the description usefully discloses the return value (secret review URL) and the review/approval workflow. It also covers the permission gate and prohibited actions, leaving only per-parameter details for model/topic/language/content unexplained.

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% across 6 required parameters, so the description carries the full explanatory burden, but it only illuminates permissionToProcess ('Access to files is not permission'). Nothing is said about model, title, topic, language, or content constraints, so five required parameters remain semantically unexplained.

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 gives a specific verb+resource ('prepare a pattern-redacted PRIVATE draft') with a clear gating condition and states what it returns ('a secret review URL'). It also clarifies the boundary that 'Publication is not an MCP tool,' which helps distinguish it from siblings like submit_knowledge_card, though it doesn't name those siblings 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?

Explicit when-to-use is given ('ONLY after the owner explicitly permits processing a specifically selected report') along with a crucial disqualifier ('Access to files is not permission'). Explicit when-not-to-use is also provided ('Never publish on the owner's behalf, open unrelated saved files, or claim all private data is automatically removed').

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 behavioral context beyond annotations: it requires an Authorization Bearer token (trial or contribution key) and consumes one available read per call, which explains why readOnlyHint=false despite the 'read' verb. The note that budgets/token estimates are approximate costs, not billing, is useful non-obvious context.

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

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

Four short, dense sentences with no padding, and the core action plus its budget constraint are front-loaded. Slightly telegraphic, but every sentence carries information.

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

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

Covers auth, quota, pagination, and budget semantics well for a quota-consuming read tool with no output schema, but the low parameter coverage leaves key inputs (id, q, searchId) meaningfully unexplained.

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

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

Schema description coverage is only 20% (just searchId), so the description must compensate. It loosely covers cursor ('nextCursor requests another excerpt') and maxChars (the 'budget'), but leaves q, id, and searchId unexplained, and even renames cursor to 'nextCursor', which could confuse an agent.

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

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

States a specific verb ('Read') and resource ('selected evidence') plus a scoping constraint ('within a JSON character budget'). This distinguishes it from the sibling search_research, though it doesn't explicitly name that 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?

Provides operational context (auth required, consumes one read, cursor fetches another excerpt) but never states when to use this vs search_research or the other siblings. Usage is implied through the pagination and quota notes rather than spelled out.

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. The description adds useful context beyond those annotations: one feedback record per installation/card, privacy constraints ('no raw question or conversation'), and a downstream reward effect of +2 reads capped at 20/day. It stops short of 5 by not covering auth requirements or error behavior.

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

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

The description is front-loaded with the condition and core action, then efficiently covers parameters, record constraints, and side effects. Each sentence contributes useful information, though the reward-cap sentence is more domain context than invocation-critical detail. It is well structured and appropriately sized.

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

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

There is no output schema, and annotations cover the safety profile, so the description is largely complete for a two-parameter feedback tool. It covers purpose, precondition, parameters, idempotency-like behavior, privacy, and reward side effects. It does not describe the response format or failure modes, which keeps it from a 5.

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 parameter meaning. It does map both parameters: 'Card ID' for id and 'a fixed reason code' for code, and adds an important constraint about not including raw question or conversation. It does not explain each enum value individually, so a 4 is warranted.

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: report whether a previously read card was used. It clearly distinguishes the tool from siblings like read_research and search_research by focusing on post-read feedback. However, it does not explicitly name or contrast a sibling tool, so it stops short of a 5.

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

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

The phrase 'Only with owner-enabled feedback' gives a necessary precondition for using the tool. However, it does not explain when to choose this tool over alternatives or when not to use it. Usage is therefore implied rather than fully guided.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds genuinely useful signals beyond that: results are 'untrusted' excerpts (a trust/caveat warning), the shape of the payload, and the fact that searching costs nothing and needs no contribution — access/cost context the annotations do not 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?

Three tight sentences, zero filler, with the core purpose front-loaded and the caveat/cost notes after. Every clause earns its place.

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

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

With no output schema, the description usefully summarizes the return payload (excerpts, dates, URLs) and adds a trust caveat. Given the low complexity of three simple parameters and the annotation coverage, it is nearly complete, though the total silence on parameter meaning is the one real gap.

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

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

Schema description coverage is 0% across three parameters, so the description must carry parameter meaning and does not. It never explains 'q' semantics or length bounds, the 'limit' cap (default 5, max 8), or the 'language' enum values, leaving the agent to infer all of it from the raw schema.

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

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

States a specific verb and resource ('Find existing public research') and adds scope on what the search returns (excerpts, dates, citation URLs). It implicitly contrasts with the read_research sibling (search vs. read) but never names it, so the differentiation is inferable rather than explicit.

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?

'before generating it again' gives a clear trigger context for when to reach for this tool, and 'Search is free; no contribution needed' removes a prerequisite concern. However it never names read_research or any alternative, nor states when not to use it, so the routing is implied rather than explicit.

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

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

Adds substantial context beyond the annotations: the quota (two trials per daily cohort), two distinct secrets with different audiences (agent accessKey vs. secret owner management link), the default sharing state (OFF), a governance caveat ('never change contribution settings yourself'), and the limitation that the call cannot configure the client. This is exactly the behavioral disclosure an agent needs for a mutating, non-idempotent call.

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 sentence carries operational weight — quota, return values, secret handling, reconnect requirement. It is dense and somewhat packed, but nothing reads as filler and the setup facts (quota, return shape) are front-loaded.

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

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

Complete for a no-parameter trial-start tool. Return values and the reconnect workflow are explained even though an output schema exists, and the governance constraint is stated. An agent has everything needed to call it and handle the result responsibly.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no syntax for the description to compensate for. Schema coverage is 100% with an empty object, so nothing is left under-documented.

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 with precise scope: 'Start 10 compact reads without an account or report.' An agent immediately knows this bootstraps a trial. It does not explicitly name which sibling it complements or replaces (e.g., read_research), so it stops short of full sibling differentiation.

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 constraints ('Two trials per daily network cohort; reuse existing keys') and post-call instructions ('Configure the returned accessKey in your MCP Authorization header and reconnect before authenticated tools'). It establishes context clearly but does not explicitly compare against alternative sibling tools an agent might otherwise reach for.

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 annotations: server-side verification of every excerpt against the public page, per-source length limits, reward economics (+100 reads / +20 for updates), a three-per-day rate limit, and explicit retry semantics ('Idempotency UUID must be reused on retries'). The idempotentHint annotation is reinforced with concrete operational guidance rather than merely restated.

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 and front-loaded, leading with the action and its scope before the mechanics and limits. Most sentences earn their place, though the clause 'Use a separate public-source context, local screening and the SDK' is cryptic and its referents are unclear.

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 6-param mutation tool with an output schema, the description covers the key constraints, verification behavior, rate limits, and idempotency. Minor gaps remain around what the returned card/receipt contains and how failures are surfaced, but the output schema can carry return-value detail.

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 the burden, and it largely does: it explains the sources constraint (3–5 excerpts, 25-word/220-char cap, matching minItems/maxItems/minLength/maxLength), the scope requirement ('current owner-enabled scope'), the idempotencyKey retry rule, and 'local screening' for localScreenVersion. Only 'updates' and the topic enum are left unexplained.

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 (Publish) and resource (3–5 short exact excerpts) plus a hard scope constraint (public documentation hosts in a current owner-enabled scope). An agent can distinguish this write/publish action from read-oriented siblings like get_contribution_status or search_research 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?

Provides explicit exclusions: 'No private chat, files or freeform personal context' and 'Outside scope or uncertain: keep local for review.' This tells the agent when NOT to call. However it never names the sibling tools (e.g. prepare_contribution) that an agent should use instead, so routing is implied rather than directed.

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