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

With no annotations, the description carries the full burden and discloses that dryRun defaults to true, real writes require a prior content pass, and successful writes change state to beautifying. It also states that the tool returns a snapshot for rollback and diff_after_beautify, that the calling agent authors lecture prose, and that this tool does not call a model. Several explicit fail conditions further clarify behavior.

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

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

The description front-loads the key operational facts: reread, generate, execute, dryRun default, and write prerequisites. It is longer than a minimal description, but most sentences convey relevant gating or state-transition information. The final failure-condition list is somewhat repetitive, though still tied to correct usage.

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 complex mutation tool with no annotations and no output schema, the description covers critical context: default dry-run behavior, write prerequisites, state transition after success, and snapshot return. It remains incomplete on the semantics of allowRecreate and includeDestructive, and it does not describe the snapshot structure. Even so, an agent can understand the main safe invocation pattern.

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%, and the description adds meaning mainly for dryRun by explaining that it only reports intended actions. It does not explain allowRecreate or includeDestructive, both of which are potentially important booleans, and it adds little beyond the schema for opIds and themeId. pageId is implicitly required but not elaborated.

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 clearly states that the tool re-reads the page, generates a plan, and executes it, with dryRun defaulting to true. It also distinguishes the write path from rollback and diff_after_beautify by mentioning the snapshot it returns. It is specific about the core action, though it does not directly contrast itself with siblings such as draft_lecture or run_lecture_pipeline.

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 explicit preconditions for real writes: handoff_status content_pass or beautifying, and only gate.pass true counts as passing. It also states that dryRun defaults to true and only reports intended actions, which guides safe first use. It stops short of naming alternative tools for planning or drafting.

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?

With no annotations the description carries full burden and mostly succeeds: it declares 只读 (safe, no mutation) and discloses the detection rules — KaTeX for display math, bracket pairing only for database formulas, and API 'unsupported' results counted as broken. That framing matters because it tells the agent what the findings mean. Permissions requirements and any size/rate limits are not mentioned.

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

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

Four short sentences, each doing distinct work: what is scanned, what is returned, the read-only guarantee, and the defect criteria. The result and safety statements are front-loaded where an agent will read them.

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 annotations, the description supplies enough: it says findings are a list of locations plus reasons. It stops short of describing the shape of that list (grouping, snippets, severity ordering), which an agent would want for a rich audit report.

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 only one parameter and schema description coverage is 100%, with pageId documented as '页面 id 或页面 URL'. The description adds no further parameter detail, which is acceptable at this coverage level but earns only the baseline.

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 (行内公式、公式块、数据库公式属性), and enumerates what counts as a defect. It is clearly narrower than siblings like audit_page or audit_structure, though it never names them to make the separation explicit.

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

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

The scope (page-level, formula-only, read-only) implies this is the tool for formula validation before rendering, but there is no explicit when-to-use guidance and no statement of when to pick audit_page or audit_structure instead. Inference is required.

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?

With no annotations, the description carries the burden well: it explicitly declares read-only behavior ('只读，不修改页面'), discloses that no model is invoked ('本工具不调用模型'), and enumerates what is returned. That is meaningful behavioral context an agent cannot get from the schema. It stops short of error behavior or what the five dimensions 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?

The first two sentences are tight and front-loaded, but the text then drifts into pipeline-level content that is not about this tool ('MCP 负责抽课件...写入 Notion 和美化', '跳步 = Fail') and a downstream gate rule referencing gate.pass, which is never defined here. Some of the Fail rules are legitimate audit criteria, but the pipeline narration dilutes focus.

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 annotations and no output schema, the description does a reasonable job describing the return shape and the read-only/no-model nature. However, it leaves the five scoring dimensions unnamed, references a gate.pass field that appears nowhere in the schema or description, and mixes in unrelated pipeline responsibilities, so an agent still can't fully predict what it gets back.

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

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

Schema coverage is 100%, so both parameters are already documented, including the three theme values. The description adds only that scoring is theme-relative ('按主题打分'), which hints at why themeId matters but gives no detail on how the theme changes scoring. 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?

The opening sentence gives a specific verb and resource (reads a page, scores it by theme) and states the return payload: five-dimension scores, an issue list, and per-issue fix suggestions. It roughly positions itself as the 'content audit' step (内容审), but never names its closest siblings (audit_formulas, audit_structure, scan_layout_rules), so an agent must infer the boundary between 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?

Usage is only implied: '内容未过关就美化 = Fail' and the gate.pass remark suggest this runs as a pre-beautification gate. There is no explicit statement of when to call this versus the other three audit_* tools, and no stated prerequisites (e.g., must the page exist / be ingested first).

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?

With no annotations, the description carries the full burden; it does disclose the key traits — read-only, report-only, no page mutation, and no judgment of content correctness. It says nothing about the shape of the report, what happens on an unreachable page id, or whether a rendered page vs. source is required, which leaves real gaps for a tool with zero structured annotations.

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

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

Front-loaded with the category label ("规则检查：") followed by the concrete checks, then two short scope constraints. Nearly every clause earns its place, though the dense enumeration takes a second read to parse.

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 read-only audit with no output schema, the description covers what is checked and what the tool will not do, which is the core need. It is still incomplete on report format and on routing among the several audit/scan siblings.

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, pageId, and the schema already documents it at 100% coverage ("页面 id 或页面 URL"), so the baseline is 3. The description adds no extra meaning about the parameter (e.g., which page versions are addressable), so it does not exceed the baseline.

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 concrete, enumerable rule set (icon/callout marking, step-number gaps, use of 「显然/略」 to skip derivations) that makes clear this audits page structure for beginner readability. The verb+object is only implicit ("规则检查" plus a list), and it never names how it differs from audit_page, audit_formulas or scan_layout_rules, so not 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?

"只报告，不改页面" and "不判断内容对错" set useful negative boundaries (read-only, not a correctness review), which steers the agent away from misuse. But it never states when to choose this over audit_page or scan_layout_rules, so usage is only implied rather than directed.

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

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

No annotations are provided, so the description carries the full burden. It states '只读' (read-only), which is a key behavioral trait, and defines what counts as a factual change, but omits details about permissions, rate limits, or output format.

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

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

Three sentences, front-loaded with the core comparison task, followed by detection scope, exclusions, and read-only status. No fluff; 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?

Covers the purpose and detection scope well, but lacks explanation of the return format (especially since there is no output schema) and does not describe the pageId parameter. For a diff tool, an agent would benefit from knowing how issues are reported.

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 description clarifies that 'snapshot' comes from apply_plan, but leaves 'pageId' completely unexplained and does not detail the expected snapshot structure. It only partially compensates for the schema gap.

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

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

States a specific verb ('对照' / compare) and resources (snapshot from apply_plan vs current page content), and clearly defines the two problem classes it detects, plus exclusions. This distinguishes it from generic audit tools like audit_page or audit_formulas.

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 usage after apply_plan produces a snapshot, but does not explicitly state when to use this tool versus alternatives such as audit_formulas or audit_page. No when-not guidance is provided, though the read-only note is helpful.

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?

No annotations are provided, so the description carries the behavioral burden. It clearly discloses key non-effects: it does not call a model, does not write to Notion, and only returns skeleton and excerpts. However, mention of '内容审' and 'gate.pass' could imply this tool returns a gate status, and the 'MCP 负责...写入 Notion' sentence is ambiguous about whether Notion writing happens here or elsewhere.

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

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

The core points are front-loaded in the first three sentences, but '本工具不调用模型' and the idea that the Agent writes the lecture are repeated. The 'MCP 负责...' sentence is confusing and largely out of scope for this specific tool, and the failure-condition list adds bulk without direct invocation 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?

For a single-parameter tool with no output schema or annotations, the description covers the essential contract: what is returned (skeleton and excerpts), what is not done (no model call, no Notion write), and the next pipeline step. It leaves the exact skeleton/excerpt format unspecified, but that is acceptable given the simple 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?

There is only one required parameter, deckPath, and schema description coverage is 100% with the schema itself saying it is a local .pdf or .pptx path. The tool description adds no format, validation, or alternative meaning beyond the schema, so the baseline of 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 first two sentences state the specific function: it returns only a structural skeleton and deck excerpts so the Agent can write the lecture, and it explicitly says this is not a finished product, does not call a model, and does not write to Notion. It names run_lecture_pipeline as the next step, distinguishing it from that sibling. The later sentence 'MCP 负责...内容审、写入 Notion...' muddies whether this specific tool also does content review or Notion writes, but the core purpose is still 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?

It tells the Agent to hand the draft to run_lecture_pipeline after writing and frames this tool as the drafting step rather than the final output. The failure-condition list gives quality constraints for the draft. It does not explicitly compare with ingest_deck or audit tools, but the workflow context is clear and there are no misleading exclusions.

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?

With no annotations present, the description carries the burden. It discloses the substance of the return value (rules, rationale, impossible-to-automate cases) and that it works standalone without Notion, which implies it is a static reference rather than a live query. It does not state whether the content is fixed or versioned, its format, or its size, which for a large spec document an agent might want to know.

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

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

Two short sentences, front-loaded with what is returned and followed by the standalone-usage note. Every clause contributes, though the Notion remark is slightly oblique without further context.

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

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

For a zero-parameter, zero-annotation tool with no output schema, the description needs to characterize the payload itself, and it does: a full layout rulebook with rationale and feasibility notes. An agent knows enough to call it and roughly what it will get back; only the output form (markdown, structured data) remains unspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No misleading parameter claims are made.

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 concrete verb and resource – it returns the complete typography/layout specification – and enumerates its content (which changes are worth making, which APIs can't achieve, why each rule exists). It is clear about what the tool produces but does not explicitly distinguish itself from adjacent siblings such as scan_layout_rules or audit_structure.

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?

One usage condition is given: the spec can be followed on its own when Notion isn't connected. That is a real context cue, but there is no guidance on when to call this versus scan_layout_rules or audit_structure, so the agent must infer that this is the reference-reading counterpart to those scanning tools.

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?

With no annotations, the description carries the full burden and does well: it explicitly disclaims side effects (no author assignment, no notifications) and discloses the downstream gating effect on apply_plan. Gaps remain on whether existing states can be overwritten or whether transitions are validated (e.g. beautifying back to content_pass).

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

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

Four short sentences, each carrying distinct information: state vocabulary, side-effect boundary, the apply_plan dependency, and the get/set split. No restatement of the tool name and 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 4-parameter mutation tool with no annotations and no output schema, the description covers states, side effects, and the critical downstream dependency. It omits what action=get returns (the stored state and note) and any state-transition rules, which an agent would want before calling set.

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

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

Schema coverage is 75%, and the description adds real meaning beyond the bare enum by glossing each state value (content_pass/beautifying/rereview_pass) and by explaining that action=get is query-only. The undocumented parameter is pageId, whose meaning is left to inference, and note is only described in 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?

Uses a specific verb (记录/record) plus the resource (审阅状态) and enumerates the exact three allowed states with glosses, so the agent knows precisely what is stored. It also distinguishes itself from apply_plan by stating it only stores state and does not perform the actual write. It stops short of relating itself to the adjacent audit_* siblings, so not 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?

Gives a concrete precondition chain: without content_pass, apply_plan's real write is rejected, which tells the agent when this tool must be called first. It also clarifies the action=get branch as read-only. It does not say when NOT to use it or which state to pick in ambiguous situations (e.g. re-review after edits).

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?

No annotations are provided, so the description carries the full burden. It does disclose the read-only nature and the shape of what comes back per page, plus a clear statement of what it does not do. It says nothing about error behavior for a missing/invalid path, page-count or file-size limits, or where the returned content goes.

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 clauses, front-loaded with pipeline position followed by inputs, outputs, and exclusions. Nothing is wasted or repeated.

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 specifies the per-page return fields, which is exactly the gap it must fill. Minor shortfall: no mention of failure modes for unreadable or unsupported files.

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?

Single parameter with 100% schema coverage already documented as a local .pdf or .pptx path. The description only restates the accepted formats, adding no path conventions or handling notes beyond the schema, 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?

Names a specific action (读取 pdf/pptx) and the exact per-page payload returned (title, body text, image presence). The negative framing ('不写讲解，也不写 Notion') separates it from draft_lecture and any Notion-writing sibling without needing 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?

'流水线第一步' tells the agent this is the entry point of the pipeline, and the two exclusions rule out using it for lecture drafting or Notion output. It stops short of naming the follow-up tool (draft_lecture) or stating preconditions such as the file existing locally.

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?

No annotations are provided, so the description carries the burden; it discloses the return contents (themes, content-type fit, palettes, callout semantics) and implies a read-only listing with no side effects. It does not explicitly state that nothing is mutated or how large the list is, keeping it below 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 short sentences, zero waste, with the action and the recommended call order front-loaded. Every clause earns its place.

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

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

With no output schema, the description must convey return values, and it does by naming the four kinds of information returned. It stops short of describing the shape of each entry, but is sufficient for an agent to decide 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies no input is needed.

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 (排版主题) and enumerates what each entry contains: suitable content types, color palettes, callout semantics. It does not distinguish itself from the sibling get_design_spec, which plausibly overlaps, 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?

Gives explicit sequencing guidance: look at this before modifying pages, pick a theme, then audit. That is clear when-to-use context, but it names no alternative tool or exclusion condition (e.g., when to prefer get_design_spec).

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?

With no annotations, the description carries the full behavioral burden and discloses key traits: it does not write back to Notion, the images are approximate layout/color renders rather than pixel-level screenshots, and the tool does not call a model. It leaves some operational details unstated, such as how the preview result is handed to apply_plan, but the main side-effect and output limitations are covered.

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

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

The core purpose and apply decision are front-loaded, but the description then expands into broader MCP pipeline responsibilities and repeated Fail rules that are not specific to invoking preview_page. These sentences add workflow context but dilute conciseness.

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 usefully explains that the return includes before/after comparison images and estimated score changes. It also covers the key no-write and approximate-render behavior, though it does not specify how the preview output is passed to apply_plan.

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 all four parameters including pageId, themeId, allowRecreate, and includeDestructive. The description does not add parameter-level meaning beyond that, so the baseline of 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?

The description states a specific verb and resource: it generates a beautification plan and returns before/after comparison images plus estimated score changes. It explicitly distinguishes itself from apply_plan by saying it does not write back to Notion and that the caller should decide whether to apply after viewing the preview.

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 usage timing: view the comparison first, then decide whether to run apply. It also states when not to use it, namely before content has passed review, reinforced by '内容未过关就美化 = Fail' and '只有 gate.pass 为 true 才 bloom'.

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?

With no annotations, the description carries the burden and does disclose the auth requirement (no Notion token) and what is produced (a plan and a comparison image). However, it does not say whether any files/artifacts are written, whether output persists, or how the plan relates to apply_plan, leaving the mutation/side-effect profile unclear.

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 zero waste: the capability and token-free constraint come first, then the parameter values and default. Slightly better structuring would separate the parameter details more cleanly, but 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?

No output schema and no annotations, so the description is the only source; it covers the output conceptually (plan + comparison image) and the no-arg behavior. It does not cover the themeId parameter at all, nor the lifecycle of the generated preview relative to apply_plan/rollback siblings.

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

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

Schema coverage is 100%, so the schema already carries parameter meaning. But the description enumerates sampleId values as payment-spec/reading-notes/weekly-report while the schema requires the sample- prefixed forms (sample-payment-spec, etc.) — a literal conflict that could cause the agent to pass an invalid value. The useful addition is the omitted-parameter default (returns sample list), but the mismatch is actively harmful.

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

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

The description names a specific action (出计划和对比图) and resource (内置的样例页面), and adds a differentiating constraint (不需要 Notion token) that separates it from sibling preview_page/render_page without needing to inspect schemas. It doesn't explicitly name the real-page alternative, 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?

Usage is only implied: the tool is for sample pages and needs no Notion token, and omitting sampleId returns the sample list. There is no explicit statement such as 'use preview_page for real Notion pages' or any prerequisite/exclusion, so the agent must infer when to prefer this over the other preview/render siblings.

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?

With no annotations at all, the description carries the full behavioral burden; it does deliver the key one by promising "不做任何修改" (a non-mutating read). It stops there, saying nothing about the image format, whether the full page or only the viewport is captured, or how the image is returned to the caller.

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 is the action and the non-mutating guarantee, the second is the usage. Nothing is padded or repeated.

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 one-parameter tool with no annotations and no output schema, the description should say what actually comes back (image as URL? inline data? attachment?). It states only that a rendered image is returned, leaving the return channel unspecified where there is no output schema to fall back on.

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 pageId is documented nowhere; the description only implies it through "读取页面". The single required parameter has an obvious meaning, which keeps this at minimum viable, but no ID format or scoping semantics are added.

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 concrete verb and resource ("读取页面并返回当前样子的渲染图") and states the output form (a rendered image) rather than just restating the name. It is clear on its own, but it never distinguishes itself from nearby siblings like preview_page or preview_sample, so an agent cannot tell from the text which of these to pick.

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

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

It gives two concrete situations to use it in: reviewing after edits ("修改后复查") and taking a look before an audit ("审计前先看一眼"). That is real situational guidance, but it never rules anything out or names the alternative it replaces, so the boundary with audit_page/preview_page stays implicit.

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?

With no annotations, the description carries the full burden and discloses key destructive effects: current top-level blocks are deleted, all block IDs change, and comments are not restored. It also states the confirm requirement, though it does not mention permissions or whether the rollback itself can be undone.

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, with the destructive effects and confirm requirement front-loaded. Every sentence adds operational value and there is no redundant 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 destructive rollback tool with no annotations and no output schema, the description covers the essential source, side effects, and confirmation requirement. It could be more complete by mentioning permissions or return behavior, but the core context an agent needs is present.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description reinforces the snapshot source and confirm requirement but adds no syntax or format details beyond what the schema already provides, making 3 the appropriate baseline.

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: rebuild the page using a snapshot returned by apply_plan. It clearly distinguishes rollback from apply_plan by tying the snapshot source to apply_plan, so an agent can tell what this tool does 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?

It gives clear usage context: the snapshot must come from apply_plan, and confirm: true is mandatory. It does not explicitly state when not to use it or name alternative rollback/preview tools, so it falls short of explicit when/when-not 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?

With no annotations, the description carries the full burden and does well: it discloses that nothing is written by default, that failed audits do not get beautified, that apply rolls back on broken formulas, and that no model is invoked. Missing are details on permissions, rate limits, and what the audit failure reason looks like, but the write/rollback semantics are unusually clear for an unannotated mutation path.

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

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

Front-loaded with the skeleton return and the draft-input rule, then escalates through review and apply gating in the order an agent would use them. Dense but every clause carries a rule; it is slightly run-on with several short declarative fragments that could be grouped more tightly.

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

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

For a 7-parameter, multi-branch tool with no output schema, the description documents the control flow thoroughly but says nothing about return values — what the skeleton contains or what an audit result looks like — leaving the agent unable to plan around the response. The flow is adequately covered; the response shape is not, which is the remaining material 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 100%, so baseline is 3, but the description adds cross-parameter meaning the schema cannot: it ties review=true to the parentPageId write target and ties apply=true to a prerequisite content-audit pass. That interaction is the part most likely to be misused and is spelled out explicitly. Only themeId and title get no discussion in the description, which is acceptable since the schema covers them.

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 opening line states a concrete verb and resource (read the deck and return a structural skeleton), then clarifies the tool's actual job: assembling a lecture draft through audit gating and optional write. It does not name sibling tools like draft_lecture or ingest_deck, so the agent cannot distinguish it by name alone, but the multi-mode pipeline behavior is unmistakable.

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 explicit mode-selection rules: omit draft for skeleton only, pass draft to run content audit, set review to write the pending draft, set apply to beautify only after passing. That is precise when/when-not guidance for the tool's own branches. The gap is that it never contrasts itself with sibling tools such as draft_lecture or preview_page, so the agent must infer which pipeline entry point to use.

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?

With no annotations, the description carries the full burden, and it does disclose the key safety trait explicitly ("只读" and "不改页面" — read-only, does not modify the page). However it says nothing about what the scan returns (per-rule pass/fail, violation list, severity), whether it is expensive, or whether it needs the page to be rendered first.

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 with the rules front-loaded and the read-only guarantee appended last, so nothing is wasted. It is slightly run-on as a colon-separated list, but every clause carries a distinct rule.

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 one-parameter read-only check with no output schema, the definition covers what is inspected and that nothing is mutated, which is the core need. It is still incomplete about the shape of the result (a report of violations? a boolean?) and about its relationship to the adjacent audit_* tools, which matters given how many siblings overlap.

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, pageId, and schema description coverage is 100% ("页面 id 或页面 URL"), so the schema already does the work. The description adds no format detail, no note on whether a URL triggers a fetch, and no scope caveat. Baseline 3 applies when the schema fully documents the single parameter.

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 (read-only scan) and resource (layout/typography rules), and enumerates the concrete rules being checked (table usage, forbidden long notice boxes, heading hierarchy, cover and icons, body density). It is clearly distinguishable in intent from mutation tools like apply_plan, but it never names its closest siblings (audit_page, audit_structure), so an agent must still infer the boundary.

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: a pre-flight style check is suggested by the enumerated rules, but there is no statement of when to call this versus audit_page or audit_structure, nor whether it should run before apply_plan or after diff_after_beautify. No prerequisites, no exclusions, no alternatives.

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?

No annotations are provided, so the description carries the full burden. It does disclose the return payload (page id and link) and the access-scoping behavior, which is valuable, but it omits result limits, pagination, and ranking/ordering behavior — meaningful gaps for a search tool with zero annotation coverage.

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 no filler; the search action and access constraint are front-loaded and the return value is appended efficiently.

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 one-parameter read tool with no output schema, describing both the scope and the return shape covers most of what an agent needs. The missing pieces — pagination, result count, and the title-vs-body inconsistency — are minor but real.

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 one parameter and 100% schema coverage, the baseline is 3. The description adds nothing beyond the schema and in fact narrows the scope to 'title keyword' while the schema says '标题或正文关键词' (title or body keyword), leaving a small ambiguity about whether body text is matched.

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 pages) plus the access scope (当前 integration 能访问的页面) and the return shape (page id 和链接). No sibling in the list does page search, so differentiation isn't strictly needed, but the description never names an alternative read/query tool, keeping it just short of a 5.

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

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

The scope clause 'current integration can access' implies when the tool will find results and warns that pages outside the integration won't appear. However, there is no explicit when-to-use/when-not guidance, no mention of alternatives, and no note on whether this searches only titles or also body text.

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