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 cover readOnly/idempotent/non-destructive, but the description adds two things they don't: the Bearer accessKey auth requirement and an explicit statement that sharing/publishing is out of scope. It still omits anything about output format or limits, so it isn't fully rich.

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 returned data before auth and scope caveats; nothing is padded. The telegraphic 'Bearer accessKey.' fragment is slightly terse but costs almost no length.

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

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

With no output schema and no parameters, the description carries the return-value burden and does so by naming the four data categories returned. Combined with the auth and scope notes, an agent has enough to call it, though the overlap with contribution_access_status remains unresolved.

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 there is nothing for the description to disambiguate and no schema gap to compensate for.

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

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

The verb 'Read' plus a concrete enumeration (installation credits, authorized source hosts, scope expiration, rewards) tells the agent exactly what data comes back. However, it never differentiates itself from the near-identically named sibling 'contribution_access_status', leaving the agent to guess which one to pick.

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

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

Usage is only implied by the read framing, and the one explicit boundary ('Does not enable sharing or publish') is a negative capability statement rather than a when-to-use rule. No alternative sibling is named for the overlapping 'access status' case.

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?

The description adds real behavioral context beyond the annotations: a required Authorization bearer key, a metered read that 'Consumes one available read', and the clarification that budget/token estimates are approximate costs rather than billing. This also explains why readOnlyHint=false despite the 'Read' verb (quota side effect), so no contradiction arises.

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 tight sentences, front-loaded with the core action and followed by auth, cost, and pagination notes. No filler, though the wording is dense enough that the param mapping is easy to miss.

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?

Auth, quota consumption, and budget semantics are covered, which suits a tool with no output schema. However, the q, id, and exact cursor/budget parameter meanings remain undocumented in both the schema and the description, leaving key invocation details incomplete.

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 all parameter meaning. It hints at 'budget' (maxChars) and 'nextCursor requests another excerpt' (cursor), but never names the parameters precisely and leaves both 'q' and 'id' entirely unexplained, which is a serious gap for a required id.

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 selected evidence within a JSON character budget.' An agent can distinguish this as a retrieval call from siblings like search_research, though the description never explicitly names those alternatives to sharpen the contrast.

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?

There is no explicit when-to-use guidance or routing versus search_research, prepare_contribution, or other siblings. The note that it 'Consumes one available read' implies a metered context but stops short of telling the agent when this tool is the right choice.

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 beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing the reward mechanics (+2 reads, capped at 20/day), that one record is kept per installation/card, and that no raw question or conversation is stored. These are genuinely useful behavioral details not derivable from the structured fields, though return/error behavior is unstated.

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

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

Four compact, information-dense sentences with the precondition front-loaded. No filler, though the reward sentence is slightly tangential to invoking the tool and the jargon ('owner-enabled feedback') assumes familiarity.

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 2-param write tool with no output schema, the description covers the precondition, payload shape, idempotency, and reward consequence, which is most of what an agent needs. Auth/permission requirements and error or response behavior remain unspecified.

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 parameter burden. It identifies the two params as 'Card ID plus a fixed reason code', which maps id->card ID and code->reason code, but it does not explain the meaning of the enum values (used, not_relevant, outdated, incorrect) or the required string format of id.

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: 'report whether a previously read card was used', which is distinct from siblings like read_research or submit_knowledge_card. It is clear what the tool does, though it never names a sibling to route against, so it stops short of the 5 level.

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?

'Only with owner-enabled feedback' establishes an explicit precondition/exclusion for when this tool applies. It provides clear usage context but never names an alternative tool or the fallback when feedback is not owner-enabled, so no routing is given.

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?

Goes well beyond the annotations by disclosing what gets created (agent accessKey and a secret owner management link), a rate limit (two per daily network cohort), and two important behavioral constraints (hand the link to the owner, never change contribution settings yourself) plus the default that automatic sharing starts OFF.

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: the core action and its quota come first, then the outputs, then the operational cautions. Every sentence carries information, though the telegraphic style takes a second read.

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

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

For a zero-param provisioning tool with no output schema, the description covers what is produced (keys, management link), the sharing default, and the caller's responsibilities. Minor ambiguity remains around what 'compact reads' actually are and how they are consumed.

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; the description correctly needs no per-parameter detail and adds no misleading signature information.

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 clear verb+resource ('Start 10 compact reads' via a trial) and is distinguishable from siblings like read_research and report_reuse. The phrase 'compact reads' is somewhat jargon-y, but the intent is legible.

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 use conditions and limits explicitly: no account or report required, two trials per daily network cohort, and to reuse existing keys. It does not directly name a sibling alternative, but the prerequisites are clear.

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 annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true): server-side verification of every excerpt against the public page, a three-per-day rate limit, reward economics (+100 reads new, +20 update), and the requirement to reuse the idempotency UUID on retries. This is exactly the behavioral 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?

Front-loaded with the core action and scope, then constraints and economics, with no filler sentences. Some fragments ('Use a separate public-source context, local screening and the SDK') and the telegraphic reward notation are dense enough to risk misreading, which keeps it below a 5.

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-parameter mutation tool with no output schema, the description covers scope, sources constraints, idempotency, rate limits, and rejection routing. It stops short of saying what the tool returns (card ID, verification result) and does not clarify topic or localScreenVersion 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 coverage is 0%, so the description must compensate, and it does for sources (3–5 excerpts, ≤25 words / 220 chars) and idempotencyKey (reuse UUID on retries). But it never explains the topic enum values, the localScreenVersion constant, or the 'updates' field, leaving several required parameters semantically opaque.

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 (publish knowledge card excerpts) plus the exact scope constraint (public documentation hosts, owner-enabled scope). It is clearly distinguishable from siblings like prepare_contribution or report_reuse, none of which publish sourced cards.

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

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

Gives a clear routing condition: outside scope or uncertain, keep local for review, and it prescribes preparing a public-source context with local screening. It does not, however, name or defer to a sibling tool (e.g., prepare_contribution) for the pre-publication step, leaving the alternative implicit.

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