审计一个页面

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.