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

No annotations are provided, so the description carries the full behavioral burden. It does not state whether tags are appended or replace existing tags, how duplicates are handled, what permissions are required, or what happens if the note is not found.

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

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

The description is a single front-loaded sentence with no unnecessary words. It is appropriately brief for a simple two-parameter mutation, though it leaves important behavioral context unaddressed.

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?

The tool is simple and the input schema is fully documented, so an agent has enough to invoke it. However, with no annotations and no output schema, the description should do more to explain mutation behavior such as append semantics and tag duplication 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 100%, so the schema already explains both note_id and tags. The description adds no additional parameter meaning or format details beyond what the schema provides, which is the baseline expectation when schema coverage is 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?

The description states a specific verb and resource: adding tags to a specified note. It is clear what the tool does, but it does not differentiate itself from the sibling delete_note_tag or explain how it relates to broader note-update 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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The only implied usage comes from the tool name and the one-sentence purpose.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one real trait, the 20-notes-per-batch cap, but says nothing about what happens when a note already belongs to the topic, partial-failure behavior when some IDs are invalid, permission requirements, or reversibility of the addition.

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

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

A single front-loaded sentence with the resource and the key constraint, zero filler. It is efficient, though its brevity leaves the gaps noted in other dimensions rather than being 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?

This is a mutation tool with no annotations, no output schema, and three parameters. The description covers purpose and the size cap but leaves the agent without error/partial-success semantics or permission expectations, which is not enough context for a bulk write operation.

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 topic_id, note_ids and directory_id are already documented in the schema. The description only restates the 20-item limit already present in the note_ids field description and adds no semantics about ordering, duplicates, or directory_id interaction. 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?

Placeholder — see above.

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 批量 (batch) implies bulk use and the 20-item cap implies you should chunk larger sets, but there is no explicit when-to-use/when-not guidance, no mention of prerequisites (e.g., topic ownership or membership), and no named alternative for single-note adds.

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 provided, the description carries the full disclosure burden. It valuably specifies the rate limit (50/day) and reset time (00:00 Beijing time), but omits mutation behavior details like idempotency, error handling when limits are exceeded, or whether creation is synchronous.

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 consists of two efficient sentences: the first establishes purpose, the second provides the critical constraint. Zero wasted words; information is front-loaded.

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 creation tool with 3 simple parameters and no output schema, the description covers the essential constraint (rate limiting) but leaves gaps regarding return values, success confirmation, or error scenarios.

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%, establishing a baseline of 3. The description text adds no parameter-specific guidance beyond what the schema already provides (name, description, cover).

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 '创建新的知识库' (Create new knowledge base), providing a specific verb and resource. It implicitly clarifies that 'topic' in the tool name maps to 'knowledge base' in the domain model, distinguishing it from note-centric siblings like save_note or list_notes.

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 provides a rate limit warning but offers no guidance on when to use this tool versus alternatives like list_topics (to check for existing topics before creating), nor prerequisites such as uniqueness constraints.

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 for a mutating tool, yet it says nothing about required permissions, whether folder names must be unique within a topic, whether duplicates are rejected, or what is returned on success. Only the basic mutation is communicated.

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

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

A single front-loaded sentence with no wasted words. Its brevity is appropriate, though it is thin rather than maximally efficient given what it omits.

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 three-parameter creation tool with complete schema descriptions and no output schema, the description is minimally sufficient. But as an unannotated write operation, an agent gets no signal about permissions, naming constraints, or post-creation behavior.

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 all three parameters including parent_id's 'omit means root' semantics are already documented in the schema. The description adds no meaning beyond it, 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 states a specific verb and resource ('创建文件夹' in 知识库) and the tool name contrasts cleanly with siblings like update_topic_directory, delete_topic_directory and list_topic_directories. It does not explicitly say what distinguishes it from those siblings, but the verb makes the intent 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?

There is no statement of when to use this versus update_topic_directory or when nesting under a parent vs root. The reader infers the create-vs-update split purely from the name, which is implied usage rather than stated 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 at all, the description carries the full burden; it does disclose the two most important behavioral facts — deletion is a move to trash rather than a permanent erase, and an auth scope is required. It does not say whether the operation is reversible or how to restore, whether it is idempotent, or what happens to attachments/tags, so it is helpful but incomplete for a destructive tool.

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

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

Two short sentences, zero filler, with the core action and its soft-delete nature front-loaded before the permission note. Nothing repeats the schema or the title.

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 output schema, the description covers purpose, soft-delete semantics, and the required scope, which is enough to call it correctly. The only real gap is the absence of any restore/recovery hint or error-behavior note, which matters because no annotations supply a safety profile.

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

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

There is a single parameter and schema description coverage is 100%, with the schema already specifying the tricky ID format (decimal string preferred, JS safe integer only). The description adds nothing about note_id, so the baseline 3 applies.

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

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

States a specific verb and resource (删除笔记) and immediately clarifies the operation is a soft delete into the trash (移入回收站). This makes it clearly distinguishable from siblings such as get_note, update_note, and delete_note_tag, which an agent could otherwise confuse with note removal.

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 names the prerequisite permission (note.content.trash scope), which is genuinely useful context for deciding whether a call will succeed. However, it gives no explicit when-to-use guidance or alternatives (e.g., restore path, or removing a note from a topic instead of deleting it), leaving intent to be inferred from the tool name.

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

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

With no annotations, the description carries the full burden. It does disclose one important behavioral constraint — system tags cannot be deleted — which is genuinely beyond the schema, but says nothing about required permissions, idempotency, or what happens when the tag is not attached to the note.

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

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

One short sentence with the operation front-loaded and the restriction immediately after in parentheses. No filler, no repetition of the 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 two-parameter mutation tool with a fully documented schema and no output schema, the essentials are covered. However, with zero annotations the description should say more about failure modes (tag absent, permission denied) to be fully 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 100%, so both parameters (note_id, tag_id, including accepted types and provenance of tag_id) are already fully documented. The description adds no format or sourcing detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific verb and resource combination ('删除笔记的指定标签') and adds a scope constraint that system tags cannot be removed. It is clear on its own, though it does not explicitly position itself against the inverse sibling add_note_tags.

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

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

Use is implied by the operation (removing a tag already on a note), and the parenthetical gives one precondition (system tags are undeletable). There is no explicit when-not guidance or reference to alternatives such as add_note_tags for the reverse action.

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 two most important traits: the operation is destructive and requires user confirmation beforehand. It omits permission requirements, error behavior when the folder is not empty, and whether the deletion is reversible.

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 destructive qualifier and confirmation requirement 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?

The behavioral side is adequately covered for a simple two-parameter destructive tool, but the total absence of parameter documentation and of any output/error expectations leaves a real gap given no annotations and no output schema.

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

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

Schema description coverage is 0%, so the description must compensate, and it does not: neither topic_id nor directory_id is explained (e.g., where to obtain the directory_id, whether it is scoped to topic_id).

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 (delete a knowledge-base folder) plus a key qualifier that the folder must be empty. It doesn't explicitly contrast with create_topic_directory or update_topic_directory, but the verb makes the distinction obvious.

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 'empty folder' precondition and the mandatory user-confirmation step give real guidance on when to call. No alternative (e.g., update_topic_directory for non-empty folders, or listing first via list_topic_directories) is named, so the agent must infer the fallback path.

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?

There are no annotations, so the description carries the full disclosure burden. It does reveal one meaningful side effect — the blogger's content becomes readable afterward — but says nothing about idempotency on duplicate follows, what a failed link resolution looks like, permission requirements, or what is returned on success.

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 action and destination front-loaded and no filler. It is efficient, though brevity contributes to the missing behavioral detail rather than compensating for it.

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-style subscribe tool with no annotations and no output schema, the description omits duplicate-handling, error behavior, and the fact that a subsequent read step (list_topic_blogger_contents) is needed to actually retrieve content. An agent would have to guess at edge-case 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 coverage is 67% and the schema already documents both required parameters (link as profile/share URL, topic_id as knowledge base ID). The description's phrase 指定知识库 only echoes topic_id, and the platform parameter is left entirely undefined in both places — acceptable only because it is a single-value enum with a default.

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 (订阅/follow), a specific resource (抖音博主), and a destination (指定知识库), and adds the downstream consequence that its content becomes readable. It is clearly distinguishable from list_topic_bloggers and get_blogger_content_detail, though it does not explicitly contrast with the near-identical follow_topic_live sibling.

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 workflow (subscribe now, read the blogger's content later) but never states when to use this versus follow_topic_live, or what to do if the blogger is already subscribed. No preconditions, no exclusions, and no named alternatives 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?

No annotations, so the description carries the full burden — and it does real work: it discloses the asynchronous timing (results appear only after the live ends and is AI-processed), the required topic.live.write scope, and the current input platform limitation. It omits idempotency and behavior when the live is already subscribed or already processing.

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 — action, downstream visibility, input limitation, required scope — with the core action front-loaded. 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?

For a 2-parameter write tool with no annotations and no output schema, the description covers the essential agent needs: what it does, when results are observable, the platform restriction, and the auth scope. Only failure/duplicate handling is left 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?

Schema coverage is 100%, so both link and topic_id are already documented in the schema. The description only reinforces the link constraint (仅支持得到 App 直播链接) without adding format or ID-resolution guidance, so the baseline 3 applies.

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

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

States a specific verb and resource: subscribing a Dedao App live stream into a knowledge base (订阅...直播到知识库), and names the sibling list_topic_lives as the read counterpart. It cleanly separates subscribe (write) from view (read), though it does not say how it differs from the adjacent follow_topic_blogger 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 clear context for when the effect becomes visible (直播结束后经 AI 处理 — after the live ends and AI processing completes, use list_topic_lives), and states the input constraint that only Dedao App live links are accepted. It does not spell out explicit exclusions or what happens on duplicate subscriptions.

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 usefully discloses the required auth scope (topic.blogger.read) and implies a read-only fetch, but says nothing about error behavior, permissions failures, or side effects for an undocumented call.

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

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

Two compact sentences, front-loaded with the payload value and followed by the access prerequisite. 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?

For a two-param, no-output-schema read tool, this is close to sufficient: parameters are fully documented and the key return field (post_media_text) is named. It stops short of describing the rest of the returned detail object.

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

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

Schema coverage is 100% and both parameters already document their provenance (post_id_alias from list_topic_blogger_contents, topic_id from list_topics). The description adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('获取博主内容详情') plus the distinguishing payload ('完整原文 (post_media_text)'). It clearly contrasts in spirit with list-style siblings like list_topic_blogger_contents, but it never names that sibling explicitly, so an agent must infer the split.

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

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

Usage is only implied: the mention of '完整原文' signals this is for when you need the full body rather than a list summary. There is no explicit when-to-use, when-not-to-use, or named alternative such as list_topic_blogger_contents.

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 load. It does add one genuine behavioral trait — that results are dynamically derived from config, not a cached fixed list ('不缓存为固定格式列表') — which is useful. But it says nothing about permissions, whether the call is read-only in practice, failure modes, or the shape of the response.

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 that front-loads the use condition and then enumerates exactly what is returned. It is appropriately terse for a zero-parameter query tool, though the non-caching clause is slightly oblique in phrasing.

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

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

There is no output schema and no annotations, so the description must carry the return-value contract. It partly does by listing the five categories of data returned, which is helpful. It still does not indicate the concrete response structure or what an agent should do when the returned limits are exceeded or absent, leaving a modest 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no inputs are needed, matching the empty schema.

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

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

The description names a specific verb (query) and a precise resource (allowed extensions, MIME types, size, page count, and daily limits under the current configuration) and the 'before upload' qualifier makes the intent clear. However, it does not explicitly distinguish itself from likely-overlapping siblings such as get_upload_config or get_quota.

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 'before upload' (上传前) gives an explicit usage moment, which is a real signal. But it names no alternative tool, no when-not-to-use condition, and no prerequisite ordering relative to get_knowledge_file_upload_token or upload_knowledge_file.

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 important traits: the call is read-only ('仅查询'), returns sensitive credentials that must never be surfaced in chat/logs/command args, and pending/processing status does not mean completion. It stops short of describing what the response contains or how failures surface beyond the schema's note about explicit failure.

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 with no filler, and the purpose plus the 'only the original operation' constraint are front-loaded. The remaining sentences are terse operational warnings, each carrying a distinct constraint, though the dense phrasing makes some rules 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 single-parameter tool with no annotations and no output schema, the description covers the essentials an agent needs: read-only intent, credential sensitivity, status semantics, and the resume-only constraint. Return-shape details are the main omission, but the schema partially compensates on the parameter side.

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

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

Schema coverage is 100% and the schema description already states that operation_id must be reused on resume and only works when server negotiation supports it. The description largely repeats that constraint rather than adding new meaning, so the baseline 3 is appropriate.

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

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

The opening line '仅查询原知识库文件上传凭据操作' gives a specific verb (query) and resource (original knowledge-file upload credential operation), and the word '原' plus '仅' scopes it to resume-style lookups rather than new uploads. It distinguishes itself implicitly from siblings like get_upload_operation and get_knowledge_file_upload_token, though it never names them, which keeps it 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?

Clear when-to-use guidance: resume by querying the original operation_id, keep the same client_request_id and uploaded object, and do not re-upload when rate-limited on save. It also states a when-not condition (cannot auto-request a new key). The only gap is that it doesn't explicitly point to the sibling tool to call when a new key is legitimately needed.

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 does substantial work: it flags credentials as sensitive, forbids putting them in chat/logs/command arguments, and prescribes passing them via a controlled file or stdin. It also discloses that pending/processing is not completion and that recovery is constrained to the original operation_id. Missing are token lifetime/expiry and whether minting a credential consumes quota, which are exactly the facts an agent operating under rate limits 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?

The structure is inverted: the core purpose sentence sits in the middle of the paragraph, behind recovery, rate-limit, and credential rules, and the credential-handling warning is repeated almost verbatim twice ('不得放进聊天、日志或命令参数' and '不写命令参数或聊天'). The first sentence about retaining uploaded objects and client_request_id assumes context the reader does not yet have.

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, yet the description never says what the returned credential looks like, how long it is valid, or what the response contains on a rate-limit or unsupported-operation failure, even though it describes those failure modes. It is strong on operational safety and recovery semantics, moderate on completeness for a credential-minting tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces operation_id semantics ('恢复仅查询原 operation_id') and ties the size cap back to a capability limit, but it adds no new meaning for mime_type beyond what the schema already states, and the CLI flags it mentions (--token-file, --max-size-bytes) are not the tool's own parameters, which could confuse the mapping.

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 contains a specific verb+resource statement: '获取一次 OSS 文件上传临时凭据' (get a temporary OSS file upload credential), and the CLI invocation plus the note that no re-login is needed distinguishes it from sibling credential tools like get_upload_token. The drawback is placement: the actual purpose appears only in the fifth sentence, after four sentences of preconditions, so an agent skimming the first line gets workflow constraints rather than what the tool does.

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 concrete when/when-not guidance: do not re-upload when rate-limited, keep the original client_request_id, and for recovery reuse the original operation_id only (explicitly no new key may be auto-requested). It also excludes a wrong path ('不要把文件字节传给云 MCP'). It never names a sibling tool by name as the alternative, which keeps it out of the top band.

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 two key return components (post_summary, post_media_text) and the required topic.live.read scope, which is real added value. It says nothing about response size, whether a transcript can be truncated or missing, or what happens when the scope is absent — meaningful gaps for a read that can return full transcripts.

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

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

Two short, front-loaded sentences with no filler: the first scopes the content, the second states the auth prerequisite. Nothing is wasted, though the second sentence could be merged or placed after the content description for slightly better flow.

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 two-parameter read with no output schema, the description adequately covers what comes back (summary + transcript) and the permission needed. The remaining gap is minor: no note on transcript availability or size, which matters for a tool returning full text.

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

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

Schema coverage is 100% and both parameter descriptions already state provenance and expected type, so the schema does the heavy lifting and the baseline of 3 applies. The description adds no parameter-level meaning — the field names it mentions (post_summary, post_media_text) are return values, not inputs.

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 ('获取直播详情') and enumerates the payload (AI summary + full transcript), so an agent knows exactly what it retrieves. It does not explicitly distinguish itself from the sibling list_topic_lives, leaving that separation 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 only implied: 'detail' versus the sibling 'list' suggests this is the second-step fetch after enumerating lives. There is no explicit when-to-use, no exclusions, and no stated precondition such as needing a live_id obtained from list_topic_lives (that hint lives only in the schema).

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

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

No annotations exist, so the description carries the full burden. It usefully discloses the shape of the returned data — notably that content is an AI summary and where the raw text lives per note_type — which is real behavioral context. It says nothing about read-only guarantees (only implied by 'get'), authentication/permissions, behavior for a missing or inaccessible id, or whether attachments/transcripts are always present, so the burden is only partly met.

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 purpose sentence is front-loaded and the per-note-type field mapping is dense, high-value reference material rather than filler. It is somewhat long with markdown formatting, but nearly every line changes how an agent would interpret the response.

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 compensates by explaining the key ambiguity in the return value (content vs. original text per note_type). That is the main trap for this tool. Remaining gaps — error behavior, presence guarantees for attachments/transcripts, and routing to the more specialized siblings — are modest 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?

Schema description coverage is 100%, so the id and image_quality parameters are already fully documented in the schema, including the decimal-string preference and the 'original' enum value. The description adds nothing about parameters, which is acceptable given the schema does the work, so the baseline 3 applies.

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

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

States a specific verb and resource (获取指定笔记的详细内容) and enumerates what is included: body, tags, attachments, audio transcript, web links. It is clear about what it returns, but it never distinguishes itself from the very similar siblings get_note_original, get_note_transcript, and get_note_attachments, all of which appear to return overlapping subsets of the same data.

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 field-semantics block gives a conditional rule for the 'read original text' case (check note_type, then select the matching field), which is genuinely useful. However, it gives no guidance on when to call this tool instead of get_note_original / get_note_transcript / get_note_attachments, nor any exclusions or prerequisites, so tool-level selection 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?

No annotations are provided, so the description carries the full behavioral burden. It indicates a direct read/list operation, but does not describe permissions, empty-result behavior, pagination, or response shape beyond the attachment categories.

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

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

The description is a single, front-loaded sentence that states the action and value proposition with no wasted wording.

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 one-parameter read/list tool, the description covers what is returned at a high level (images, audio, file attachments) and why to use it over full details. It could be slightly more complete about response structure, but no output schema exists and the core need is sufficiently 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?

There is only one parameter, and the schema description coverage is 100%, with the schema explaining the note ID as a decimal string. The description adds no additional parameter semantics beyond what the schema already provides, so 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 description uses a specific verb (列出) and names the exact resource types: images, audio, and file attachments within a note. It also distinguishes itself from the full-detail tool by saying the caller does not need to guess fields from complete details.

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 “不需要从完整详情中猜字段” clearly signals when to use this tool instead of fetching full note details, but it does not explicitly name get_note as the alternative or state 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, the description carries the full burden. '读取' implies a read-only operation, and it adds useful behavioral detail that start_ms is in milliseconds and source must be preserved, but it does not disclose permissions, empty/error behavior, pagination, or return structure.

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

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

The description is two compact clauses with no wasted words. The core resource is front-loaded, followed by the timing/format detail and the sibling distinction.

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 read tool with one fully documented parameter, the description supplies the key output semantics—chapter_timeline, millisecond start_ms, and source preservation—along with sibling separation. It still omits some return-shape and edge-case detail, which matters more because there is no output 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 parameter, id, and the schema already documents it at 100% coverage as '笔记 ID'. The description adds no additional meaning about the id parameter beyond what the schema provides, 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: reads the independent chapter timeline (chapter_timeline) from a note summary. It also explicitly distinguishes this from recording moments and marks, so an agent can tell it apart from sibling tools such as get_note_marks and get_note_timeline.

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 clearly says to read chapters separately from recording moments and marks and that they cannot substitute for one another, which provides explicit exclusion guidance. It does not name the exact sibling tools or state a positive use case beyond 'read chapters', so it falls short of the most explicit routing guidance.

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

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

With no annotations, the description carries the burden; 读取 implies a read-only operation and the mark contents hint at the return payload. But there is no statement about permissions, pagination, ordering, or what happens when a note has no marks — gaps a no-annotation tool should cover.

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

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

One tight sentence that front-loads the purpose and appends the anti-confusion caveat about Timeline. No filler, though the two clauses could be split more cleanly.

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 tool with no output schema, the description covers purpose and sibling differentiation but leaves the caller guessing about the shape of the returned marks and the note_id contract. Adequate but with evident 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%, so the description is the only source of meaning, and it says nothing about note_id (format, where to obtain it, valid range). It only implicitly justifies the parameter by saying marks belong to a note.

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 clarifies what a mark includes (文字标记、照片). It also explicitly distinguishes itself from the sibling get_note_timeline, so an agent can tell which one to pick without opening a schema.

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

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

Explicitly says this is independent of Timeline and that the timeline is not a substitute — a clear when/when-not signal against a specific sibling. It does not, however, address other adjacent readers such as get_note_attachments or get_note_original.

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 provided, the description carries the full burden and does disclose the key behavioral trait: the return type varies by note kind, and certain inputs raise errors rather than returning empty. '直接读取' also signals a raw passthrough read rather than a structured/metadata fetch. It does not state permission requirements or whether the call has any side effects, which keeps 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?

A single front-loaded sentence with the action first and a compact semicolon-delimited mapping of note type to return value. Every clause carries information; nothing is repeated from the schema or 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?

There is no output schema, so the description must explain return values, and it does so by note type — including the error case. For a one-parameter read tool this is close to sufficient; the main omission is whether large originals are truncated or size-limited.

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

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

Only one parameter, and the schema already documents it at 100% coverage ('笔记 ID，推荐十进制字符串'). The description adds nothing about the id — no note on ID reuse across note types or cross-account scope. Baseline 3 applies when the schema does the work.

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

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

A specific verb and resource — '直接读取笔记原文' — followed by an enumeration of what is returned for each note type (引用/链接/录音/文字). This lets an agent predict the payload shape without opening anything else. It stops short of distinguishing itself from the sibling get_note or get_note_transcript, which overlap on the audio-transcript case.

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 a real usage condition by naming the failure modes: notes with no original content or unsupported types will error. That tells an agent when not to call it. It never names an alternative tool (e.g., get_note_transcript for audio, get_note for structured fields), so the selection among siblings is still left partly 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?

No annotations are provided, so the description carries the full disclosure burden. It does add real value by disclosing the no-quick-note case ('明确返回不可用'), telling the agent not to treat an absent quick note as a failure. However, it says nothing about what a quick note contains, whether it is derived/synthesized, or the shape of the 'unavailable' response.

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 plus one semicolon clause covering the failure case; no filler, no repetition of the tool name. Every clause contributes information.

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

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

With no annotations and no output schema, the description must explain both side effects and return behavior. It covers the empty case but leaves the agent guessing about the normal return shape (text? structured object? timestamps?) and about whether this is a pure read with no side effects.

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%: the single `id` parameter is already documented as a note ID with a recommended decimal-string format. The description adds nothing about the ID beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (读取/read) and a specific sub-resource (录音笔记的快捷笔记, the quick note of a recording note), which meaningfully separates it from generic siblings like get_note, get_note_transcript, or get_note_original. It does not explicitly name or route against those siblings, 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 by the tool name and the 'quick note' sub-resource; the description never says when to prefer this over get_note or get_note_original, nor does it state prerequisites. The one useful signal is that the caller should expect an explicit 'unavailable' result rather than an error when no quick note exists.

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 delivers: per-item status states (ok/unavailable/failed/deferred_budget), content_state, pending_ids, partial, an explicit warning that a successful call does not mean every item was read, budget limits (32000 default/64000 max code points + 1MiB), and the required scope note.batch_detail.v1. This is unusually rich behavioral disclosure.

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 core operation and densely packed with useful constraints; every clause carries information. It is somewhat run-on and abbreviation-heavy, but appropriately sized for a tool this behaviorally complex.

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 return semantics (per-item statuses), budget behavior, scope requirement, and the no-auto-concurrency rule even without an output schema or annotations. The residual 20-vs-200 count discrepancy and unexplained meaning of pending_ids/partial keep it from a 5.

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?

At 33% schema coverage the description compensates well: it defines field defaults (content/ref_content/reference), the requirement to explicitly select 'original', the ref_content-vs-content distinction, and max_total_chars default/max with 1MiB nuance. The ids ordering/dedup meaning is added too, though the 20 vs 200 mismatch leaves some ambiguity.

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: batch-reads up to 20 deduplicated personal note IDs while preserving order, which clearly contrasts with the single-item get_note sibling. The '20' cap conflicts with the schema's maxItems=200, slightly muddying precision, but the core purpose 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?

Names the alternative explicitly: '整条超预算按需改用旧get_note' (fall back to get_note when the whole set exceeds budget) and clarifies it does not auto-concurrent 20 calls. Use context is clear; a fuller when-not statement would earn a 5.

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

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

No annotations provided, yet description fully discloses: async lifecycle (status transitions to success/failed), return value structure (note_id on success, error_msg on failure), operational constraints (polling interval 10-30s, ~3min duration), and auth requirements (note.content.read scope).

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

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

Three sentences with zero redundancy: sentence 1 states purpose, sentence 2 covers complete workflow (trigger, input source, polling pattern, output values), sentence 3 provides timing guidance and auth scope. 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?

Despite absent output schema, description compensates by detailing return values (status, note_id, error_msg), terminal conditions, auth scope, and operational timing. Fully sufficient for an async polling 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?

While schema has 100% coverage describing task_id, description adds critical semantic linkage by specifying this ID comes from save_note's return value, establishing the tool-chain relationship that pure schema cannot convey.

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 '查询' (query) + resource '笔记任务的处理进度' (note task processing progress). Clearly distinguishes from sibling get_note (which retrieves actual note content) by explicitly targeting async task polling rather than final note data.

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?

Comprehensive usage context: specifies exact trigger condition (link note creation via save_note), prerequisite parameter source (save_note returned task_id), terminal states (success/failed), sibling relationship (save_note), and exact workflow (poll until status change).

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. It usefully discloses that the tool directly reads timeline/original resources and explicitly returns unavailable when no timeline exists, but it does not describe the return shape, auth requirements, or whether it has any side effects.

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

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

The description is a single compact sentence with the core purpose front-loaded, followed by the key fallback behavior. It is efficient, though '原文资源' is slightly vague and could be more precise.

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

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

For a low-complexity, one-parameter read tool, the description covers the main action and a missing-timeline edge case. However, with no output schema and no annotations, it should ideally clarify return values and distinguish this tool from related note-content 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?

There is only one required parameter, id, and the schema description coverage is 100%. The description adds no parameter-specific meaning beyond the schema, so the baseline score 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 read operation and resource: it directly reads the structured timeline and original text resources of a recording or meeting note. The tool name and description make the core purpose clear, but it does not explicitly distinguish itself from close siblings such as get_note_chapters, get_note_transcript, or get_note_original.

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

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

The only usage-like guidance is the fallback behavior when no timeline exists ('没有时间线时明确返回不可用'). It does not say when an agent should choose this tool over siblings that return chapters, transcripts, or original note content, nor does it list prerequisites.

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

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

With no annotations, the description carries the full burden, and it discloses the return shape (source and items) plus an important behavioral rule: an empty list means no explicit section was identified, and the model must not fabricate entries. It does not explicitly state read-only semantics or error behavior for an invalid id, which keeps 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 tight sentences: the first defines the purpose and data origin, the second defines the return contract and the anti-hallucination rule. Nothing is wasted and the most important constraints are front-loaded.

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 appropriately explains that it returns source and items and what an empty result means. For a single-parameter read tool this is nearly complete; only failure modes (e.g., nonexistent note id) are unaddressed.

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

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

Schema coverage is 100% for the single id parameter, including the recommendation to use a decimal string, so the description adds nothing beyond the schema. Baseline 3 is appropriate when the schema fully documents the only 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 states a specific verb and resource: it reads todo entries that are rule-parsed from the explicit action-item section of a meeting summary. It also scopes the tool narrowly ('明确待办章节' rather than any extracted text), which distinguishes it from sibling note readers such as get_note_chapters or get_note_transcript.

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

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

The description implies usage by specifying that an empty list means no explicit action section was found, but it never says when to call this tool versus alternatives like get_note_chapters or get_note. The guidance it does give concerns interpreting results, not tool selection, so usage context 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?

No annotations are provided, and the description does add real behavioral context: missing transcripts yield an explicit 'unavailable' result instead of synthesized content. However it says nothing about permissions, whether it works for every note type, or rate/response shape, so the disclosure is only partial for a no-annotation tool.

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

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

Two compact clauses, front-loaded with the core action and followed by the source-lookup precondition and the no-transcript rule. No filler or restated title.

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 required id with a fully documented schema and no output schema, the description covers what it returns (transcript raw text) and the failure case (unavailable). It only lacks detail on what the returned transcript looks like (speaker segmentation, pagination) for very long recordings.

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

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

Schema coverage is 100% and the single id parameter is documented in the schema (笔记 ID, 推荐十进制字符串). The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States a specific verb (读取 transcript original text) and a clearly bounded resource set (录音台、录音卡、录音/会议/课堂笔记), and explicitly contrasts it with AI summaries so the agent can distinguish it from get_note_chapters or recall-style 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?

Gives an explicit precondition — locate the device source with list_notes.source first — and an explicit fallback rule: when no transcript exists the tool reports unavailable rather than substituting an AI summary. That is a when-to-use plus a when-not-to-substitute instruction naming the alternative.

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?

Without annotations, the description carries full burden. It successfully discloses the specific quota categories returned (read/write/write_note) and timeframes (daily/monthly), but omits whether this call consumes quota itself, rate limits, or authentication requirements beyond 'current API Key'.

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?

Single information-dense sentence with zero waste. Front-loaded with the action verb, followed by target resource and specific return value breakdown (three categories, daily/monthly).

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 utility tool without output schema, the description adequately specifies what data is returned (quota types and time granularities). Could be improved by mentioning edge cases (e.g., unlimited quotas), but sufficient for tool selection.

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?

Input schema has zero parameters (coverage 100% trivially). With no parameters requiring semantic explanation, this meets the baseline score of 4 as defined in the rules.

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 the specific verb '查询' (query) with resource '调用配额' (call quota), and clearly distinguishes from siblings by specifying it returns quota metadata for the current API Key rather than content (notes/topics) like other 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?

Provides no guidance on when to invoke this tool versus alternatives, no prerequisites (e.g., whether API Key must be configured first), and no warnings about when quota checks might fail.

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 exist, so the description carries the full burden. "已授权用户" hints that access is scoped to the caller's own authorized content, but the description does not state error behavior for invalid ids, whether access can fail on permissions, or any rate/return characteristics beyond the word "原文".

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-loading the action and resource, with the id provenance appended. Nothing is padded and nothing needs pruning.

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, the description minimally suffices: it names the returned payload (original text) and the id source. It still leaves gaps around failure modes and permission behavior that, with zero annotation coverage, only the description could supply.

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% for a single required `id` string, so the description must compensate. It does add provenance (the id comes from list_sprouts), which is genuinely helpful for locating a valid value, but it gives no format, type, or validity constraints for the id itself.

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

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

States a specific verb and resource: read the original text (原文) of a sprout report, as opposed to list_sprouts which enumerates them. The list/get distinction is clear enough to separate it from its nearest sibling, though the description is a single sentence with no explicit contrast statement.

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?

"id 来自 list_sprouts" implies the two-step workflow (enumerate with list_sprouts, then fetch content here), which is useful routing. However there is no explicit statement of when not to use it, prerequisites, or what happens if the id is unknown or unauthorized.

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 provided, the description carries the full disclosure burden. It successfully indicates what contextual information is returned (file types, size limits) and hints at the 'constraints' understanding purpose, but lacks details on caching behavior, authentication requirements, or whether the configuration is user-specific vs global.

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?

Optimal two-sentence structure with zero waste. First sentence establishes the core function and return value categories; second sentence establishes the temporal context (pre-upload). Information is perfectly front-loaded and appropriately sized for the tool's simplicity.

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

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

Given the tool has no parameters, no annotations, and no output schema disclosed, the description adequately covers the essential information: what configuration categories are returned (file types, size limits) and the operational context (pre-upload validation). Minor gap in not describing the data structure of the response, but acceptable for a simple configuration retrieval tool.

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

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

Input schema contains zero parameters, triggering the baseline score of 4 per evaluation rules. The tool requires no configuration to retrieve the upload constraints, which is appropriate for a global configuration endpoint.

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?

Clearly specifies the action (获取/get) and resource (图片上传配置/image upload configuration), including specific configuration aspects like file types and size limits. Effectively distinguishes from sibling 'upload_image' by clarifying this retrieves constraints rather than performing the upload.

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

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

Explicitly states when to use the tool: '上传图片前先调用此接口' (Call this interface before uploading images). Provides clear prerequisite context, though it could explicitly name the subsequent 'upload_image' tool as the next step in the workflow.

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 supplied, the description carries the behavioral burden well: it declares the operation is lookup-only, discloses that credentials are sensitive and must not appear in chat, logs, or command arguments, and clarifies that pending/processing does not mean success. It omits what a failed or unsupported query returns, but the safety and lifecycle disclosures go well beyond the bare name.

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?

Purpose is front-loaded in the first clause, followed by tightly packed operational rules with no filler sentences. Each clause (object preservation, rate-limit behavior, credential sensitivity, state semantics, recovery constraint) earns its place.

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

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

For a one-parameter read-style tool with no output schema or annotations, the description covers purpose, recovery preconditions, safety handling of credentials, and status semantics. The main remaining gap is what a successful or unsupported query actually returns, which the agent must infer.

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

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

Schema description coverage is 100% and the single operation_id parameter is already fully documented, including the reuse-on-recovery rule and the server-negotiation caveat. The description reinforces that recovery must reuse the original operation_id but adds no new syntax, format, or constraint 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 verb (query-only) and a specific resource (the original image upload credential operation), and "仅查询" plus "不能自动申请新 key" functionally separates it from token-issuing siblings like get_upload_token or get_knowledge_file_upload_operation. It stops short of naming any sibling by name, so differentiation is inferential rather than 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?

It states the positive case (recover by querying the original operation_id only), the negative case (do not re-upload when saving hits a rate limit, do not auto-request a new key), and the state rule (pending/processing is not completion). An agent has enough to decide between reusing this tool and starting a fresh upload.

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 warns credentials are sensitive and must not appear in chat, logs, or command arguments; that rate limiting means do not re-upload; that pending/processing is not completion; and that recoveries must use the original operation_id. The opening sentence about preserving client_request_id is ambiguous and appears to belong to a different tool, which slightly muddies the picture.

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 purpose sentence is not front-loaded; it is preceded by unrelated-looking clauses about client_request_id and task states, and the warning emoji line is appended at the end. Several sentences do not clearly belong to a credential-issuing tool, so the reader must filter to find the operative content.

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

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

For a parameterless-required credential tool with no output schema, the description covers the essential pieces: what is returned, how to use the token (multipart/form-data POST), the follow-up step (save_note with image_id), and two failure modes (mime_type mismatch, rate limiting). Missing is any hint about credential lifetime or whether tokens are single-use.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by adding a real constraint the schema does not state — mime_type must match the actual file format or the OSS signature will fail. It adds nothing new for count or operation_id beyond the schema text.

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

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

The core statement '获取 OSS 图片上传凭证' with the returned fields (accessid/host/policy/signature) is specific and actionable, but it appears mid-way through the description after several sentences about client_request_id preservation, rate limits, and task states that read like guidance copied from another tool. It never contrasts itself with the close siblings upload_image or get_knowledge_file_upload_token.

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 does supply a workflow (upload via multipart/form-data, get image_id, then call save_note) and recovery rules (reuse original operation_id, no new key). However, it gives no explicit rule for choosing this tool over the nearly identical siblings upload_image and get_knowledge_file_upload_token, which is the main decision an agent faces.

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 zero annotations the description carries the full burden and does: it says the list returns only locating info, that partial/warnings mean even the last page may be incomplete, that total_count=null means unknown, and that meta.capabilities/applied_filters/pagination.next_cursor must be checked. It also discloses a hard 5-page discovery limit and conflict-annotation rules for book_info.author vs reference.author.

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?

Purpose is front-loaded, but the body is a dense run-on chain of semicolon-separated rules (pagination, partials, discovery cap, author conflicts) with no grouping, which makes it easy to miss individual constraints.

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 17-parameter tool with no annotations and no output schema, the description supplies the missing return-shape semantics (meta.capabilities, applied_filters, pagination.next_cursor, partial/warnings, total_count=null). Only edge behavior around permission failures and empty-result handling remains thin.

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

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

Schema coverage is 100%, so the baseline is 3; the prose adds cross-parameter constraints and intent beyond the schema, e.g. keeping time/platform/knowledge-base scope together, not adding a default dedao source, and how to use note_type=ref plus real reference fields to resolve book author/title/book_id.

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 (查找笔记) plus the three filtering axes (来源、引用资源、知识库), and immediately distinguishes the tool from get_notes (body retrieval) and get_note (knowledge-base shared notes path). An agent can pick this over its siblings 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?

Explicitly routes body retrieval to get_notes and notes the original permission path via get_note for knowledge-base shared notes, plus concrete rules for unknown platforms (don't auto-add dedao) and a 5-page discovery cap. It gives context but no explicit statement of when NOT to use this tool overall.

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 behavioral burden and does so well for pagination and data completeness: it explains continuing on next_cursor even with an empty page when has_more=true, preserving partial/warnings and metadata_state, and not claiming exhaustive teacher-course coverage. However, it does not explicitly state read-only/no side effects, permissions, or rate 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?

The description is dense but front-loaded with purpose, then parameter rules, pagination behavior, and scope limitations. Every clause carries operational value, especially the continuation and completeness caveats.

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 must explain return behavior; it names key fields such as course_type, course_id, reference.resources.v1, applied_filters, has_more, next_cursor, partial/warnings, and metadata_state. It also explains the course_directory_no_lessons caveat and warns that total is unknown, which is complete enough for correct invocation and interpretation.

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

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

Schema coverage is 71%, and the description adds meaningful semantics beyond the schema: query is course name only with exact/prefix, author is exact, the two are ANDed with at least one required, and cursor continuation must preserve all filters. It does not clarify the required source and resource_type enums, though those are largely 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 states a specific verb and resource: locate Dedao courses that have personal notes by course name/teacher, without a knowledge base. It also distinguishes the tool from list_notes and from full-site course listing or in-course semantic search, so an agent can identify its role.

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 explicitly specifies that query and author are combined with AND and at least one is required, and that match_mode only affects the course name while author is exact. It also explains the downstream use of returned course_type+course_id to filter list_notes and states what the tool is not for.

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. It conveys that this is a read (读取) and that results are scoped to the current user, but says nothing about pagination (implied by limit/since_id), what the report contains, ordering, or whether results are capped at 20 per page.

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 clauses, front-loaded with the core action and resource. The second clause is terse to the point of being cryptic, but it earns its place as a disambiguation hint; 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?

No output schema and no annotations, so the description must cover return shape and paging behavior — it covers neither. An agent calling this cannot tell what a 'sprout report' record looks like or how to page through results without inspecting the schema.

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

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

Schema coverage is 67% and the schema already documents month as YYYY-MM and since_id as the previous page's cursor. The description reinforces month-based selection but adds nothing about limit's page-size role or the pagination flow implied by since_id, so it sits at 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 concrete verb and resource — read (读取) the current user's monthly sprout report — and scopes it to the current user and a month. The trailing clause '发芽不是标记数据' hints at disambiguation from mark-related siblings like get_note_marks, but it never names get_sprout or explains the relationship.

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 month-scoped, current-user framing implies when this tool applies, but there is no explicit when-to-use versus when-not-to-use, and no mention of the closely named sibling get_sprout. Usage must be inferred from the description's scope alone.

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. It usefully discloses the return shape (topics[], has_more, total) and a non-obvious edge rule ('cannot treat an empty library as no notes'). However, it never states read-only semantics explicitly, nor how results combine with or differ from the user's own library, leaving gaps for a 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?

Every clause carries information, but the description is a single dense run-on that interleaves purpose, scope defaults, and multi-step fallback routing. It is hard to parse quickly and the routing logic is not ordered for front-loading the core action.

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

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

No output schema exists, but the description names the returned fields (topics[], has_more, total). All six params are schema-documented at 100% coverage, and the fallback behavior is explained. An agent has enough to call it correctly, though the empty-result handling could be clearer.

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 page, query, scope, author, book_id and page_size with defaults and enums. The description reinforces the DEFAULT vs BOOKSPACE split and the query/author/book_id/pagination handling but adds little beyond what the schema states.

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 states a specific resource and scope: knowledge bases the current user actually subscribes to, explicitly excluding self-created ones. This distinguishes it from the sibling list_topics (own libraries) without naming it outright. An agent can tell what it returns, though the counterpart tool is only implied.

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 concrete routing: 'when own library has no match, supplement here,' and further prescribes a fallback to list_notes' personal-reference route with a condition ('user hasn't limited to only subscribed libraries'). It covers when-to-use and alternatives. The guidance is somewhat buried in dense prose rather than cleanly front-loaded.

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 does carry real weight: it discloses the required 'topic.blogger.read' scope and clarifies that results are summaries rather than full text. It says nothing about ordering, result caps, or pagination behavior despite a page parameter existing.

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

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

Two short sentences with zero waste: the retrieval action and its output scope come first, followed by the permission requirement. Nothing is buried 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 read-only list tool with fully documented params and no output schema, the description adequately covers what comes back (summaries, not original text) and what authorization is needed. Minor gap: no hint about the size or shape of the returned list.

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

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

Schema description coverage is 100% and each parameter already explains its origin (topic_id from list_topics, follow_id from list_topic_bloggers, page defaulting to 1). The description adds no further parameter semantics, so the baseline 3 applies.

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

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

States a specific verb and resource: retrieve the list of contents published by a given blogger within a knowledge base. The parenthetical '摘要，不含原文' meaningfully scopes the output, implicitly separating it from the content-detail sibling, though no 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?

The 'summary only, not original text' clause hints that a different tool is needed for full content, but it never names get_blogger_content_detail or states when to prefer it. No exclusions or prerequisites beyond the scope requirement are given, 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?

No annotations are provided, so the description carries the full burden, and it does add genuine context by disclosing the required 'topic.blogger.read' scope. However, it says nothing about pagination behavior despite a page parameter, nor about the shape or size of the returned list.

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

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

Two short, front-loaded sentences: the purpose first, then the permission prerequisite. Nothing is redundant and nothing needs to be scanned for.

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 two-parameter read tool with no output schema, purpose and auth scope are covered. Missing are the pagination contract (default/size) and any hint of what the returned list entries contain, which matters more here because there are no annotations 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 100% — page (1-based, default 1) and topic_id (sourced from list_topics) are both fully documented in the schema. The description adds no parameter meaning beyond that, 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?

States a specific verb and resource: fetch the list of bloggers subscribed by a knowledge base. It is distinguishable from siblings like follow_topic_blogger (write) and list_topic_blogger_contents (contents of a blogger), though it never explicitly names those alternatives.

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 listing verb plus the knowledge-base scope; an agent can infer this is the read path for bloggers in a topic. There is no explicit when/when-not guidance and no mention of follow_topic_blogger or list_topic_blogger_contents as 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?

With no annotations, the description carries the full burden. It does disclose the return shape at a high level (folder structure plus notes/resources in the current directory), which is genuinely useful. But it says nothing about pagination, ordering, depth limits, permission requirements, or how much of the tree is returned; for a traversal tool those gaps matter.

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 the core action, with the scope note trailing. Nothing is padded, though the second sentence about supported knowledge base types borders on marketing rather than operational detail.

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 must serve as the safety and return contract; it partially does by naming what gets returned. However, for a two-parameter traversal tool an agent still lacks pagination, depth, and permission context. Adequate but with 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 100%: topic_id and directory_id are both documented, including that omitting directory_id means root. The description adds no format, ID-source, or example detail 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?

The description uses a concrete verb phrase ('浏览…文件夹结构及当前目录下的笔记等资源'), clearly a read/traversal operation over the knowledge base tree. It implicitly distinguishes itself from the create/update/delete_topic_directory siblings by being the browsing counterpart, but never names them. Purpose is clear; sibling differentiation is only implied.

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

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

There is no guidance on when to use this versus list_topic_notes, list_topics, or list_reference_resources, nor any stated preconditions or exclusions. The sentence about supported knowledge base types (个人/书籍/客户档案/团队) is scope information, not usage routing. An agent must infer the selection criteria itself.

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 does add useful auth context by stating the topic.live.read scope requirement, and 'list/获取' implies a read operation. However, it says nothing about pagination behavior, ordering, or what the response contains, leaving notable gaps for an unannotated tool.

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

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

Two short sentences with zero waste; the filter condition is front-loaded before the scope requirement. 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?

For a simple paginated read with only two parameters at 100% schema coverage and no output schema, the description gives enough to call it correctly, including the required scope. Minor gaps remain around ordering and return shape, but nothing essential 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%, so both parameters (page, topic_id) are already fully documented in the schema. The description adds no syntax or format detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb (获取/list) and resource (直播/livestreams) scoped to a knowledge base, plus a meaningful filter (completed and AI-processed). It is clear enough to distinguish from generic note tools, though it never names the closest siblings like get_live_detail or follow_topic_live.

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 'completed and AI-processed' qualifier tells the agent what this list contains, implying when it applies. But there is no explicit when-to-use vs. get_live_detail or the follow_topic_live tools, and no exclusion guidance, 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?

With no annotations, the description carries the full burden and does well: it discloses that results are location-only, how to paginate, that IDs must be de-duplicated, and that repeated cursors/pages, no progress, or mid-way failure must not be reported as complete. It omits permission/rate-limit context, which is minor for a read listing.

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 sentences, front-loaded with what is listed and what is returned, then the alternative, then pagination/result-integrity caveats. Dense and largely waste-free, though the final clause is 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?

For a 16-parameter read tool with no annotations and no output schema, the description supplies the missing return-shape context (locating info only) and pagination/completeness semantics. Only the absence of output-schema-like detail on the result fields keeps it from a 5.

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 16 parameters, including the cross-parameter pairing rules (source + reference_resource_type) and the independent time axes. The description only restates the filter categories at a high level, adding little beyond the schema, which fits the baseline 3.

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

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

States a specific verb+resource ('列出知识库内可访问的笔记') and names the filter axes (来源、引用资源、时间). It also distinguishes itself from get_note by saying the list returns only locating info, though it doesn't explicitly separate itself from the sibling list_notes.

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

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

Explicitly says when to use this tool (locating notes with source/reference/time filters) and when to use an alternative ('需要正文和完整元数据时调用 get_note'). The pagination instruction ('按 pagination.next_page 翻页') further constrains usage.

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 supplied, so the description must carry the full behavioral burden. It discloses the return shape (topics[], has_more, total), pagination behavior, and the meaning of an empty result. It does not discuss permission or auth requirements, but for a read-only listing tool that is a minor gap.

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

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

Purpose comes first, followed by scope and matching rules, then the fallback chain; the structure is very efficient for such a dense description. It reads as long, semicolon-joined clauses rather than as clean sentences, which slightly hurts scanability, but no sentence 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?

There is no output schema and no annotations, so the description reasonably compensates by naming the return fields and the pagination flags. The fallback chain and the warning about empty results close the main behavioral gaps. It could still say more about what a topic object contains and what the book_info check involves.

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 most of the value is already in the structured fields. The description restates the query/author AND semantics, the BOOKSPACE restriction, and 'only pass author when you have an author clue', nearly all of which also appear in the schema parameter descriptions, so it adds little beyond what the schema already provides. 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 names a specific verb and resource (retrieve the list of knowledge bases the user created, owns, or joined) and immediately pins down the default scope. It also distinguishes itself from the sibling list_subscribe_topics by describing the exact situation in which that sibling is the correct fallback.

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 routing rules: use scope=BOOKSPACE when the clue is a book title or author, pass only author when the only clue is an author, fall back to list_subscribe_topics when there is no match and the user has not restricted the search to owned topics, and only then fall back to the reference sources of list_notes. It also states a negative rule (an empty library must not be reported as the account having no highlights), which is exactly the kind of exclusion an agent needs.

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 exist, so the description carries the full behavioral burden. It does disclose two useful traits beyond the schema: results are ranked by relevance descending, and the caller needs note.recall.read scope. It omits read-only confirmation, what a result item contains, and any limits on corpus or latency.

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 front-loaded statements: what it does, when to use it, result ordering, and the auth requirement. No filler, though the scope sentence and the ordering sentence could be merged for tighter structure.

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

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

No output schema exists, so the description must describe return values; it only says results are sorted by relevance and never describes the shape of a hit (note ID, title, snippet). Given a four-parameter tool with a mode enum, this leaves an agent guessing about the response.

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 query, top_k, response_mode, and max_snippet_chars are already fully documented in the schema. The description adds no parameter-level detail such as query length, when to set response_mode=snippet, or the interaction between snippet mode and course filtering, so it stays at 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: global semantic recall across all notes, plus the concrete query intent. It is clearer than the sibling list_notes/get_notes by scope (global) and by method (semantic), but it never names a sibling or explains how it differs from recall_knowledge, which is the most confusable neighbor.

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 two example phrases ("搜一下", "找找哪些笔记提到了 XX") imply when to reach for it, which is real guidance. However, there is no explicit exclusion, no mention of when to use recall_knowledge or plain listing instead, and no guidance on choosing top_k or response_mode.

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, so the description carries the burden. It discloses the relevance-descending sort order and the required scope 'note.topic.recall.read', both valuable behavioral facts beyond the schema. It omits pagination/return-shape detail, 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?

Four short sentences, front-loaded with the core identification '知识库语义搜索' followed by scenario, return ordering, and auth. Every sentence carries distinct information with zero waste.

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-param read tool with no annotations and no output schema, it covers the essentials: scope, trigger, ranking, and required scope. Return value structure is only summarized as relevance-ordered, which is adequate but not exhaustive given the missing output schema.

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

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

Schema coverage is 100%, so all parameters (query, top_k, topic_id, response_mode, max_snippet_chars) are already documented in the schema. The description adds no parameter-level detail beyond restating the scoping to a topic, so baseline 3 applies.

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

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

States a specific verb+resource: semantic recall within a specified knowledge-base scope. The phrase '在指定知识库范围内' distinguishes it from the sibling `recall`, which lacks that scoping, though the sibling is not 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?

Provides a concrete usage trigger and example ('在我的 XX 知识库搜一下 XX'), giving clear context for when to call it. No explicit exclusions or named alternative tools, so not a full 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a mutation but does not explain whether the note is deleted permanently, merely unlinked from the topic, what happens if the note or topic is missing, or whether 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?

The description is a single short sentence with no filler and the action is front-loaded. It is efficient, though its extreme brevity leaves important behavioral context unstated.

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 annotations and no output schema, the description is too sparse. It does not clarify the difference between removing a note from a topic and deleting it, nor does it describe side effects, reversibility, or expected outcomes.

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 both parameters are already documented in the input schema. The description adds no parameter-level detail, which is acceptable given the schema coverage but 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 states a clear verb and resource: removing a note from a knowledge base. It is understandable without opening the schema, but it does not distinguish this operation from sibling tools such as delete_note or batch_add_notes_to_topic.

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

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

There is no explicit guidance on when to use this tool versus alternatives like delete_note, nor any prerequisites or exclusions. Usage is only implied by the tool name and brief description.

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 discloses that ordinary link notes are asynchronous and return a tasks array requiring polling, while plain_text and share-link notes return ids synchronously, and it lists the returned fields per type. Gaps remain on permissions, quota implications (a get_quota sibling exists) and what happens to topic placement if topic_id is omitted.

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 most important constraint (create-only) and uses bold section headers so the flow and return-value rules are scannable. It is somewhat long and repeats the share-link sync/async rule that the link_url schema field already states, which is mild duplication.

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 9-parameter, multi-mode creation tool with no output schema, and the description compensates by explaining return values per note type and the chained upload/poll tools. Not fully complete: no guidance on default topic placement, sub-note creation via parent_id, or limits/idempotency expectations.

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

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

Schema coverage is already 100%, so baseline is 3; the description adds genuine meaning beyond it by explaining the required two-step image_urls flow, the internal-link URL format for content, and the sync/async consequence of link_url type. It does not add anything about parent_id or topic_id semantics, which remain schema-only.

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

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

Opens with a specific verb+resource (create a note) and immediately draws the boundary against the closest sibling by stating it only creates and cannot edit existing notes (update_note exists among siblings). It then enumerates the three supported note types, so an agent can distinguish it from get_note/list_notes 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?

Gives explicit workflows and alternatives: for img_text call upload_image first to obtain image_url, and for citing notes in shared contexts prefer share_note and embed the share link instead of an internal link. It also states when polling is required (ordinary links via get_note_task_progress) versus not required (share links), which is exactly the when-to-use routing an agent needs.

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 load and does well: it discloses idempotency (repeat calls return the same share_url) and the required note.sharing.write scope, which is auth context an agent must know before calling. It omits whether a share can be revoked or what error surfaces when the scope is missing.

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 first, then the idempotency behavior, then the auth prerequisite. Every sentence earns its place and nothing is 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?

No output schema exists, and the description compensates by naming the returned share_url field, along with the auth scope. For a two-parameter tool this is nearly complete; only failure/revocation behavior is absent.

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 both note_id and share_exclude_audio are already documented in-schema. The description adds no extra parameter semantics, so baseline 3 applies.

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

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

States a specific verb and object: generate a public share link for a note. No share-related sibling exists in the tool list, so ambiguity is low even without explicit differentiation, though it never names a nearest alternative.

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 explicit when-to-use or when-not-to-use guidance. Idempotency implies it is safe to call repeatedly, but the agent is left to infer context such as whether an existing share is simply returned.

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 usefully discloses the plain_text restriction, the at-least-one-field rule, and that tags are replaced rather than merged. However, it does not mention permissions, error behavior for unsupported note types, or what the operation returns, so behavioral coverage remains only moderate.

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

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

The description is short, front-loads the core action, then immediately surfaces the critical warning and validation rule. Every sentence contributes useful information 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 four-parameter mutation tool with no annotations, the description covers the key call-time constraints: supported note type, required non-empty payload, and tag replacement behavior. It does not explain return values or permission requirements, but the schema fully documents the individual parameters.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still adds a cross-parameter constraint not present in the schema (at least one of title, content, or tags must be supplied) and reinforces the tags replacement semantics, giving it value beyond the parameter descriptions.

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

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

The description states a specific verb and resource: updating an existing note's title, content, or tags. It also scopes which note types are supported, which helps distinguish it from tools like create/save note flows, though it does not explicitly name sibling alternatives.

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 clearly states an exclusion (only plain_text notes are supported; link and image notes cannot be updated) and a prerequisite (at least one of title, content, or tags must be passed). It does not contrast with alternatives such as add_note_tags or delete_note_tag, which keeps it from a 5.

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

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

With no annotations, the description must carry the behavioral load; it does disclose partial-update semantics ('unspecified fields remain unchanged'), which is genuinely useful for a mutation tool. It does not say what permissions are needed, whether moving a folder is recursive, or how collisions/duplicate names are handled.

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

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

Two short sentences with the action front-loaded and the partial-update caveat second; nothing is wasted. It is sparse rather than bloated, and the brevity is appropriate even if the content is thin.

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 omits the identity semantics of topic_id/directory_id and any error or permission behavior. What is present is accurate, but not enough for an agent to call it confidently.

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 must compensate, and it only implicitly maps 'rename' to name and 'move' to parent_id. It never explains what directory_id versus topic_id means or why both are required, leaving the two mandatory parameters undocumented in both places.

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 pair (rename/move) and a specific resource (knowledge-base folder), which clearly separates it from the sibling create_topic_directory, delete_topic_directory and list_topic_directories. It does not name those siblings explicitly, but the action scope 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 verbs 'rename or move' imply when to use the tool, and the second sentence tells the caller that unspecified fields stay unchanged. There is no explicit statement of when NOT to use it or which sibling to pick for creation/deletion, 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses credential sensitivity, rate-limit retry behavior, status semantics, recovery constraints, and the return value. It still omits details such as authentication requirements, upload size limits, or overwrite behavior, so it is strong but 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?

Most sentences are useful and there is little empty wording, but the core purpose appears near the end after several warnings, and the opening clause about retaining the uploaded object and client_request_id is hard to parse. It is concise but not well front-loaded.

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 moderate-complexity upload tool with no output schema, the description explains the return value image_url and how it feeds image note creation, plus important retry and recovery caveats. It is complete enough to call correctly, though some operational limits remain unstated.

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

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

Schema description coverage is 100%, so the schema already documents mime_type, image_path, image_base64, and operation_id. The description adds meaningful operation_id recovery semantics and warns against requesting a new key, going beyond the schema without needing to repeat field definitions.

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: "上传图片到 OSS" (upload image to OSS), and it names the returned image_url and its downstream use. It does not explicitly distinguish itself from upload_knowledge_file, so it is clear but not fully sibling-differentiated.

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 concrete operational guidance: do not re-upload when saving hits rate limiting, pending/processing does not mean done, and recovery must query the original operation_id rather than requesting a new key. It does not explicitly name get_upload_operation as the polling tool, leaving one routing detail 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 it delivers meaningful behavior: rate-limit semantics, idempotency expectations, credential sensitivity, async job states (pending/processing ≠ complete), and the metadata-only constraint that forbids local paths and base64. It weakens itself by referencing client_request_id and operation_id, which do not exist in the input schema, creating ambiguity about the actual call contract.

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 text is a run of semicolon-separated fragments with no front-loaded statement of what the tool does, opening instead with idempotency advice. Warnings and workflow rules are interleaved without structure, forcing the agent to parse operational caveats before understanding the core action.

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

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

For a complex asynchronous, six-parameter, metadata-registration tool with no annotations or output schema, the description does cover result handling (poll list_topic_directories) and failure modes. It still leaves the parameters and the prerequisite token step unexplained, so an agent could not reliably construct the request.

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 six required parameters, so the description must compensate. It only clarifies the nature of url (remote OSS object, not a local path or base64) and implies topic_id/directory_id through the polling instruction; md5, file_name, and file_type receive no explanation at all.

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 makes clear that this tool registers an already-uploaded OSS object into the knowledge base, accepting metadata only ('OSS 直传成功后将原文件加入知识库，只接收元数据，不接收本地路径或 base64'). This distinguishes it from an actual upload step, which is valuable. It is fragmented and never states the primary action up front, but an agent can derive the verb and resource.

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

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

It gives explicit when-not guidance ('保存遇限流不要重新上传'), a recovery rule (only query the original operation_id, never request a new key), and names the alternative for status checking (list_topic_directories until SUCCESS or FAIL). However, the preceding token-acquisition step (get_knowledge_file_upload_token / get_upload_token) is not mentioned, leaving the overall call sequence incomplete.

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