revisia

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 genuine value by disclosing what is returned (plan tier, caps, unlocked sources) and why it matters for downstream quota-consuming calls. It does not discuss rate limits or failure cases (e.g., unauthenticated), which keeps it short of a 5.

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

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

Two sentences: the first declares contents, the second declares usage timing and reason. Nothing is redundant and the content of the return is front-loaded before the call-condition.

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 must convey what comes back, and it does so at the level of three content classes. It stops short of describing the shape of those values (e.g., whether caps are numeric limits or structured objects), but an agent can call it correctly with what is given.

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 parameter semantics carry a baseline of 4. The description correctly implies no inputs are needed by framing everything around the signed-in researcher.

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 (Show) and resource (the signed-in researcher's plan, per-account caps, unlocked bibliographic sources). It is unmistakably distinct from every sibling, which are all workflow action tools (search, screening, extraction, export).

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 explicitly when to call it: before planning work that consumes quota, and enumerates the affected activity classes (searching, screening, extraction). It supplies the rationale (know the ceilings), so the agent has an ordering rule, not just a purpose.

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=true, idempotentHint=true and destructiveHint=false, and the description is fully consistent with them ('Read-only', 'never approves anything'). Beyond the annotations it adds real workflow context the schema cannot convey: later stages stay locked in the web app until the first unapproved one is signed, and the response carries human-readable signing instructions.

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 trigger condition is front-loaded, and the negative constraint ('It never approves anything') plus 'Read-only' are placed where they cannot be missed. The first sentence is long and comma-chained, but nearly every clause carries information an agent needs to phrase the hand-off to the researcher.

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 describing the return value and does so item by item: which stage, what to check, the exact wording, and the signing link. Combined with the locking rule and the read-only constraint, nothing an agent needs in order to call this correctly is missing.

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

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

There is a single required parameter, project_id, and schema description coverage is 100% ('Review id (from revisia_projects list)'), so the schema already does the work. The description adds no format or sourcing detail beyond that, which is the expected baseline here.

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 resource ('returns which stage awaits approval') and immediately pins down scope: 'always the first unapproved one'. It also enumerates the payload (what to check, exact words, web link), so an agent knows exactly what it gets back and how it differs from a mutation tool despite the name 'approve_stage'.

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 this when a stage looks finished' gives a clear trigger condition, and 'It never approves anything: stage approval is a human act made in the web app' explicitly rules out the misuse an agent would otherwise infer from the tool name. No sibling tool is named as an alternative, which keeps it just 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 cover readOnly/idempotent/non-destructive, and the description adds real context beyond them: default returns a summary plus a web-app download link, include_file only attaches when the file fits, and extracted titles/abstracts are untrusted third-party text to treat as data. That injection warning is substantive behavioral guidance rarely found in annotations.

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 trigger, then the artifact list, then default behavior, then the caveat — all in three compact sentences with no filler. The parenthetical format keys double as a reference without bloating the 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 still tells the agent what comes back (summary + download link, or attached file) and under what condition. For a simple 3-parameter read-only export, nothing an agent needs before calling 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 description coverage is 100% and the enum values are already documented in the schema with matching glosses, so the description's format list largely repeats structured data. The only added nuance is the conditional nature of include_file ('if it fits'), which is also already in the schema default text.

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 ('export a file from the review') and enumerates the exact artifact set (screening_csv, refs_ris, refs_ris_all, audit_csv, rob_csv, protocol_md). This distinguishes it cleanly from siblings like revisia_report or revisia_prisma_flow_diagram, which produce non-file outputs.

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?

Opens with an explicit trigger ('Use this when the researcher needs a file from the review') and explains the default vs include_file path. It does not name alternatives or say when to prefer revisia_report / revisia_prisma_flow_diagram instead, which is the only gap.

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, and the description's restatement of 'Read-only' is redundant. What it does add beyond the annotations is the result shape (per-study rows, per-variable columns, per-cell verification flag) and the paginated nature plus the with_quotes output-size tradeoff — genuinely useful for a tool with no output schema.

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 dense sentence that front-loads the main clause and packs row/column/cell semantics, pagination, and the quotes option into parentheticals. Slightly run-on, and the trailing 'Read-only' duplicates the annotation, but nothing major is wasted.

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 5-parameter paginated read with no output schema, the description covers the important ground: what a row is, what a column is, what a cell contains, how verification is signaled, and how quotes change the payload. It doesn't explain paging flow (next_cursor chaining) or column variability across projects, which would round it out.

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 80%, so limit, cursor, project_id, and with_quotes are already documented in the schema. The description only echoes the with_quotes behavior and the pagination concept without adding format, cursor lifetime, or ordering details beyond the schema. Baseline 3 applies.

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

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

States a specific resource and its exact shape: 'data extraction table: one row per included study, one column per variable, each cell with its value and whether its supporting quote was verified.' An agent immediately knows what it gets back, though it never names sibling revisia_extraction_act or explains why this read variant differs from the write one.

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 this when you need the data extraction table' gives an implied trigger but no exclusions and no alternative named. The agent must infer on its own that revisia_extraction_act is the counterpart for editing cells rather than reading the table.

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 context beyond the annotations: the suggest-then-save workflow, that dry_run defaults to true and reports pending studies and blockers, that false actually launches, and that extraction is paid and gated on full-text approval. However, with destructiveHint=true set, it never states what is overwritten by define_columns or consumed by a real run, nor whether a launch can be cancelled or reverted.

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, then a compact per-action list; nearly every clause carries information. The telegraphic fragments ('AI extraction; dry_run defaults to true') read tersely but remain parseable, with only mild redundancy against the schema's dry_run description.

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 5-parameter mutating tool with no output schema, it covers the essentials an agent needs before calling: action semantics, dry-run default, cost/approval gating and the order of operations. Remaining gaps are the shape of the run response and what governs quota consumption, which matter but are secondary to correct invocation.

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 80%, so the schema already documents dry_run, project_id and idempotency_key. The description still adds meaning the schema lacks: which action consumes `columns`, that suggest_columns output is discarded, and what dry_run=true actually reports (pending studies, blockers). The idempotency_key is left entirely 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 description names a concrete resource (data extraction) and breaks the tool into three specific actions (suggest_columns, define_columns, run), each with a one-line meaning. It never mentions the sibling revisia_extraction (likely the read/status counterpart), so an agent must infer the act/read split from naming convention alone.

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?

Opens with an explicit trigger ('Use this when preparing data extraction') and gives per-action distinctions, notably that suggest_columns results are not saved while define_columns persists accepted columns. It also states prerequisites (paid feature, approved full-text stage). It stops short of saying when NOT to use it or naming revisia_extraction as the alternative for reading existing definitions.

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=false and openWorldHint=false, so 'Read-only' in the description is a restatement rather than new information. The genuinely additive parts are the disclosure of record categories (has full text / not retrieved) and that decisions include who decided and why, plus pagination — but nothing about volume, ordering, or permission requirements.

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

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

A single front-loaded sentence that leads with the usage trigger and then enumerates the returned content; no filler. The heavy nested parentheses make it dense to parse, but every clause carries substantive 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?

With no output schema, the description usefully enumerates what comes back (inclusion state per record, retrieval status, decision attribution), which is the main gap a list tool would otherwise have. Combined with fully covering annotations for the safety profile, an agent has enough to call it correctly; only ordering and pagination mechanics remain unstated.

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 75%: limit, cursor and project_id are already self-documented in the schema, while the 'action' enum has no schema description at all. The description's '(action list, paginated)' partially compensates by implying the only action is a paginated list, but adds no semantics about cursor lifetime or row ordering.

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 the resource precisely (the full-text stage: which included records have a PDF/PMC text, which were not retrieved, and the recorded decisions with reviewer and reason) and implies a paginated list operation via '(action list, paginated)'. It does not distinguish itself from the sibling revisia_fulltext_act, so an agent must infer that this is the read side and that one is the write side.

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 this when you need the full-text stage' gives a context trigger but no explicit when-not or alternative. The 'Read-only' tag hints that mutations belong elsewhere, but revisia_fulltext_act is never named as the counterpart, leaving routing to inference.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description usefully explains what that means in practice: dry_run true only reports what would run and quota used, while dry_run false actually launches the job. It also discloses a gating condition (paid feature, stages must be approved) that annotations cannot express. It does not state whether recorded decisions are reversible or what happens to prior decisions.

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 trigger condition is front-loaded and every clause carries information: action mapping, the reason requirement, the dry_run default, and the paid-feature gate. The middle section is a dense run-on chain that could be split per action for faster scanning.

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 7-parameter multiplexed tool with no output schema, the description covers the mode selection, the safety default, the cost prerequisite, and the one conditional requirement (reason on exclude). What is missing is modest: whether decide is a separate step from run, and any indication of what a dry-run versus launch response contains.

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 86%, so the baseline is 3, but the description supplies the missing semantics for the action enum, which the schema lists only as bare values, and reinforces that exclude needs a reason and that dry_run defaults to true. Minor parameters such as idempotency_key and paper_id are left entirely 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 description names the three concrete operations (fetch open-access full texts, run AI full-text screening, decide/record a decision) and attributes each to an action value, so an agent can map intent to parameter immediately. It does not explicitly distinguish itself from the sibling revisia_fulltext (the non-act variant), leaving the read-vs-write split to be inferred from naming convention.

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 opening 'Use this when the researcher wants...' clause gives per-action trigger conditions, and it adds real prerequisites: exclude requires a reason, fetch/run default to dry_run true, and screening is a paid feature needing approved stages. It stops short of naming which sibling to use instead for status/listing or approval (revisia_fulltext, revisia_approve_stage).

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=false and openWorldHint=false, so safety and side-effect behavior are covered without description help. The description adds real substance about the guide's scope, notably that it defines what an agent may and may not do on the researcher's behalf. It does not say what form the response takes (prose vs structured) or how large it is, which matters for a doc-dump tool.

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, zero waste, with the identity of the resource front-loaded and the call condition placed second. The three-item content list earns its length by telling the agent what it will actually get.

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 must carry the whole burden of saying what comes back, and it largely does by naming the guide's three sections. A note on response format or size would fully close the gap for a documentation tool of this kind.

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 parameter meaning for the description to add; the baseline of 4 applies. Nothing is missing on this dimension.

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 ('Return revisia's own guide for AI agents') and enumerates the guide's contents: platform purpose, the ten-stage methodological spine, and the agent's permission boundaries. This clearly separates it from every sibling tool, which are operational (screening, extraction, rob, export) rather than documentation.

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 explicit triggering guidance: 'Call this when unsure how a step of the review works before guessing.' That tells the agent the condition that selects this tool. It does not say when not to call it (e.g., not repeatedly mid-task, or deferring to revisia_account_status for runtime state), so it falls short of full alternatives 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 declare read-only, idempotent, non-destructive, closed-world behavior, and the description reinforces this with real added context: deterministic results, validation against R packages (irr, psych, irrCAC), and no account needed. It also states the scope boundary that it will not adjudicate disagreements, which prevents misused expectations. The remaining gap is minor — it does not discuss input-size limits or error behavior, but the annotations carry the safety profile.

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 dense paragraph, front-loaded with the use case before the statistical detail and the exclusions. It is long but nearly every clause carries information; the list of output artifacts (CI, p-value, band, methods sentence, figure) is the only part that partly duplicates what the output schema already provides.

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?

Given an output schema exists, the description need not explain return values, and it still names them for decision-making. It covers inputs, variant selection, provenance, and scope limits, so an agent has everything required to call it correctly.

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 the baseline is 3, but the description adds the critical semantic that 'table' and 'ratings' are alternative input modes — a k×k contingency table versus one row of labels per item with one column per rater — plus the mapping from rater count to Cohen vs Fleiss. That mutual-exclusivity framing helps an agent choose correctly even if the schema descriptions already gesture at 'Give this or ratings'.

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 computation (agreement statistics / kappa) with named variants (Cohen unweighted/linear/quadratic, Fleiss, Gwet AC1/AC2, PABAK) and expected outputs. An agent can immediately distinguish it from sibling tools like revisia_screening_act or revisia_rob, which act on reviews rather than computing statistics.

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 trigger ('when the user wants agreement statistics between reviewers, e.g. for dual screening or data extraction'), an explicit exclusion ('does not resolve disagreements or judge which rater is right'), and an explicit instruction not to compute kappa by hand while this tool exists. It also routes to the correct statistical variant via the 2-rater vs 3+-rater rule.

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 and destructiveHint=false, and the description corroborates with 'Read-only' rather than contradicting. Beyond that it adds real behavioral detail the annotations cannot express: a wait window of about 45 seconds, the fact that it returns status plus done/total progress with next steps, and that a finished screening job reports AI-screened versus human-verification counts driven by plan quota. It does not describe the possible status values or how multiple job kinds are resolved when kind='all'.

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 with the trigger front-loaded, followed by return-value detail and the retry instruction, so the most actionable content comes first. The parenthetical list of eight job families is dense but earns its place by defining scope; the screening-quota sentence is the only slightly tangential addition.

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, so the description carries the return-value burden, and it does so adequately: status, done/total progress, next steps, and the screening-specific breakdown. What is missing is the vocabulary of statuses and what happens when the wait expires without completion, which matters for an agent deciding whether to re-poll or escalate.

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 80%, so the schema already documents kind, job_id, project_id and timeout_seconds, including the default-and-max of 45. The description's mention of 'about 45 seconds' merely restates the timeout default and adds no syntax or precedence rules, such as how job_id interacts with kind when both are supplied. Baseline 3 is the correct score here.

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 action (wait) on a specific resource (a job) and enumerates the job families it applies to (import, search, strategy build, criteria suggestion, screening, full text, extraction, risk of bias). That set of families maps onto the sibling launch tools, so an agent can tell this is the poll-after-launch tool rather than another action tool.

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 clear trigger ('Use this after launching anything long') and the retry rule ('If the job has not finished, call it again'), which is exactly the guidance an agent needs for a polling tool. It stops short of 5 because it never names the sibling launch tools or states any when-not-to-use condition, leaving the agent to infer which tool started the job.

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 the delivered artifacts (Word document and CSV carrying the official item wording), that progress and unanswered items are reported back, that notes land in the CSV but not the Word file, and that no account is needed. It also draws the key behavioral line that it only records the user's answers rather than interpreting the manuscript.

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 'Use this when...' trigger, then inputs, then outputs, then the exclusion. It is a dense single paragraph with a couple of easily trimmed clauses (the repeated item counts, 'only the user's answers go in') but no wasted sentences.

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 three-parameter, fully documented generator with an output schema, everything the agent needs is present: what it returns, in which formats, what it deliberately does not do, and that no authentication is required. Nothing material 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 the baseline is 3; the description still adds value by explaining that each entry pairs an item status with where it is reported (page, section, table) and by noting the CSV-not-Word routing of notes. It does not mention the lang or title parameters, leaving those entirely 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?

States a specific verb and resource: produce the completed PRISMA 2020 reporting checklist (27 items plus the 12-item abstract list) for manuscript submission. The scope, item counts, and output formats (.docx and CSV) make it clearly distinguishable from the flow-diagram and report siblings.

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 trigger ('when the user needs the completed PRISMA 2020 reporting checklist... to submit with a manuscript') and a clear boundary ('It does not read the manuscript or decide whether an item is reported'). It never names a sibling or says when to use revisia_prisma_flow_diagram or revisia_report instead, so routing against alternatives 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?

Annotations already declare readOnlyHint/idempotentHint/non-destructive and closed-world, so safety is covered. The description adds real behavior beyond that: it derives duplicates from per-source counts plus records_after_deduplication, validates the arithmetic and returns warnings when numbers do not add up, emits both SVG and PDF, and requires no account. What remains undisclosed is what happens when required counts are absent or when warnings fire.

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 and prerequisite, then the capability, then the constraint, then the no-login note. Dense but nearly every clause carries decision-relevant information; the long parenthetical count list is the one place that pushes toward density over scanability.

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 tool with deeply nested inputs and an output schema (so return values need not be described), the description covers purpose, preconditions, derivation logic, validation warnings, output formats, and the must-not-invent constraint. An agent has everything needed to call it correctly 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?

Schema coverage is 71%, and the description compensates by mapping real-world PRISMA stages onto parameters: per-source counts, duplicates, screened/excluded, reports sought and assessed, and per-reason exclusions, plus the 'previous version' arm for updated reviews and the 'other methods' arm. It also adds an important semantic rule not in the schema ('leave unknown ones out', 'pass only numbers the user gave you'). Only lang and the precise label-vs-count shape of exclusion reasons go 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 (draws) and a specific artifact (PRISMA 2020 flow diagram) rendered as SVG and PDF, and enumerates the exact inputs it consumes (records per database, duplicates, screened, excluded, reports sought/assessed, exclusion reasons, studies included). An agent can tell this apart from revisia_prisma_checklist or revisia_risk_of_bias_figure 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?

Opens with an explicit trigger condition ('use this when the user needs ... and already has the counts per stage') and adds an explicit exclusion ('does not search databases, screen records or invent counts'). It stops short of naming a specific sibling (e.g. the checklist tool) as the alternative, so routing to the wrong PRISMA artifact is still inferable rather than stated.

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=true, idempotentHint=true and destructiveHint=false, so the trailing 'Read-only' sentence adds nothing. Real added context is the ordering guarantee ('newest first') and the contents of the status payload (running jobs, next stage awaiting approval), which tell the agent what state it can observe. It does not cover failure behavior, e.g. what status does without a project_id.

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 trigger leads, followed by a clean 'action list:' / 'action status:' parallel structure and a short operational note. The only dead weight is the final 'Read-only.' which duplicates the annotations; the status enumeration is long but every item is informative.

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 describing returns and it does so for both actions, listing the counters and job/stage state the agent can expect. Combined with the calling-cadence advice, an agent can select and invoke this correctly without further context.

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 67% and the enum values are the main semantic gap, which the description fills by defining what 'list' and 'status' actually return. project_id and include_archived are elaborated in the schema itself, and the description's note that ids come 'from revisia_projects list' usefully links the two calls. It could be sharper about when project_id is required versus optional.

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 the resource ('the researcher's reviews') and enumerates the two operations with concrete content: 'action list: reviews owned by the account, newest first' and 'action status: corpus size, identification and deduplication counts...'. This is enough to separate it from revisia_projects_act on behavior grounds, though the description never acknowledges the write-side sibling or explains why the tool is named 'projects' while it returns 'reviews'.

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 trigger ('Use this when you need the researcher's reviews or where one stands') plus a concrete cadence rule ('Call status before proposing next steps and after any long job'). What's missing is a negative/exclusion rule pointing to revisia_projects_act for mutations, so the agent must infer the read/write split.

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 destructiveHint/not-idempotent annotations, it discloses the AI question check and its daily quota, that a failed verdict creates nothing and returns the verdict plus what is missing, that confirm_question skips a second check, that unavailability still creates the review, and that question_version staleness causes refusal. These are real behaviors an agent could not infer from the annotations.

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 'Use this when' trigger and no filler sentences; every clause earns its place. The flow is dense and some sentences are long run-ons (the create/verdict sentence), which costs a point against crispness but not against usefulness.

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 the description compensates by describing what comes back (the verdict, what is missing, revisia's own wording, or a statement that no wording could be proposed). For a two-action, destructive, quota-limited tool this covers everything needed to call it correctly.

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

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

Schema coverage is already 88%, so the baseline is 3; the description earns more by explaining why confirm_question should only be set after the researcher saw the check of that exact wording, why question_type is echoed back to preserve the framework, and what question_version guards against. Syntax details like lang default and the sha256 pattern remain schema-only, which is fine.

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+resource pair ('a new review or to reword its question') and then separates the two actions ('action create' vs 'action update_question'), so an agent knows exactly which capability it is invoking. It does not name or contrast the closely related siblings (revisia_question, revisia_question_act), leaving that differentiation to inference.

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 ('Use this when the researcher wants a new review or to reword its question'), explicit sequencing (show original vs revisia's wording, ask the researcher, then re-call create with confirm_question: true), and explicit exclusions ('Never write a wording of your own', concepts locked once stage 1 is approved). It also names the fallback branch when the AI check is unavailable (quota used up, AI down, email not confirmed) creates anyway and must say so.

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, and destructiveHint=false, and the description's "Read-only" merely repeats that. The one piece of added context is that AI-suggested criteria awaiting researcher action are included in the result, which is genuinely useful. No pagination, auth, or scope behavior is described.

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 short and front-loads the usage condition, which is good. However, the bare fragment "action list_criteria" reads like leftover wiring rather than prose, and "Read-only" duplicates the annotation, so some content does not earn 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 carries the burden of describing the return shape, and it does list the main content categories (question, concepts, criteria, AI-suggested criteria). It omits how these are structured or what happens when a review has no criteria yet, leaving a meaningful gap for a retrieval tool.

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

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

Schema coverage is only 50%, so the description should compensate for undocumented parameters, but it does not. The fragment "action list_criteria" only echoes the single enum value already in the schema, and project_id gets its meaning solely from the schema description ("Review id from revisia_projects list").

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 the specific resource being retrieved: the review question, its concepts, and the eligibility criteria, plus pending AI-suggested criteria. That is more than a restatement of the title. It never mentions the mutating sibling revisia_question_act, so an agent cannot distinguish read vs. edit paths from the text alone.

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 this when you need the review question..." gives an explicit triggering condition, which is clear usage context. There are no exclusions or named alternatives, though, so the agent must infer that revisia_question_act is the write counterpart.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds genuinely new behavioral context: AI actions consume the account's AI limits as in the web app, an unconfirmed email only gets trial calls, suggest_pico is not persisted, and suggest_criteria is asynchronous. It stops short of stating what check or set_criteria actually does to existing criteria on overwrite, so it is strong but not complete.

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 rationale is front-loaded in one sentence and the four actions are laid out in a scannable 'action X:' pattern with no filler. It is telegraphic and dense, and the quota note trails at the end, but every clause 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?

For a four-action, quota-limited tool with no output schema, the definition covers persistence, async behavior, cost, and where to read the async result. The remaining gap is that it never says what the check action returns or how set_criteria reports success or conflicts, so an agent must discover that at call time.

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 75% schema coverage the baseline is already decent, and the description still adds meaning: it explains that criteria entries with an id edit an existing criterion while entries without an id add one, and that preset applies a pack instead of explicit criteria. It does not explain the stage, required, or exclusion_label fields, which remain schema-only.

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 the specific domain (stage 1 question and eligibility criteria) and enumerates all four actions with a concrete phrase for each: quality check, concept breakdown, AI criteria draft, and saving criteria. It also distinguishes itself from siblings by pointing to revisia_question for reading results and noting that new reviews are checked by create.

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?

Every action carries a when-to-use clause ('preparing stage 1 and the eligibility criteria', 'a review that already exists', 'runs as a job; read the result with revisia_question', 'save criteria the researcher accepts'). It explicitly routes the agent to revisia_question for the job result and to create for new reviews, which is exactly the alternative-selection guidance this dimension rewards.

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=false and openWorldHint=false, and the description's "Read-only" merely restates that. The only added behavioral value is characterizing the artifacts (e.g., the PRISMA diagram comes with its counts, the Methods paragraph is citable) with no mention of generation cost, latency, or whether outputs are stored or computed.

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

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

A single front-loaded sentence with the trigger condition first and the three action-to-output pairs enumerated in parallel. Every clause carries information; nothing is padded.

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 only two parameters and no output schema, the description usefully sketches what each action returns, which is the main gap it needed to fill. Remaining omissions (output format, whether the manuscript is generated on demand, overlap with prisma-related siblings) are minor for a read-only report tool.

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

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

Schema description coverage is 50% and the undocumented parameter is exactly the one that matters: the action enum. The description supplies the meaning of all three enum values, which is genuine added semantics. It adds nothing for project_id, but the schema already documents that as the review id sourced from revisia_projects.

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 the concrete deliverables (PRISMA 2020 flow diagram with counts, citable Methods paragraph, manuscript draft) and maps each to an action value, so the resource is unambiguous. It falls short of 5 because it never distinguishes this tool from siblings that sound highly overlapping, notably revisia_prisma_flow_diagram, revisia_prisma_checklist, and revisia_report_act.

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 this when you need the review's outputs" plus a per-action mapping effectively tells an agent which action yields which artifact, which is real selection guidance. There is no explicit exclusion or alternative routing (e.g., when to use revisia_prisma_flow_diagram instead, or that mutations belong to revisia_report_act), so it stops short of the top score.

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, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds context the annotations cannot: dry_run defaults to true and only launches when false, and that all prior stages must be approved with a confirmed email. It does not say what happens to an existing draft or what a launch consumes, which keeps it short of a 5.

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

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

Three short sentences, front-loaded with the trigger and followed by the dry_run rule and the prerequisites. Nothing is wasted, though dry_run is explained twice within a very short span, once in the description and once in the schema, which 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?

For a destructive, four-parameter action tool with no output schema, the description covers the essentials an agent needs: when to invoke, the safe default, and the approval/email gates. The remaining gap is consequence detail - whether a generated draft replaces a prior one and any quota cost - which matters given destructiveHint=true.

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 75% and the schema already documents dry_run, project_id and idempotency_key thoroughly. The description restates the dry_run default/false behaviour without adding syntax or caveats, and says nothing about idempotency_key. Baseline 3 is appropriate when the schema is doing the explanatory work.

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: writing the 'manuscript draft' from 'approved stages (action manuscript)', which pins down both the operation and the enum value. It is clear on its own, though it never explicitly contrasts itself with the sibling read tool 'revisia_report' or the export tool, so differentiation is left to inference.

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 trigger ('Use this when the researcher wants the manuscript draft written') plus preconditions: every earlier stage must be approved and an email confirmed. What is missing is the negative case - no statement of when not to call this versus revisia_report or revisia_export - but the gating conditions are unusually concrete for this suite.

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 description's added value is the operational detail: outputs come back as SVG and PDF plus per-domain percentages, hard cap of 500 studies, and no account required. Minor gaps remain on whether figures are persisted or returned inline only.

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, then scope, inputs, outputs, and limits in a compact block. The long opening sentence carries a lot of clauses but none are redundant; the instrument enumeration is necessary because the enum is large.

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 stateless, read-only figure generator with 10 parameters (one required), a rich nested schema and an output schema, the description supplies everything an agent needs: what triggers it, what it accepts, what it returns, its hard limit, and what it explicitly does not do.

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

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

Schema coverage is already 90%, so the baseline is 3; the description still adds real meaning by spelling out the robvis table layout (Study, D1…Dn, Overall, Weight) and the studies-vs-table alternative, and by clarifying that weighted vs unweighted governs the summary bars. It does not explain the 'headers', 'palette' or custom-scheme parameters beyond what the schema says.

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

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

States a concrete verb and artifact ('traffic-light plot and the weighted or unweighted summary bar chart (robvis style)') plus the full instrument list, so the agent knows exactly what gets produced. It also implicitly separates itself from revisia_rob by declaring it does not assess bias itself.

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?

Opens with an explicit trigger condition ('Use this when the user has risk-of-bias judgements per study and wants...') and adds a clear exclusion ('It does not assess bias itself and never reads papers: every judgement must come from the user'). It stops short of naming the sibling tool to use instead for judging bias, leaving that routing 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 readOnlyHint, idempotentHint and destructiveHint=false, so the trailing 'Read-only.' adds nothing. The useful addition is that action=summary results are paginated and include supporting quotes, which the annotations do not convey. It says nothing about page-size behavior, empty-result behavior, or what the figure payload contains.

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 front-loaded sentence that starts with the trigger condition, then branches cleanly into the two actions via parallel parentheticals. The final 'Read-only.' is redundant with annotations but is only two words.

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-parameter read tool with no output schema, the description covers both action branches and their return character well enough to invoke correctly. The remaining gap is navigational rather than behavioral: no guidance on when to prefer the standalone risk-of-bias figure tool.

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

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

Schema coverage is 75%, and the description adds the one thing the schema cannot: it maps the bare enum values summary and figure to their respective outputs, notably that summary is paginated. limit, cursor and project_id are already documented in the schema, so no further explanation is required.

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 resource (risk-of-bias assessments per study and domain, plus supporting quotes) and enumerates the two modes of operation, so the agent knows exactly what it retrieves. It does not distinguish itself from the sibling revisia_risk_of_bias_figure, which on name alone appears to overlap with action=figure.

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 opening 'Use this when you need...' gives implied usage guidance and ties each need to an action value, which is helpful. However there are no exclusions, and the presence of revisia_risk_of_bias_figure alongside action=figure is left unexplained, so the agent cannot confidently choose between them.

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, idempotentHint=false, and openWorldHint=true; the description adds genuinely new context by flagging that drafting is a paid feature and gated on the extraction stage, plus that dry_run defaults to true. However, it does not disclose what destructive means here — e.g. whether decide overwrites existing judgements or domain entries — leaving the most consequential annotation unexplained on a mutation tool.

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 a 'Use this when' clause and kept to two sentences covering run and decide, plus cost/gating. It is dense with parentheticals but every clause carries operational meaning; a light split into separate run/decide sentences would improve scanability slightly.

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

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

For a two-mode mutation tool with 7 parameters and no output schema, it covers prerequisites, cost, and the dry-run default well. What is missing is outcome information an agent needs to act safely: whether run returns a job handle, and whether decide is additive or overwriting — important given destructiveHint=true.

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 86%, so the schema already labels tool, domains, dry_run, paper_id, project_id, and idempotency_key. The description restates the two key semantics (dry_run false launches; decide takes instrument plus one judgement per domain) without adding format or constraint detail beyond what the property descriptions already say. Baseline 3 applies given the schema does the heavy lifting.

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 both modes precisely: 'AI risk-of-bias drafts (action run...)' and 'a judgement recorded (action decide...)', each mapped to its action value. An agent can distinguish the two operations without opening the schema. It stops short of 5 because it never contrasts with the read-only sibling revisia_rob, which an agent choosing between list/inspect and act tools would want.

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 trigger condition ('Use this when the researcher wants...') for each action and states a prerequisite ('needs the extraction stage approved'). No exclusion clause or alternative tool is named, so an agent must infer that revisia_rob covers inspection rather than drafting or recording.

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 pagination (10 per page with limit and cursor), two detail levels, and a meaningful domain behavior: it respects blind dual screening, which an agent must know before interpreting actor fields. It does not state what blind mode hides from the result.

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 content is dense but the second sentence is a fragment that wedges 'or action conflicts' onto the end of the results clause, making the action split read awkwardly. Front-loading the trigger is good, but the structure costs clarity on the two-action choice.

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 correctly spends its words on return shape (per-record fields, criterion verdicts, quote-verbatim flag) and pagination. The only shortfall is not saying how conflicts records differ in shape from results records.

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% and already documents every parameter, yet the description adds actionable meaning: that the decision filter only applies to the results action, and what concise vs full actually return. This goes past restating the enum descriptions.

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 the resource (title/abstract screening decisions) and the exact payload: per-record decision, human vs AI actor, per-criterion verdict with reason, and a verbatim-quote flag. It is clearly a read tool distinct from the act siblings via 'Read-only', though it never names revisia_screening_act 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?

It gives an explicit trigger ('Use this when you need the title/abstract screening decisions') and routes between the two actions, defining conflicts as records left in 'review' or in reviewer disagreement. It lacks an explicit when-not-to-use or a pointer to the sibling that records decisions.

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 flag destructiveHint=true and openWorldHint=true, and the description adds real context beyond them: dry_run defaults to true and reports quota consumption and launch blockers, idempotency_key makes retries safe, and screening is gated on a confirmed email plus an approved criteria stage. It stops short of saying what is actually mutated or consumed when a launch proceeds despite destructiveHint=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?

Front-loaded with the triggering condition, then split by action value, which matches the two-mode shape of the tool. Dense but every clause carries information; only the parenthetical retry note is slightly compressed.

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 still explains what a dry_run returns (record counts, human-verification quota share, blockers). It leaves the return shape of an actual launch and of a decide call unstated, and does not name a sibling for listing screening results, but the gating and safety story is otherwise complete for an 8-parameter mutation tool.

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

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

Schema coverage is 88%, so the baseline is 3, but the description goes further by tying dry_run to its default behavior, linking idempotency_key to retry safety within a window, and stressing that decide records exactly ONE decision. Those cross-parameter relationships are not in 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 for each mode ('AI screening run' vs 'a screening decision recorded') and immediately enumerates the two action values. An agent can tell this apart from the read-side sibling revisia_screening and from bulk work, which the description pushes to the web app.

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?

Opens with an explicit when-to-use sentence, then gives an exclusion ('bulk changes are made in the web app') and prerequisites ('Screening needs a confirmed email and an approved criteria stage'). It also sets the default expectation for dry_run before launch, so the agent knows the safe first call.

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 read-only, idempotent, open-world and non-destructive, so the bar is lower; the description adds that 'estimate' involves 'no AI' and that the count is persisted server-side ('The count is saved, so the web app shows it without counting again'), which explains an observable side effect. It stops short of covering latency, cost, or what the status payload actually looks like beyond a field list.

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 intent is front-loaded, but the text is a chain of dense run-on sentences with nested parentheticals that take several readings to parse. Every clause carries information, yet the packing into two long sentences hurts scannability.

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 7-parameter tool with an enum-driven action and no output schema, the description covers both action modes, the prerequisite flow, and the persistence of counts. Gaps remain around filters semantics and any indication of what status actually returns structurally, but nothing essential for 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 71% and the description meaningfully extends it: query is described as a what-if that still returns the saved count, provider/providers are framed as the researcher-selected databases with the leave-out behavior returning the plan's database list, and detail=full is tied to printing whole queries. The nested 'filters' object is left entirely unaddressed.

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 (search) and precisely enumerates the two action modes and their outputs: 'status' returns the search strategy (concept blocks, saved query per database, what each search retrieved, latest import) and 'estimate' returns a record count. It also explicitly distinguishes itself from revisia_search_act by noting that the estimate counts 'what revisia_search_act run launches'.

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 explicit when-to-use conditions for both actions, a prerequisite (ask the researcher which databases if unspecified), and a fallback behavior — 'estimate without provider or providers counts nothing and returns the databases available on their plan'. The saved-vs-what-if distinction for the query parameter is also spelled out as a usage rule.

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, destructiveHint=true, openWorldHint=true), it discloses that build runs as a job but answers immediately and must be re-called, that dry_run defaults to true and only reports counts while false launches ingestion, and that import is capped at 200,000 characters and never fetches URLs. These are exactly the operational traits an agent needs before invoking a mutating, open-world tool.

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 a single dense paragraph that front-loads the triggering condition, and every clause maps to an action, so little is wasted. It would scan faster as per-action lines, and the build/job re-call instruction sits mid-sentence rather than being prominent.

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 five-action, twelve-parameter tool with no output schema, it covers each action, the job-waiting loop, and the safety-relevant defaults, which is close to what an agent needs. Return shapes for build and run are only sketched ('returns the available databases'), leaving some guesswork about what success looks like.

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

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

Schema coverage is already 92%, so the baseline is 3, but the description adds real meaning on top: save=false means look-only, dry_run true vs false, content is file text not a URL with a per-call size limit, and searches overrides providers. It does not explain idempotency_key or the blocks structure, both of which rely on 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 description names each action and its resource concretely (build proposes concept blocks, edit_strategy/edit_queries save changes, run launches searches, import ingests a reference file), so an agent can map an intent to a branch. It does not explicitly distinguish itself from the sibling revisia_search (read) or revisia_jobs, which keeps it just 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?

It opens with the situation that selects the tool ('preparing stage 2') and then gives per-action conditions, including the fallback behavior for run when neither providers nor searches are supplied. It also routes the agent to revisia_jobs for waiting and to revisia_projects for the id, which is explicit when/where guidance.

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