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

Annotations already declare a non-readonly, non-destructive, non-open-world write, so safety is covered. The description adds genuine behavioral value in the form of validation semantics (citation requirement, limitation requirement) and the caveat that a passing citation check does not validate the conclusion. It stops short of saying what happens on failure or whether claims are deduplicated.

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, dense sentences with the core purpose front-loaded and constraints following. No filler, though the terse phrasing borders on cryptic.

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

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

For a 5-required-param write tool with no output schema and thin schema descriptions, it covers purpose and the key type/evidence/limitation rules adequately. It omits any interaction with the update/evidence siblings and says nothing about failure or duplicate handling.

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

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

Schema description coverage is only 20% (only study_id is documented), so the description must carry weight. It does define the meaning of the type values and ties evidence_ids and limitation to specific type values, which is useful, but leaves text and the study_id semantics largely to the schema.

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

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

The description states a specific verb+resource (record researcher claims) and enumerates the three claim types it accepts: fact, inference, unknown. That lets an agent understand the tool's output domain without opening the schema. It does not, however, distinguish this from close siblings such as research_add_evidence or research_add_verification.

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 real conditional rules — fact/inference must cite this study's evidence, and inference must state a limitation — which steers correct invocation. But there is no explicit when-to-use-vs-alternative guidance and no mention of sibling tools like research_add_evidence, so routing must be inferred.

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

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

Annotations only tell the agent this is a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds real behavioral context beyond them: the submission is stored as unverified input and is not promoted to an independently verified fact, which shapes how an agent should later reason about claims built on it. It still omits what the call returns and any permission or rate-limit constraints.

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: the first front-loads the action and accepted input types, the second states the source requirement and the trust caveat. No filler, no 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?

For a mutation tool with no output schema and almost no annotation detail, the description covers the trust model but leaves gaps: no indication of the persisted record's identity/return value, no mention of duplicate handling, study-state prerequisites, or how limitations are surfaced later. It is minimally viable rather than 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 17% — only study_id is documented — so five of six required parameters (title, kind, content, source, limitation) carry no schema explanation. The description implicitly maps the four kinds and stresses that source is mandatory, but says nothing about content vs. limitation semantics or the title field, 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?

The description gives a specific verb (保存/save) and resource (research materials, static code, runtime observations, interview records), matching the kind enum. It is clear what the tool does, but it never distinguishes itself from close siblings such as research_add_claim or research_add_verification, which also write evidence-like records to a study.

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: an agent can infer this is the entry point for ingesting raw source material, and the sentence '必须写明来源' sets a precondition on the source argument. There is no explicit when-to-use/when-not-to-use statement and no alternative tool named for the adjacent tasks (claims, verifications, node capture).

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=false, so the write/non-destructive profile is already known. The description adds genuinely new behavioral context: it only registers a plan and does not execute the target, which prevents the agent from expecting execution side effects. It does not describe permissions or return behavior, but with annotations present this is solid.

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 compact sentence with the verb+resource front-loaded and the important 'register only' caveat appended after a semicolon. No wasted wording, though the two ideas could be split for even faster scanning.

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

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

For a five-required-parameter write tool with no output schema and 20% schema coverage, the definition covers purpose and the registration-only behavior but omits study_id semantics and any routing guidance among the many research_* siblings. Adequate but incomplete.

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

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

Schema description coverage is only 20%, so the description must carry meaning. It maps to steps, expected, and the associated judgments (claim_ids), and references the pending question, covering most required inputs. But study_id is not explained and no format or relationship details are added, leaving the low-coverage schema under-supported.

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 (创建/create) and resource (验证项/verification item) plus the fields it holds (步骤、预期结果、关联判断). It is clearly distinguishable in spirit from research_record_verification, but does not name that sibling explicitly, so differentiation is left partially 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?

The clause '只登记计划，不执行目标' usefully defines a boundary (registration only, no execution), which is a when-not signal. However, it never says when to prefer this over siblings like research_record_verification or research_add_claim, 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?

Goes well beyond the annotations with concrete operational constraints: 180 s timeout, 64 MiB output cap, 512 MiB process heap, no code execution of the target, evidence persistence, and no automatic business conclusions. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with a tool that writes Evidence without destroying anything. This is exactly the extra context descriptions should carry.

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

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

Front-loads the verb+resource in the first clause, then packs limits and constraints into a dense sequence of semicolon-separated clauses. No sentence is wasted, though the constraint stream is heavily compressed into run-on phrasing rather than being structured into discrete facts.

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

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

For a 2-parameter tool with no output schema, the description covers what is produced (raw Evidence), what will not happen (no execution, no business conclusions), and the resource limits. It leaves the return shape and source_paths format implicit, but nothing critical to invoking it correctly is missing.

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

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

Schema coverage is 50%: study_id is documented in-schema but source_paths has no schema description. The description compensates by explaining source_paths' purpose (narrowing scope for large apps) and tying paths to a JS directory. It still omits the array/30-item bounds and the exact path format, so it is helpful but not complete.

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 combination: running the built-in syntax scanner over the unpacked JavaScript directory of the current research, and saving raw Evidence. This clearly distinguishes it from siblings like research_read_source or research_import_analysis. An agent knows exactly what operation is performed.

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 real scoping context: only standard JS, no JSX/TS/ASAR/.app, and advises providing source_paths to narrow scope for large apps. It excludes unsupported input types but never names an alternative tool to use for TS/JSX targets, so routing is implied rather than explicit.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds real value by disclosing that the study disappears from the default list, that its materials are retained, and that the operation is reversible. That is meaningful behavioral context beyond the structured hints, though permission requirements are still unstated.

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

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

Two short, front-loaded clauses with no filler: the action first, then the consequences. Every clause carries information, though the semicolon-separated packing is terse enough to feel telegraphic.

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?

No output schema exists, so the description must convey outcomes — and it does: list-hiding, material retention, reversibility. For a single-parameter state-change tool with matching non-destructive annotations, this is close to complete; only auth/permission context and the meaning of study_id are missing.

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

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

There is one required parameter, study_id, with 0% schema description coverage, and the description says nothing about it — no ID format, source, or how to obtain it. The pattern '^r_[a-f0-9]{8}$' in the schema hints at format, but the description does not compensate for the coverage gap as the rubric requires at this coverage level.

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 ('归档研究' / archive research) and adds scope detail: it is hidden from the default list and materials are retained. This implicitly separates it from research_delete and signals research_unarchive as the inverse, though neither sibling is named explicitly.

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

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

Usage is implied — archive when you want the study out of the default list without losing data — but there is no explicit when-to-use, when-not, or named alternative (e.g. research_delete for true removal). The reader must infer the routing decision.

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

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

Annotations already declare readOnly=false, destructive=false, openWorld=false, and the description adds genuine context beyond them: the archive and trash regions are included, and existing files are not overwritten. It does not address auth, timing, or output location, but the non-overwrite disclosure is exactly the kind of behavioral fact an agent needs.

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

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

One compact sentence front-loads the core action (whole-library ZIP) followed by scope qualifiers and the non-overwrite guarantee. 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 only one parameter, no output schema, and consistent annotations, the description covers what gets packaged and the overwrite policy well. It still leaves the 'output' parameter meaning and any size/time expectations to inference.

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

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

Schema coverage is 0% with a single required 'output' parameter that is never described. The mention of ZIP packaging and non-overwrite behavior hints that 'output' is a destination path, but the description never names or explains the parameter, format, or pattern constraints.

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 (pack/bundle) and resource (the entire research library plus referenced raw materials) with clear scope (ZIP, including archived and trash areas). No sibling performs a backup, and the operation 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?

The description implies a full-library backup use case but never states when to reach for it versus siblings like research_archive or research_report. Usage is inferable from the verb, not spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral value by stating what is persisted (source location and file hash) and that it deliberately does not validate the source text. It omits idempotency (what happens when the same chunk is registered twice) and error behavior.

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

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

A single tight sentence with three meaningful clauses: the action, what is retained, and the non-validation caveat. Nothing is padded or repeated, and purpose is front-loaded. It is arguably too terse for a 4-required-parameter mutation tool, which costs it a point.

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

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

A mutation tool with four required ID-style parameters, no output schema, and no schema descriptions needs the description to explain the identifier roles and the return/registration outcome. The description covers neither, and leaves open whether duplicate registration is possible. What it does say is accurate but far from 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?

Schema description coverage is 0% across 4 required parameters, so the description carries the burden and fails to meet it. It mentions neither study_id, document_id, chunk_id nor title, and does not explain the ID format conventions (r_/d_/chunk_ prefixes). 'Preserves source position and file hash' does not map to any input parameter, so nothing 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 concrete verb+resource: registering a selected document chunk as citable evidence. It is clearly a capture/registration operation, distinct from read tools like research_document_chunks or research_get. However, it never differentiates itself from the closest siblings, research_add_evidence and research_capture_node, so an agent still has to guess which capture path 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 implied rather than stated: the chunk must already be 'selected' and the tool turns it into citable evidence. The caveat '不验证原文真实性' hints that verification is a separate step, but no sibling (research_add_evidence, research_record_verification) is named as the alternative, and no exclusions or prerequisites are given.

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

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

Annotations already establish write/no-destroy/no-open-world, but the description adds real behavioral value beyond them: repeated registration of the same node reuses the existing evidence (idempotent dedup), and the original Evidence ID, node ID and hash are preserved. It still omits failure behavior and what the call returns.

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, with the core action stated first and the idempotency behavior second. Nothing is padded or 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?

For a non-destructive write tool with four required parameters, no output schema and 25% schema coverage, the description covers the what and the dedup rule but leaves parameter meaning, prerequisites (e.g. an existing analysis_id) and the return value (evidence ID?) 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 only 25% (only study_id is documented), so the description carries the burden and does not meet it: analysis_id, node_id and title are never explained. Worse, it references "Evidence ID 与哈希" which are not parameters at all, potentially misleading the agent about the input surface.

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 (登记/register) and resource (已选择的静态节点 → 可引用证据), making the transformation clear. It does not, however, distinguish this from the sibling research_add_evidence, which an agent could easily confuse it with.

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

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

"将已选择的静态节点" implies a precondition — the node must already be selected — which gives implicit usage context. There is no explicit when-to-use/when-not guidance and no mention of how this differs from research_add_evidence or research_find_nodes.

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 write (readOnlyHint=false), closed-world (openWorldHint=false) and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: target is an optional unpacked-JS-directory path and no app auto-discovery happens. It still omits idempotency, permissions, and what an existing record conflict does.

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

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

Two sentences, front-loaded with the core purpose before the target qualifier, with no filler. Slightly terse relative to the number of unexplained parameters, but 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?

For a create tool with no output schema and minimal annotations, the description covers the action and the trickiest parameter (target) but leaves title and demo semantically undocumented and says nothing about the created result. Adequate but with clear gaps for a 4-parameter creation 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 0%, so the description carries the full burden. It clarifies target (optional absolute path to an unpacked JavaScript directory) and implicitly maps question→'用户的具体问题' and target→'明确选择的目标', but gives no meaning for title, and 'demo' is never mentioned at all despite being a required boolean.

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: '建立产品功能研究' (create a product feature research), plus what it persists (the user's question and selected target). An agent can identify it as the creation entry point among the research_* siblings. It does not, however, explicitly contrast itself with research_update or the other create-adjacent tools.

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 or when-not-to-use guidance and no named alternative. The lone constraint '不自动寻找其他应用' is a scoping note about the target rather than a routing rule, so an agent gets no signal on when to prefer this over research_update or research_import_document.

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 and destructiveHint=true, so the safety profile is covered. The description adds the substantial detail that this is a soft removal into a recycle area that preserves the original evidence and can be undone via undelete — valuable context that reframes 'destructive' as recoverable. Not a contradiction, but a meaningful qualification of the 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?

One compact sentence that front-loads the action and appends the reversibility guarantee; 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?

For a single-parameter mutation with no output schema, the description covers purpose, scope, and reversibility, and the annotations cover the safety profile. An agent has everything needed to invoke it correctly; return-value details are unnecessary 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 0%, so the description carries the burden of explaining the single parameter. 'Explicitly selected research' hints that study_id targets one specific item rather than a bulk/recursive delete, but the required ^r_[a-f0-9]{8}$ identifier format and where to obtain it are never mentioned, so the compensation is only partial.

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

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

States a concrete verb+resource pair — moving an explicitly selected research item into the recycle bin — which is far more informative than the bare name research_delete. It also differentiates from research_undelete by naming it as the inverse operation, though it does not distinguish itself from the sibling research_archive, which is the main adjacent concept an agent must choose between.

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 tells the agent the operational context (explicit selection, reversible removal) and names the recovery alternative (undelete), which is enough to route correctly in most cases. It stops short of an explicit when-not-to-use clause, e.g. archive vs delete, so the choice against research_archive is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description's 'does not modify configuration' largely restates readOnlyHint, while 'does not check or install native decompilation engines' adds a useful scope boundary; still, no output format, permissions, or rate-limit context is supplied, so the extra disclosure is thin.

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 three clauses, each adding specific scope: inspected items and two non-goals. No filler or redundancy.

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

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

With no output schema, the description carries return-value burden and does list the inspected categories (version, data directory, analyzer info), which is enough for a diagnostic tool. It stops short of describing output format or interpretation, but the core scope is covered.

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 no parameters, so the baseline is 4. The description appropriately says nothing about parameters and the empty schema is self-explanatory.

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 (检查/check) and concrete resources it inspects: tool version, data directory, and built-in analyzer information. This is not a tautology and is distinct from sibling mutation tools like research_update, though no sibling alternative is named.

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 explicit exclusions—does not modify configuration, does not check or install native decompilation engines—which help an agent avoid mis-invoking it for setup mutations or engine installation. However, it does not state an explicit 'use when' trigger or name alternative tools for those excluded tasks.

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, openWorldHint=false, destructiveHint=false, so safety is covered. The description adds genuine behavioral context: it returns page numbers/paragraphs/line numbers and checks original-vs-extracted hashes. It does not describe pagination limits or result shape beyond the return fields.

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

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

A single front-loaded sentence with no filler; the pagination/search verb leads and the RAG disclaimer comes last. The semicolon-separated hash clause is dense but earns its place by flagging an integrity behavior.

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

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

With no output schema, the description usefully states the return content (page/paragraph/line numbers), and annotations cover safety. But for a 5-parameter tool at 0% schema coverage it leaves parameter roles and pagination semantics underspecified, so an agent lacks what it needs to call it precisely.

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

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

Schema description coverage is 0% across 5 parameters, so the description must carry the load. It only loosely implies pagination (offset/limit) and search (query) roles, and does nothing to explain study_id/document_id or the query's literal-matching, maxLength, or limit bounds.

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 with scope modifiers: paginate OR literal-search document chunks, and disambiguates from RAG semantics. It does not name the most relevant siblings (research_read_source, research_capture_document_chunk), so sibling differentiation is only 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?

Usage is implied by 'literal search' versus 'pagination', which tells an agent the two modes, and '不是 RAG' (not RAG) sets a boundary. However, there is no explicit when-to-use/when-not or names of alternatives among the many siblings, so selection among them is left to inference.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, so the safety profile is covered. The description adds that search is by 'literal' keyword (not semantic) and that results are paginated, which is useful context beyond annotations, but says nothing about ordering, result shape, or limits.

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 filler that efficiently conveys both operating modes. It is compact, though the density means some clarity is traded away.

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

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

For a 5-parameter tool with no output schema and low schema coverage, the description covers the entry modes but omits parameter semantics, return format, and the reason study_id/query/offset/limit are all required. 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 coverage is only 20% (only study_id is documented), so the description must compensate. It does conceptually map evidence_id (by ID), query (keyword), and offset/limit (pagination), but adds no format, pattern, default, or range detail for the undocumented 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?

The description states two concrete modes (fetch evidence by ID, or search registered evidence in a study by keyword with pagination), which is a specific verb+resource. It doesn't differentiate itself from siblings like research_find_nodes or research_add_evidence, 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?

It implies the two usage modes (ID lookup vs keyword search) but gives no when-to-use guidance against alternatives, no exclusions, and no note about how the two modes interact with the required parameters. Usage is inferable but not explicit.

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

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

Annotations already establish a safe read (readOnlyHint=true, destructiveHint=false). The description adds real behavioral context beyond them: literal vs semantic matching, that specifying node_id returns a full node with coverage limits, and that nodes do not represent actual runtime behavior. That runtime caveat is a genuine disclosure not captured 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?

Three tight clauses, front-loaded with the primary search behavior before the node_id alternate path and the runtime caveat. Every sentence carries information; 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?

For a 6-parameter tool with 17% schema coverage and no output schema, the description covers the two most semantically loaded parameters but leaves pagination bounds and analysis_id unexplained, and offers nothing about result shape. Adequate but with visible 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 17%, so the description bears most of the load. It adds useful meaning for query (literal keyword, not semantic) and node_id (reads full node plus coverage limits), but offset, limit, and analysis_id are left entirely undocumented. Partial compensation for a low-coverage schema.

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

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

States a specific verb (literal keyword search) and resource (complete static analysis graph) with pagination, and carves out a distinct node_id read mode. The clarification that query is not semantic search sharpens the purpose well. It stops short of naming which sibling to prefer for non-keyword lookups, so it doesn't fully differentiate within the crowded research_* family.

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 explicit 'query is not semantic search' and the node_id branch imply when each mode applies, but there is no clear 'use X instead' routing against siblings like research_analyze or research_read_source. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds the useful fact that results are a catalog/overview rather than full evidence, but says nothing about pagination, size limits or permissions. Adequate 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?

A single semicolon-joined sentence, front-loaded with what is retrieved and ending with the sibling pointer. Dense but efficient, with no filler; the long enumeration makes it slightly harder to scan than an ideal definition.

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

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

There is no output schema, so the description carries the burden of telling the agent what comes back, and it does so by listing the five content categories while deferring bulk evidence to research_evidence. Combined with full parameter coverage and read-only annotations, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% for the single study_id parameter, and the schema itself explains that it is the research ID returned by research_create. The description adds nothing about the parameter, 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 uses a specific verb (查看/view) and enumerates the resources returned: research questions, judgments, verification records, analysis scope and evidence catalog. It also explicitly contrasts itself with the sibling research_evidence, so an agent can distinguish the two. It falls just short of 5 because the enumeration is a laundry list rather than a synthesized statement of the tool's role (study overview).

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 clear routing guidance: use this tool for the overview, and use research_evidence when full evidence is needed. That is an explicit alternative with a selecting condition. It does not, however, state an explicit when-not-to-use case or any prerequisites beyond the implied one.

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, broken out as a write operation, and the description adds genuinely useful context beyond them: the 64 MiB input cap and the explicit security boundary that importing does not grant read access to local paths referenced inside the JSON. It still omits failure behavior or whether an existing analysis is replaced, so it is not exhaustive.

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 led by the action and resource, with the size limit and security caveat appended in priority order. No filler text; the single-sentence structure is efficient, though the security clause is slightly dense.

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

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

For a 2-parameter write tool with annotations and no output schema, the description covers the resource, the input size ceiling, and a key security boundary. It leaves unclear what the call returns or how it interacts with an existing study's data, which for an import/mutation tool is a notable remaining 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 coverage is 50%: study_id is documented in the schema ('研究 ID，由 research_create 返回') but path has no description. The description partially compensates by implying path is a user-selected file ('用户选择的完整...JSON') subject to the 64 MiB limit, but adds no format, path-syntax, or boundary details.

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 (导入/import) and a well-scoped resource (完整兼容的 JavaScript 分析 Evidence JSON), plus a concrete size bound of 64 MiB. The described resource is distinct enough from research_import_document and research_add_evidence, though it never names those siblings to disambiguate 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?

No when-to-use or when-not-to-use guidance and no routing to alternatives such as research_import_document or research_add_evidence. The only conditional statement is a security caveat about what import does not authorize, which is a behavioral constraint rather than usage 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 readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is partly covered. The description adds genuinely non-obvious behavior: no OCR, no execution of instructions embedded in file content (a prompt-injection guard), and no model calls. These are real behavioral disclosures beyond the annotations, though it does not state permissions or side effects on the study record.

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

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

A single dense sentence that front-loads the action, then the formats, then the preserved metadata, then the exclusions. It is efficiently structured with no filler; the only cost is that the semicolon-separated constraints are packed tightly enough to be easy to skim past.

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-parameter tool with no output schema and no schema descriptions, the definition covers capability and constraints but leaves the parameters and the resulting effect on the study (what record is created, what is returned) unexplained. Annotations cover the safety profile, so the remaining gap is parameter and outcome detail.

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

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

Schema description coverage is 0% for all three parameters (path, title, study_id), so the description is the only place semantics could be added, and it explains none of them. It implies path is a local filesystem location but gives no format, size, or extension guidance, and says nothing about the study_id pattern or how title is used.

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 (extract/import a document) plus the supported source formats (TXT/MD/DOCX/text-based PDF) and what metadata is preserved (file hash, source location). This makes it distinguishable in spirit from research_import_analysis, but the description never names a sibling, so the differentiation must be inferred.

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 implicit negative guidance: '文字型 PDF' and '无 OCR' tell the agent this tool is not for scanned/image PDFs, which effectively scopes selection. However, no alternative tool or positive precondition is named, so the agent gets a boundary but not a routing rule.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds the meaningful behavioral detail that archived/deleted items are excluded unless status is overridden, which is useful, but says nothing about ordering, volume, or return shape.

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, front-loaded with the action and scope, then the enumerated values. Nothing is padded.

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

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

For a trivial one-parameter read-only list tool with no output schema and full annotation coverage, the description tells an agent everything needed to call it. Only minor gaps (ordering, pagination) remain and are low-risk for this tool type.

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%, but the single parameter's enum and default are already self-documenting in the schema. The description merely restates the same four values and the same default, adding no syntax or meaning beyond the structured data.

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 research) and specifies the default scope (only active items). It does not distinguish this from siblings like research_get or research_find_nodes, so an agent must infer the role from the name 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 mention of the active-only default implies when you'd change status, but there is no explicit when-to-use statement or named alternative (e.g. use research_get for a single item). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds real behavioral context beyond that: hash verification before reading, restriction to previously analyzed unpacked directories, and explicit refusal of path escape and changed files. These are concrete safety and scope behaviors not encoded in 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?

Two tight sentences, front-loaded with the core action (reading source lines) followed by the safety constraints. Little wasted text, though the parameter set is never addressed.

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?

Behavioral context (hash check, scope limits, rejection rules) is well covered, which is valuable for a no-output-schema tool, but with five required parameters at 20% schema coverage the definition leaves the agent guessing about how to supply valid inputs.

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

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

Schema description coverage is only 20% (only study_id is documented), yet the description explains none of the five required parameters — node_id, analysis_id, observation_index, and context are left entirely undefined. For a five-parameter tool with poor schema coverage, the description does not compensate.

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: reading a small set of source lines for a static clue, with hash verification first. This is clearly distinguishable from siblings like research_document_chunks or research_find_nodes, though it does not explicitly name an alternative tool.

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

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

Gives meaningful preconditions — only directories this tool has already analyzed and that the user specified — and states that path traversal and file changes are rejected. However, it does not tell the agent when to prefer this over other read-style siblings, 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 declare a non-read-only, non-destructive write. The description adds real behavioral context beyond that: historical attempts are retained (append-only history), and judgments are never auto-escalated, which tells the agent the write is additive and non-inferential. It does not cover permissions or error behavior, 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?

Three compact clauses with no filler, and the core action is front-loaded before the constraints. The semicolon-separated rules are dense but readable, though the evidence and no-escalation rules could be ordered more helpfully.

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

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

For a five-required-parameter mutation tool with no output schema and 20% schema coverage, the description covers the evidence-citation rule and append semantics but omits the identity parameters and how this differs from research_add_verification. It is minimally viable rather than 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 description coverage is only 20%, with study_id the lone documented property, so the description must carry most of the burden. It partially compensates by tying evidence_ids to passed/failed outcomes and naming the observed content, but explains nothing about the required study_id/verification_id linkage or the status enum semantics.

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 (人工验证的实际观察与通过/失败/阻塞状态), so an agent knows it writes a manual verification outcome rather than a claim or evidence. It does not differentiate itself from the closely-named sibling research_add_verification, leaving ambiguity about which one to call.

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 when the tool applies (recording manual verification results) and states a precondition (passed/failed must cite evidence), which is usable guidance. However, it never addresses the obvious alternative, research_add_verification, nor when a blocked status is appropriate versus passed/failed.

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

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

Adds real context beyond annotations: default is content return, providing an absolute path writes a new file, existing files are never overwritten, and the report is a research record rather than model-verified output. This explains the write-but-not-destructive nature consistent with readOnlyHint=false, destructiveHint=false, and the non-overwrite claim meaningfully de-risks invocation.

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

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

Three tight sentences, purpose front-loaded, then the output-behavior branch, then the disclaimer. 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?

For a 3-parameter tool with no output schema, the description covers the essential behaviors an agent needs: what is produced, where it goes, and the non-overwrite guarantee. The study_id link to research_create is only in the schema, but that is acceptable given its documented pattern and description.

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

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

With only 33% schema coverage, the description compensates well: it names the two formats (markdown/json) and describes the output parameter's behavior (absolute path triggers file write, no overwrite). Only study_id is left to the schema, where its description already lives.

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: compile a Markdown or JSON report with citations and limitations. An agent can identify the output artifact precisely, though it doesn't explicitly contrast itself with sibling tools like research_get or research_analyze.

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 one clear behavioral branch: default returns content, specifying an absolute output path writes to a new file. That is effectively a usage rule for the output parameter, but there is no explicit guidance on when to choose this tool over related siblings such as research_analyze or research_get.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses that the ZIP is validated first, that the existing database is not overwritten, and that historical application paths are not readable. These are meaningful and consistent with destructiveHint=false, but failure behavior and auth requirements remain undisclosed.

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 packs the operation, the destination constraint, and two safety guarantees with no filler. Dense but well ordered.

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

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

With no output schema and no param descriptions in the schema, the description correctly covers the safety profile and target constraints, but omits what a successful restore produces, failure handling, and explicit path/destination semantics. 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 0% for the two params, so the description carries the burden. It partially does: 'ZIP 备份' implies path is the archive and '新目录' implies destination is the target directory, giving usable semantics even though neither is tied to its parameter name explicitly.

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 pairs specific verbs (校验/恢复 = validate/restore) with a clear resource (ZIP 备份) and target (尚不存在的新目录). It is easy to distinguish from the backup-creating sibling, though it never names an alternative explicitly.

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

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

It states two constraints on use – the destination must be a not-yet-existing directory and the current database is not overwritten – which implies when the tool is appropriate. However, it never frames the backup/restore relationship or says when to choose this over research_backup, leaving usage 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 this is a non-read-only, non-destructive, non-open-world mutation, so the agent knows the safety profile. The description adds real behavioral context beyond that — the observable effect is the study reappearing in the default list — but omits idempotency, error behavior when the study is not archived, and any permission requirements.

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

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

One compact sentence with the effect front-loaded after the verb; nothing redundant. It is arguably too terse rather than bloated, but as a structure it is clean and wasting no words.

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

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

For a simple single-parameter mutation with no output schema, the description covers the essential effect and the annotations cover safety, so the core is adequate. It still leaves the identifier semantics and the error/precondition behavior unaddressed, which are the remaining gaps an agent would want closed.

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 required parameter study_id has 0% schema description coverage and a pattern but no explanation, and the description never mentions it. For a 1-param tool with no schema documentation, the description should at least clarify what identifier is expected (a research/study ID, format r_xxxxxxxx), which it entirely omits.

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 (取消归档 / unarchive) and resource (研究 / research), and the inverse relationship to the sibling research_archive is apparent from the name pairing. It is clear what the tool does, though it never names its counterpart explicitly to help the agent choose between archive/unarchive.

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 clause '让研究重新出现在默认列表' implies the use case (restoring a hidden study to the default listing), which implicitly tells the agent when to reach for it. However, there is no explicit when-to-use guidance, no mention of the prerequisite state (item must currently be archived), and no comparison against siblings like research_restore or research_undelete.

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 (readOnlyHint=false mutation with destructiveHint=false), so the description only needs to add context. It does add one useful fact beyond the annotations: the original archive state is restored along with the object. It does not say what happens if the id is not in the recycle bin, whether the call is idempotent, or what permissions are required.

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 short sentence with the restore action and scope front-loaded and no filler. It is lean and well-structured, though its brevity edges toward under-specification rather than optimal density.

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 mutation tool with no output schema, an undocumented required id, and no error semantics, this is too thin. An agent would not know what happens when the research is not in the recycle bin, whether archive state restoration can fail, or what the call returns.

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% for the single study_id parameter, and the description never mentions it or explains that it must reference a previously deleted research. Only the name and the regex pattern in the schema convey format, 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?

Specific verb (恢复/restore) plus resource (研究) plus scope (从回收区, 原归档状态), so the agent knows this pulls back a deleted research object and reinstates its prior archive state. It stops short of explicitly distinguishing itself from close siblings like research_restore and research_unarchive, which is the only thing keeping it out of the top band.

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

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

The phrase 从回收区 (from the recycle bin) implies this is the undo of research_delete and supplies implicit timing context. There is no explicit statement of when to prefer it over research_restore or research_unarchive, and no prerequisites or failure conditions are given.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description usefully narrows the blast radius: it preserves revision history and does not touch existing evidence or judgments. This adds real behavioral context beyond the annotations, though it omits auth requirements and reversibility details.

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 that front-loads the action and scope; no filler or redundancy.

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

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

For a mutation tool with annotations but no output schema, the description covers what changes and what is preserved, but leaves gaps on the required identifier, the partial-update semantics, and the return behavior, which matter 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 coverage is 0%, so the description must compensate. It names the two mutable fields (title, question) but says nothing about the required study_id identifier or the format constraint (^r_[a-f0-9]{8}$), and does not clarify whether both fields must be supplied or at least one.

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: modifying the research title or question, with a clear scope qualifier ('不改写已有证据和判断'). An agent can tell this is an edit operation rather than create/delete, though it does not name a sibling to distinguish from (e.g., research_create or research_add_claim).

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 implied by the scope statement — use this to change a study's title or question. However, no explicit when-to-use-vs-alternative guidance is given, nor are prerequisites or the case where neither field is supplied addressed.

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