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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, covering the mutation and safety profile. The description adds the useful downstream note that added articles 'then need screening', but leaves vague what 'add' targets (presumably the screening queue) and what result follows. Adequate but thin given annotations carry most of the burden.

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 with zero filler; the scoping fact comes first and the usage restriction second, both earning their place.

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

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

With an output schema present, return values need no explanation, and annotations plus 100% param coverage handle safety and inputs. The description supplies the crucial 'skipped for no identifier' and 'needs screening' context, though it could clarify the effect of adding on run state.

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%, with both parameters (uids array capped at 50, run_id pattern) fully documented. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Add') and a precisely scoped resource ('articles that were skipped for having no DOI, PMID or PMCID'). This population is distinct from every sibling tool's scope, so an agent can identify it without opening a schema.

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

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

'Use only when the researcher asks for them by name' gives an explicit when-to-use condition and an implicit exclusion (don't add them proactively). It stops short of naming a concrete alternative tool, but the constraint is clear enough to route correctly.

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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false; the description corroborates the write behavior by naming concrete side effects (wiki refresh, report write, reply message). It adds real behavioral value beyond the flags, though it omits that the destructive nature is a finalization step and what exactly is overwritten.

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 names the action first and then its effects; every clause earns its place with no filler.

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

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

With an output schema present, return values need not be explained, and the description still notes the reply message is produced. It covers the key side effects for a finalization tool, though it says nothing about state after finishing (e.g., whether the bot run can be resumed).

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?

Only one parameter ('project') and schema description coverage is 100%, so the schema already documents it fully. The description adds no syntax or constraint detail for the argument, matching the baseline for well-covered schemas.

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 (end) plus resource (bot run) and enumerates the three concrete effects: refresh the wiki, write the update report, return the reply message. This clearly distinguishes it from the sibling lifecycle tools bot_start and bot_next.

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 name and 'End a bot run' framing imply when it applies, but there is no explicit statement of prerequisites, ordering relative to bot_start/bot_next, or conditions under which it should not be called.

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 word 'advance' plus 'repeat until finish' conveys that calls are progressive and stateful, aligning with idempotentHint=false and destructiveHint=true; this is useful loop semantics beyond the annotations. However, it never surfaces the destructive/non-readonly nature the annotations declare, and 'returns the next step' could mislead an agent into treating this as a pure read.

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 dense sentences with the verb and sequencing front-loaded and zero filler; the step enumeration is compact and functional.

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

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

With an output schema present, return-value detail needn't be restated, and the description covers the loop framing and termination condition. It could do more to flag the side-effecting nature of each advance, but it is largely complete for a driver tool.

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

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

Schema coverage is 100% and the single 'project' parameter is already documented as 'the bot project named in the job's prompt'. The description adds no additional meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Advance a bot run'), names the sibling that precedes it (bot_start) and the terminal state (finish). Enumerating the possible step outcomes (wait, triage, screen, fetch, wiki, finish) lets an agent distinguish this state-machine driver from siblings like get_run_status or bot_finish.

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

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

Explicitly sequences the call: invoke after bot_start and repeat until finish. This is strong when-to-use guidance within a loop, though it does not state when-not to use it (e.g., versus get_run_status for pure inspection).

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 (which already flag this as a destructive, non-idempotent, open-world write), the description discloses two non-obvious side effects: the project gets locked and a look-back window is scanned. It does not say what unlocks the project or what happens on failure, but the lock disclosure is genuinely additive.

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 sentence with the main verb first and the two effects after the colon; no filler, nothing repeated from the name or schema.

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

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

An output schema exists so return values need no explanation, and the safety profile is covered by annotations. However, for a stateful lifecycle tool named alongside bot_next and bot_finish, the description never places it in that sequence or explains the locked-state consequence, leaving the agent to infer the workflow.

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?

Only one parameter and the schema already documents it at 100% coverage, so the schema carries the semantics. 'lock the project' restates the target but adds no format, identity, or constraint detail beyond the schema, matching the baseline 3.

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

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

States a specific verb+resource ('Begin a ... bot run') and adds two concrete actions (lock the project, search its look-back window), so the agent knows what happens on invocation. It does not differentiate itself from the closely related siblings bot_next and bot_finish, which matters in a bot lifecycle.

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

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

The phrase 'scheduled bot run' hints at context but there is no explicit when-to-use guidance, no prerequisites (e.g. project must be open), and no mention of how this relates to bot_next, bot_finish, start_search, or resume_search.

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, readOnlyHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the on-disk layout detail (wiki plus hidden data folder); it does not warn that repeated calls create duplicates (non-idempotent) or what happens if the target path already exists.

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 tight sentence with the action front-loaded and no filler. The parenthetical '(hidden)' is slightly awkward but carries real information about the data folder.

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

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

With an output schema present and full annotation coverage, the description need only convey purpose and side-effect shape, which it does. The remaining gap is usage routing, which is scored separately.

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%, including the default path (~/med-lit/<name>) and a name example, so the baseline is 3. The description adds nothing about parameter meaning beyond the schema, but nothing is required of it either.

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?

Specific verb+resource ('Create a project') with an added structural gloss that one project equals one folder per review holding a wiki and hidden data. It differentiates somewhat from list_projects/open_project by virtue of being the creation verb, but it never names or contrasts 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?

There is no statement of when to call this versus open_project, list_projects, or project_settings, and no prerequisites (e.g. must the project not already exist). Usage must be inferred entirely from the name and the sibling list.

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=true and readOnlyHint=false, so the safety profile is covered. The description adds scope ('every' page) and the content set it overwrites, which is genuinely useful, but it does not say where files are written, whether existing pages are overwritten or deleted, or what permission the operation requires.

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 sentence, front-loaded with the verb and resource, with no padding. 'From its database' is the only slightly redundant clause, but it usefully clarifies the source of the rewritten 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?

An output schema exists, so return values need no explanation, and the single optional parameter is well covered by the schema. For a destructive, filesystem-touching rewrite, however, the description omits key context such as the target location and how existing pages are handled.

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 single parameter has 100% schema description coverage, so the schema already documents the optional project name and its default. The description adds nothing about the project argument, leaving it at the baseline for high-coverage schemas.

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

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

Names a specific verb (rewrite/export), the resource (every Markdown page of a project's wiki), and enumerates the page types (entities, sources, index, log) plus the source of truth (its database). It is distinguishable from siblings like get_article_page or wiki_tasks, though it never explicitly contrasts itself with them.

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 when-to-use guidance, no prerequisites, and no mention of alternatives among the 28 sibling tools (e.g., wiki_tasks, get_article_page). An agent cannot tell from this text when an export/rewrite is appropriate versus other wiki operations.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=true, so the safety profile is covered. The description adds the useful source-fallback behavior and the batching loop, but never explains why the operation is destructive or what state it mutates, which is the one thing the annotations flag as risky.

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 compact sentences, front-loaded with the action and the source fallback, with the loop condition stated before the pointer. The trailing 'Rules: guide("fetch")' is terse to the point of being cryptic, keeping it from 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?

An output schema exists, so return values need not be described, and the core fetch loop plus fallback order are covered. Missing is any explanation of the destructive/mutating nature flagged by annotations and the external-API failure/rate-limit behavior implied by openWorldHint, leaving a meaningful gap for a batch 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 80%, so the schema documents uids, run_id, max_items and the two retry flags on its own. The description only reinforces that the default target is 'included articles', adding little beyond the schema's 'next pending ones' note; the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch full text of included articles') and adds the source hierarchy (PMC, Unpaywall open access, else abstract), which tells the agent exactly what content it will get. It does not explicitly distinguish itself from siblings like get_article_page or list_articles, so it stops short of a 5.

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

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

'repeat while remaining > 0' gives a clear operational loop, which is genuine usage guidance. However, it defers all detailed rules to guide("fetch") rather than stating them, and there is no when-not-to-use or explicit alternative (e.g. get_article_page).

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

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

Adds a side-effect disclosure not visible in the schema: the call may create the project database despite being a read operation. This is consistent with readOnlyHint=false and the non-destructive, idempotent annotations, so there is no contradiction, though no further behavioral detail (auth, rate limits) is given.

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

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

Two tightly packed sentences; the search scope is front-loaded and the side-effect caveat is appended without extra prose. Nothing 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?

With a 100%-covered schema, an output schema, and annotations, the description carries only the scope plus the database-creation caveat, which is enough to call it correctly. It stops short of describing match ranking or pagination behavior, but that is minor here.

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%, so every parameter (query, project, entity_type, limit) is already documented in the schema. The description's mention of name/alias/acronym/spelling variants only restates the query parameter's schema text, adding no new semantic value.

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 (search) and resource (a project's wiki entities) plus the matching modes (name, alias, acronym, spelling variant). The stated goal of reusing an entity id while extracting distinguishes it from mutation siblings like merge_entities.

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 usage context (reusing an entity's id during extraction) but names no alternative tool and no explicit when-not conditions, so an agent must infer routing against merge_entities or list_articles on its own.

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 idempotentHint=true and destructiveHint=false, and the description adds real context by reconciling the readOnlyHint=false flag: it explains that despite reading only, it 'may create the project database.' This is a genuine side-effect disclosure beyond the annotations rather than a restatement of them.

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

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

A single tight sentence pair: purpose and use case first, alternative second, side-effect note last. Zero filler.

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

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

For a 3-param read with a fully documented schema and no output schema, the description covers purpose, alternative, and the one surprising side effect. It is essentially complete; only the return shape is unstated, which is acceptable given no output schema exists.

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

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

Schema description coverage is 100% and all three params (run_id, uid, page) are documented in the schema, so the schema does the heavy lifting. The description adds no param-level syntax or format detail, 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?

States a specific verb (Re-read) and resource (one page of a fetched article) and explicitly contrasts with the sibling next_wiki_article, which 'serves the pages still to extract.' An agent can distinguish this from next_wiki_article without opening either schema.

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

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

Gives a concrete use case ('to check a quote') and names the alternative (next_wiki_article for pages still to extract), making the when-to-use boundary clear. It stops short of an explicit 'use this instead of X when...' routing statement, but the intent is unambiguous.

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

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

The annotations declare readOnlyHint=false, which would look contradictory for a status check, and the description resolves it by disclosing the real side effect: 'Reads only (may create the project database).' That is exactly the kind of behavioral context structured fields alone can't convey. It still omits auth needs, rate limits, and failure behavior, so it is not 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 compact clauses, progress-tracking purpose front-loaded ahead of the usage directive and the side-effect caveat, with zero filler. Every phrase 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?

An output schema exists, so return values need no explanation, and the description covers purpose, usage trigger, and the surprising side effect. What remains unaddressed (auth requirements, behavior when run_id is unknown) is minor for a single-parameter read-mostly 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?

There is a single parameter with 100% schema description coverage, and the schema already documents run_id's format and origin ('Run ID from start_search'). The description adds nothing beyond the schema, which is the baseline for fully-covered parameters.

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: showing a single run's progress across all stages plus available next steps. It is clearly differentiated from list_runs by being about one run's status, though it never names that sibling. Not a tautology and not misleading.

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?

'Check it rather than chat history' gives an explicit when-to-use directive with an alternative named (chat history / prior context). It stops short of routing among sibling tools like list_runs, so no explicit exclusions are stated, but the usage context is 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that (no mention of freshness, caching, or output detail) but does not contradict them either.

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 tight sentence, front-loaded with the resource type. Efficient, though a large share of its tokens merely restate the schema enum.

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

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

With an output schema present, return values need not be described, and a one-param tool is simple. However, the when-to-use context for this help tool is entirely absent, leaving the agent unclear on how it fits the wider workflow.

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

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

Schema description coverage is 0% and the single topic parameter is an enum. The description merely repeats the enum values verbatim and adds no meaning about what each topic covers or how 'stage' maps to the workflow, so it does not compensate for the coverage 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 resource type (rules and how-to) scoped to a stage, and enumerates the covered topics. An agent can tell it is a reference/help lookup rather than an action tool, though the name 'guide' alone is vague and the description leans on the enum list.

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

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

No guidance on when to call this versus the many action siblings (start_search, set_screening_criteria, etc.). It never says to consult the guide before or during a stage, so the agent must infer its role entirely.

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 safety profile is fully covered. The description usefully adds that returned rows carry screening, fetch, and wiki status, but says nothing about pagination behavior (limit/offset) or result ordering, which matters for a listing 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?

A single front-loaded sentence with zero filler. The scope (a run's articles) and payload (the three status domains) are stated immediately.

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

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

An output schema exists, so return-value explanation is not required. However, with six parameters and only one documented, the description should at least signal that decision/wiki_status/fetch_status are filters and that limit/offset paginate; that omission leaves an agent guessing how to narrow results.

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

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

Schema description coverage is only 17%: run_id has a hint ('Run ID from start_search') and limit/offset have only defaults and bounds. The description's mention of screening/fetch/wiki status loosely maps to the decision, fetch_status, and wiki_status filters, but it never explains that these are filters, nor what their enum values mean, so it fails to compensate for the coverage 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?

Specific verb+resource: it lists a run's articles and enumerates the status domains (screening, fetch, wiki) covered. It is distinguishable from list_runs and get_run_status, but it never names a sibling or the alternative tool for a similar listing need.

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

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

The description gives no when-to-use context, no prerequisites (e.g., that a valid run must exist), and no indication of when a filtered listing is preferable to next_screening_batch or get_run_status. Usage is entirely implied by the name.

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 annotation set declares readOnlyHint=false, and the description explains exactly why: 'Reads only (may create the project database)'. That is genuine added context beyond the structured hints, and the idempotent/no-destruction profile is consistent. It does not discuss pagination or what 'pending' means semantically, keeping it below 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 tight clauses: purpose/scope first, routing second, with the side-effect caveat parenthetically folded in. No filler sentences and nothing repeated from the schema.

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

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

An output schema exists so return values need no explanation, and the description covers scope, the handoff sibling, and the surprising write side effect. What is missing is only minor orientation (e.g., that results are pending items awaiting a decision), which is implied rather than stated.

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%, so the schema already documents limit, run_id, and project thoroughly. The description adds no syntax or semantics for the parameters themselves (no mention of the limit cap or run_id scoping), so baseline 3 applies.

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

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

States a specific verb and resource ('List pending entity pairs that may be the same thing') plus the returned detail ('an example mention of each'), and names the sibling that consumes the output (resolve_duplicates). An agent can immediately distinguish it from resolve_duplicates/merge_entities.

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

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

Explicitly routes the agent to resolve_duplicates for the decision step, so the when-to-use-next is clear. It does not state when not to call it (e.g., after all duplicates are resolved) or any prerequisite ordering beyond the run_id/project params, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuine behavioral context by explaining that available=false signals a moved or missing folder, which helps interpret results beyond what the annotations provide, but it is a single note.

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

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

Two short sentences with no filler, and the core purpose is front-loaded before the field-semantics note. Every sentence earns its place.

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

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

With an output schema present, the description need not enumerate return values, and it correctly focuses on purpose plus the one field whose meaning is non-obvious. For a zero-parameter read-only list tool, this is sufficient.

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 nothing for the description to disambiguate; the baseline for a parameterless tool applies. No parameter-level information is needed or missing.

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 ('List known projects') and adds scope detail ('with their folders'). It is clear what the tool does, though it does not distinguish itself from the adjacent create_project/open_project siblings by naming when each applies.

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: the agent infers it should call this to enumerate available projects. There is no explicit when-to-use, no exclusion of alternatives like project_settings or open_project, and no stated prerequisites.

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 safety profile is covered. The description adds the ordering behavior ('newest first'), which is genuinely useful context not in the annotations. However, it discloses nothing about pagination, result limits, or what happens when no runs exist.

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 sentence that front-loads the verb and resource and includes the ordering constraint without any filler. Every word 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?

For a read-only list tool with an output schema and annotations covering the safety profile, the description is adequate but incomplete. It omits pagination behavior, default limit implications, and any conditions that select it over similar list tools.

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%. The 'project' parameter has a schema description ('Project name from list_projects; may be omitted when only one project exists'), and the description adds no further detail. The 'limit' parameter is undocumented in both schema and description, so the description does not compensate for the coverage 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?

The description states a specific verb ('List') and resource ('a project's searches (runs)') with an ordering guarantee ('newest first'). It clearly distinguishes itself from execution-oriented siblings like start_search and get_run_status, though it does not name them 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?

The description implies usage (list searches for a project) but provides no explicit when-to-use guidance, no differentiation from siblings like get_run_status or list_articles, and no exclusions. Usage is inferred from the verb+resource, which is the minimum viable level.

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 carry destructiveHint=true and readOnlyHint=false, so the safety profile is largely covered. The description earns credit for sharpening the consequence ('irreversible') and clarifying that the destructive action is the folding of merge_ids into keep_id, which confirms the annotation rather than contradicting it. It still says nothing about non-idempotency, failure modes, or what happens when an id is invalid.

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, no filler, with the irreversible warning front-loaded before the alternative routing. 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?

An output schema exists, so return-value detail is unnecessary, and the description covers mutability, irreversibility, and the key sibling alternative. Minor gaps remain around permissions or preconditions, but an agent has enough to invoke 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 description coverage is 100%, so every parameter is already documented in the schema, including the empty-merge_ids rename/retype case and the merge log. The description only restates 'by id' and the rename/retype combination, adding no syntax or format detail 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 specific verbs and resource: merge entities into one, and/or rename or retype, keyed by id. It also marks the operation as irreversible. An agent can distinguish it from list_duplicate_candidates and resolve_duplicates without opening any schema.

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

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

Explicitly routes one case elsewhere: pairs coming from list_duplicate_candidates should go to resolve_duplicates. That is a real when-not rule. It doesn't cover the remaining cases (e.g., multi-way merges not surfaced as duplicate candidates), so it stops short of full routing guidance.

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

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

Annotations declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, but the description's read-framing ('Get the next titles/abstracts') never mentions any state change, consumption of the session, or the destructive effect of advancing/starting a round. Because annotations carry the safety profile the bar is lower, but the description still adds no behavioral context and slightly understates the mutation implied by 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?

A single front-loaded sentence with no wasted preamble. It is efficient, though the trailing 'with the criteria' is vague and the '20 best-triaged articles' clause adds ambiguity rather than 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?

An output schema exists, so return values need not be described, and the schema documents two of three parameters. However, for a stateful tool with a destructive/round-advancing flag, the description never explains when advancing the session is appropriate or what it affects, leaving a real gap for an agent deciding how to call it.

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%: run_id and new_round are documented in the schema, while batch_size is not. The description adds no parameter meaning and its '20 best-triaged articles' phrasing is mildly at odds with the default batch_size of 10. With the schema doing most of the work, a baseline 3 is appropriate.

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 (Get) and resource (next titles/abstracts of the session) and characterizes the payload as the 20 best-triaged articles returned with their criteria. The purpose is understandable, but it does not distinguish itself from the near-identical sibling next_triage_batch, and the parenthetical '20 best-triaged articles' conflicts with the schema's default batch_size of 10, muddying exactly what comes back.

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, no named alternatives (e.g. next_triage_batch, bot_next), and no exclusions. The only conditional logic ('only when the researcher asks') lives in the new_round schema description, not in the tool description, so the description itself offers no routing help.

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 declare readOnlyHint=false and destructiveHint=true, yet the description only says 'Get' and never explains what state is consumed or destroyed, nor what happens if the loop is abandoned without record_synthesis. The queue-advance semantics are only hinted at by 'it repeats until...', leaving the destructive/idempotent profile unexplained.

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 tight sentences with the purpose front-loaded and the loop/terminator condition immediately after; no filler. The trailing 'Rules: guide("synthesis")' is a pointer rather than a wasted sentence, though it shifts essential content elsewhere.

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

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

An output schema exists, so return values need not be described, and the schema fully covers the three parameters. What is missing is the behavior of a destructive, idempotent queue-advancing getter in a 35-tool pipeline, and the operating rules are outsourced to guide().

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%, so run_id, project, and min_sources are already documented in the schema (including the run_id pattern and the wiki.min_sources override). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Get the next entity whose wiki page needs writing or updating, with its evidence.' That is materially more informative than the name alone and delimits the synthesis stage. It does not, however, distinguish itself from the sibling next_wiki_article or explain the entity-vs-article split.

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 repeats until record_synthesis saves it' implies the iteration loop and names the terminating sibling, which is useful workflow context. But there is no when-not guidance, no statement about prerequisites (run_id/project), and the actual rules are deferred entirely to guide("synthesis") 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 cover safety: readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false. The description adds that it returns untriaged titles along with question and criteria for scoring, but omits batch size, pagination, or next-step behavior; the output schema covers return values.

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 no wasted words. It is slightly terse about how the triage batch relates to the surrounding screening workflow.

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 low-complexity, read-only, one-parameter tool with annotations and an output schema, the description adequately states source and purpose. It leaves sibling differentiation implicit, which is a minor 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 100%, and run_id is documented as 'Run ID from start_search'. The description adds no parameter meaning beyond the schema, so the baseline 3 is appropriate.

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?

Specific verb 'Get' and resource 'untriaged titles with the question and criteria'; identifies the triage stage and scoring range. It does not explicitly contrast with sibling tools like next_screening_batch, so it falls short of a 5.

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

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

The phrase 'to score 0-3 before screening' implies this is used during triage before screening decisions. However, it gives no explicit when/when-not guidance or alternatives such as next_screening_batch or record_triage_scores.

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 significant behavioral detail beyond the annotations. It explains that the tool repeats until record_extraction records the page, and that an article whose text changed loses its old extraction first, which directly clarifies the destructiveHint=true annotation.

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

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

Two sentences, front-loaded with the core action and followed by essential behavioral context. There is no redundant or filler text.

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

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

With no output schema, the description supplies the return shape ('a JSON header plus the page') and the iterative recording behavior. It does not detail edge cases like empty results or max_pages effects, but parameter documentation and annotations cover the remaining needs.

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

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

Schema description coverage is 100%, and all three parameters are documented in the schema. The description adds no parameter-specific meaning, so the baseline of 3 is appropriate per the rubric.

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: 'Get the next unextracted page of article text.' It also clarifies scope with 'it repeats until record_extraction records it,' which distinguishes this from the sibling get_article_page and makes the extraction workflow clear.

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 clearly implied: call this to fetch unextracted pages, and repeat until record_extraction records the extraction. The description does not explicitly name alternatives or when not to use this tool, but the workflow context is strong enough for correct selection.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=false and destructiveHint=true, so the safety profile is carried by structured data. The description adds the move/copy scenario, but given a surprising destructiveHint=true on what reads as a benign 'register' action, it should explain what gets overwritten or destroyed — that gap keeps it at 3.

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 zero filler; the core action is stated first and the example follows economically.

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

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

An output schema exists, so return values need no explanation, and the single required parameter is fully documented. The only shortfall is that the destructive annotation is left unelaborated, which is a minor completeness gap for an otherwise simple 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 100% for the single 'path' parameter, which the schema already documents as 'Folder of an existing project'. The description's phrasing mirrors that without adding format, constraints, or edge-case detail, so the 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?

The description gives a specific verb ('register') and resource ('existing project folder'), which implicitly separates it from create_project (new projects). It is clear what the tool does, but it never explicitly names the sibling it differs from, 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 supplies a concrete triggering scenario ('after it was moved or copied from elsewhere'), which is real context for when to reach for this tool. It does not state exclusions or name alternatives like create_project or list_projects, so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this mutates state. The description reinforces caution with 'change them only as the researcher asks', which is useful alignment, but it never explains why the operation is destructive or what the change semantics actually are.

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

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

Two sentences, front-loaded with the show/change dichotomy, and the list of settings is illustrative rather than exhaustive. Little wasted text, though the parenthetical filename adds marginal 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?

An output schema exists, so return-value explanation is unnecessary, and annotations carry the safety profile. With only two optional parameters and full schema coverage, the description is complete enough for 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 description coverage is 100% and both parameters (changes, project) are documented with dotted-key syntax and the omit-to-only-show behavior. The description lists setting categories but adds no parameter-level syntax or format detail beyond the schema, so the 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?

The description names a specific verb pair (show/change) and resource (a project's settings), then enumerates concrete settings such as search years, records per source, and fetch limit, making the scope tangible. It does not explicitly differentiate itself from siblings like create_project or list_projects, but the purpose is unambiguous.

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?

'Change them only as the researcher asks' gives a real conditional constraint on when to mutate versus just show. However, there is no comparison to alternative tools and no explicit statement of when-not to use this tool at all.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds the useful overwrite semantics ('re-recording replaces it'), telling the agent what gets destroyed, but says nothing about auth requirements, side effects on linked entities, or how relationships are reconciled.

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

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

Two short, front-loaded sentences with no padding; the overwrite caveat is placed immediately after the core action. The guide("extraction") pointer is terse but 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?

For a 6-required-parameter write tool with only 17% schema coverage, the description is too thin: it omits parameter provenance (run_id/uid/content_sha256), the maxItems caps on entities/relationships, and any hint of the replace-vs-append model beyond one parenthetical. It relies on the output schema and an external guide it never summarizes.

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

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

Schema description coverage is only 17%, so the description should compensate but adds nothing about parameters. It never explains run_id, uid, content_sha256, or page semantics, leaving the agent to infer provenance and identity requirements from field names alone.

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?

Specific verb+resource: 'Record the entities and relationships extracted from one page.' Clearly distinguishable from sibling recorders (record_screening_decisions, record_synthesis) by its one-page extraction scope. No explicit sibling differentiation is stated, but the resource is unambiguous.

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?

Points to the governing rules via guide("extraction") and warns that re-recording replaces prior data, which is genuine contextual guidance. However, it never states when this should be called versus alternatives, nor any preconditions (e.g. run must exist, page must be fetched).

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 readOnlyHint=false, so the safety profile is covered. The description adds one genuine behavioral constraint beyond the annotations: include/exclude decisions require a verbatim evidence quote. It does not explain batch/concurrency behavior (e.g. what a stale revision does), so this is solid but not 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?

One front-loaded sentence with zero filler; the evidence constraint is stated immediately. It is arguably too terse for a batch-write tool, but nothing in it 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?

An output schema exists, so return values need no explanation. However, this is a batch mutation tool with a revision-based concurrency model (up to 25 decisions, revision from next_screening_batch) and the description does not cover batch semantics, revision conflicts, or what destructiveHint=true means here, leaving real gaps.

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%, with run_id, revision and evidence already documented inline, so the schema does most of the work. The description reinforces the evidence requirement for include/exclude, adding slight value, but says nothing about the 1-25 batch size or the uid/reason fields.

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

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

The description states a specific verb and resource ('Record screening decisions'), so an agent can tell what the tool does at a glance. It does not, however, distinguish itself from close siblings like set_screening_criteria, next_screening_batch, or review_article, which all live in the same screening workflow.

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 mention of the alternatives it belongs to. The workflow dependencies (that run_id comes from start_search and revision from next_screening_batch) are only in the schema, not the description, so an agent gets no routing help from the text.

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 declare destructiveHint=true and idempotentHint=false, and the description reinforces this by stating it is 'replacing the stored one' rather than appending. That is genuine added context about what gets destroyed, though it omits auth/permission prerequisites.

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 tight sentences with the replace semantics and mode distinction front-loaded. The trailing 'Rules: guide("synthesis").' is terse but earns its place as a routing pointer.

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

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

With an output schema present and annotations covering the safety profile, the description does not need to explain return values and mostly does not. It supplies the replace/mode context an agent needs, leaving only permission and rules detail to the guide reference.

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%, so most parameters are already documented in the schema. The description adds the new-vs-update mode framing (mapping loosely to synthesis/sections) but contributes no syntax or format detail beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb (Save) and resource (an entity page from next_synthesis), and distinguishes the two modes: a new page versus only changed sections of an update. It implicitly separates itself from the sibling next_synthesis, which generates the content this tool persists.

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

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

The phrase 'from next_synthesis' implies the tool is used after that sibling produces content, and 'Rules: guide("synthesis")' routes the agent to a rules source. However, it gives no explicit when/when-not conditions or named alternatives beyond these hints.

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 declare destructiveHint=true and idempotentHint=false, meaning re-recording can overwrite prior scores, yet the description never says whether scores can be revised, appended, or clobbered. It also omits the concurrency role of 'revision' (stale writes presumably rejected), which is essential to invoking a non-idempotent mutation correctly.

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 short sentence with the key qualifier ('0-3', 'title scores') front-loaded and zero filler. It is efficient but arguably under-specified for a destructive bulk write with a 500-item cap.

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

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

An output schema exists so return values need no explanation, and the schema covers the score scale and ID provenance. However, for a destructive, non-idempotent bulk mutation gated by a revision token, the description should explain the write/revise semantics; that gap leaves the definition only minimally adequate.

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%: run_id and revision carry descriptions pointing at start_search and next_triage_batch, and the score scale is documented in the nested TriageScore definition. The description merely restates the 0-3 range, adding no meaning beyond the schema, which is the expected baseline at this coverage.

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 ('Record') and resource ('0-3 title scores') with a stated purpose ('decide which articles each session screens'). It does not distinguish itself from near-siblings like record_screening_decisions or record_extraction, which also write per-article judgments, so the agent must infer the distinction.

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

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

No guidance on when to call this versus record_screening_decisions or record_extraction, and no stated prerequisite ordering relative to next_triage_batch. The only hint of context is 'each session,' which is not an actionable condition.

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 non-idempotent, and the description reinforces this by disclosing 'merge (irreversible; keep picks the survivor)' and that 'distinct' means the pair is not suggested again. That is real consequence-level context, though it omits batch-size limits and partial-failure behavior.

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

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

Two tight sentences with the action, consequences, and rules pointer front-loaded; every clause earns its place and nothing is redundant.

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

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

An output schema exists, so return values need no explanation, and the description covers actions, irreversibility, pair source, and rule lookup. The gap is parameter-level detail for the decision objects and batching limits, but for a well-annotated mutation tool this is close to complete.

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%: `project` is documented in the schema, but `decisions` and its fields rely on titles/enums. The description adds meaning to `keep` ('keep picks the survivor'), yet says nothing about `reason`, `entity_id`, or `candidate_id`, so it only partially compensates for the coverage 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+resource ('decide pairs') and names the exact upstream source (list_duplicate_candidates) plus the two outcomes (merge/distinct). An agent can distinguish this from siblings like merge_entities and list_duplicate_candidates 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?

Clear context: decisions operate on pairs from list_duplicate_candidates, and it points to guide("duplicates") for the governing rules. It does not, however, state when to prefer this over merge_entities or any preconditions/ordering beyond the implicit candidate flow.

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, so the safety profile is covered structurally. The description adds mode semantics but says nothing about the blocking wait behavior, resource cost, or the fact that retrying can append new records to an existing run. It does not contradict the annotations, but it adds only modest context beyond them.

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

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

One sentence, front-loaded with the primary action, and each clause corresponds to a genuinely distinct mode of behavior. There is no filler or restatement of the tool name.

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

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

An output schema exists, so return values need no explanation, and the three usage modes are covered. What is missing is the blocking/wait semantics and any note that retry operations mutate an existing run's results, which matters for a tool annotated as destructive and non-idempotent.

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%: run_id and retry_failed_sources are documented in the schema, and the description's third clause reinforces retry_failed_sources. The undocumented wait_seconds parameter — which blocks up to 240 seconds — is never explained in either place, so the description fails to compensate for the coverage 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?

The description names the resource (a search run) and enumerates three distinct operations: checking a running run, retrying a failed run, and retrying failed sources of a completed run. That is specific and actionable. However, it is not fully differentiated from siblings get_run_status and list_runs, which arguably also let an agent 'check' a run, so the boundary is blurry.

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 conditional guidance tied to run state (running vs failed vs completed), which is exactly the context an agent needs to pick this tool. It stops short of naming an alternative such as get_run_status for plain status polling, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the agent knows this is a non-idempotent write. The description adds that the recorded decision is the researcher's own for a single article, but says nothing about overwriting an existing decision or auth requirements — notable gaps given 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?

A single well-formed sentence with no filler, front-loading the core action. Appropriately sized, though somewhat sparse for a four-parameter mutation tool.

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

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

An output schema exists so return values need no explanation, but for a write tool with four required parameters and 25% schema coverage the description leaves behavioral and parameter details thin. Adequate but with clear gaps.

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

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

Schema description coverage is only 25% (only run_id documented), so the description must compensate. It meaningfully maps 'include/exclude decision', 'reason', and 'one article' onto decision, reason, and uid, but leaves run_id's source and uid's identity unexplained — partial compensation 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?

States a specific verb and resource: 'Record ... include/exclude decision and reason for one article.' The phrase 'the researcher's own' hints at differentiation from the bot_* and bulk-record siblings, but it never names an alternative, so the distinction remains implicit.

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?

No when-to-use guidance and no exclusions. With closely related siblings like record_screening_decisions, next_screening_batch, and add_skipped_articles, the description never tells the agent which path selects this tool, leaving it 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is partially covered. Yet the description says nothing about the destructive consequence — that setting criteria starts a new revision and re-screens everything — which the schema only reveals under 'replace'. For a mutation with real re-screening side effects, this is a significant disclosure gap.

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

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

Two short sentences with the core action front-loaded and no filler. The trailing 'Rules: guide("screening")' is cryptic and reads as a stray directive rather than a useful rule, slightly weakening structure.

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

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

An output schema exists, so return values need not be explained, and parameter docs are complete. But for a destructive, re-screening mutation, the description omits the behavioral consequences an agent needs, leaving a real gap despite the rich schema.

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

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

Schema description coverage is 100%, including the key nuance on 'replace' (new revision, re-screens everything), so the schema does the heavy lifting. The description only echoes the include/exclude purpose already documented, adding no new parameter meaning. Baseline 3 applies.

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

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

States a specific verb (Save) and resource (inclusion/exclusion criteria for screening), which is clear. However it does not distinguish this tool from siblings like record_screening_decisions or start_search, so an agent cannot route confidently on the description 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?

The only usage hint is 'Rules: guide("screening")', which points to a sibling tool for methodology rules rather than explaining when to call this tool versus alternatives. It implies a mandatory procedural step but never states when this must be invoked relative to screening.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the agent knows this is a non-idempotent write. The description usefully adds that a run is created in the project and that a running search should be resumed rather than restarted, but says nothing about blocking/wait behavior despite a wait_seconds parameter.

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 compact sentences; the primary action is front-loaded and the conditional resume guidance follows. No filler, though the resume rule is slightly compressed into the same breath as the main action.

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

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

An output schema exists so return values need not be explained, and the description covers the write side effect and the alternate path for in-flight runs. It is nearly complete for a tool of this complexity; only the wait_seconds blocking semantics are unaddressed.

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 75%, so most parameters are already documented in the schema (project, question_id, limit_per_source). The description reinforces the 'approved question' precondition for question_id but adds no new semantics for wait_seconds or limit_per_source. Baseline 3 is appropriate.

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 ('Search the literature databases') plus a notable side effect ('creates a run in the project'). It differentiates from the sibling resume_search by naming it explicitly, though it doesn't distinguish from validate_question, which is the natural predecessor.

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

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

Gives clear conditions: the question must be approved, and if search_status is 'running' the agent should call resume_search(run_id) instead. That routing rule is genuinely actionable. It stops short of stating prerequisites like validate_question completing first, which is left to the schema.

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 it is a non-idempotent, non-read-only, open-world operation, so the bar is lower. The description adds genuinely useful context beyond that: the result must be surfaced to the researcher and approval awaited before proceeding, and it hands back a question_id. It does not say what happens on a failed validation, but the human-in-the-loop gate is the key behavioral detail.

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 action and its output, then the approval requirement, then the guide pointer. Nothing is padded, though the 'Rules: guide("question")' fragment is a slightly awkward standalone tail.

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

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

An output schema exists, so return values need not be explained, and the approval step is covered. Still, for a tool whose argument is a deeply nested research-question object at 33% schema coverage, the description leaves an agent without enough detail to build a valid call without first invoking guide("question").

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

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

Schema description coverage is only 33%, and the description adds nothing about the three top-level parameters (project, sources, question). The nested ResearchQuestion/Filters/Components structure is complex, and the only guidance given is a pointer to guide("question"), leaving the description unable to compensate for the coverage 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 ('Check a drafted PICO/PCC search question against the project's settings') and names the downstream consumer ('return a question_id for start_search'), which distinguishes it from the sibling start_search. It is clear, but the notion of 'check against settings' stays abstract about what is actually validated.

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 workflow constraint is stated ('Show the result, including settings, to the researcher and wait for approval'), and it points at guide("question") for rules. However, there is no explicit when-to-use/when-not or alternative routing (e.g., when to skip straight to start_search), so usage is only implied.

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 the safety profile (destructive=true, idempotent=true, readOnly=false), which is an unusual combination the description never reconciles or explains. The description adds only the task-granularity trait ('each sized for one fresh subagent') and sheds no light on what state the mutation affects or how idempotency works.

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 compact sentences, front-loaded with 'Start here,' with no filler. Slightly penalized because the terse 'Rules: guide("wiki")' fragment is cryptic and would benefit from a few clarifying words without bloating.

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

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

An output schema exists, so return-value explanation is not needed, and annotations cover safety. Still, for a state-touching workflow entry point with a destructive flag, the description omits what calling it does to workflow state, making it only minimally complete.

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

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

Schema coverage is 100% and the single run_id parameter is fully documented in the schema. The description contributes nothing about run_id or its source, and the cryptic 'guide("wiki")' reference adds no parameter meaning, so baseline 3 applies.

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

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

The description frames the tool as the wiki workflow entry point ('Start here to build or update the wiki') that returns 'the current step as self-contained tasks.' The resource is identifiable but the verb is fuzzy - it's unclear whether it returns tasks, advances workflow state, or both - and it doesn't clearly distinguish itself from the 'next_*' 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?

'Start here to build or update the wiki' gives implied entry-point guidance, and 'Rules: guide("wiki")' points to a companion for constraints. However, no alternatives, prerequisites, or when-not-to-use conditions are stated, leaving the agent to infer sequencing.

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