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

No annotations provided, yet description lacks behavioral disclosure. It does not specify idempotency (whether adding existing tags errors or is silently ignored), atomicity, or validation rules. The agent cannot determine if this appends to or replaces existing tags.

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?

Extremely concise single sentence with no redundancy. However, the brevity leaves behavioral gaps; one additional sentence covering idempotency or error behavior would improve utility without sacrificing clarity.

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?

Adequate for a simple 2-parameter mutation tool with complete schema coverage. However, lacking output schema and annotations, the description should have disclosed success/failure behavior and tag creation semantics to be fully complete.

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

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

With 100% schema coverage, the schema fully documents both parameters (note_id and tags). The description does not add semantic context like ID format examples or tag validation rules, warranting baseline score of 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?

The description clearly states the verb (添加/add), resource (tags), and target (note) with identifier support. However, it fails to distinguish from sibling tool delete_note_tag or clarify additive vs. replacement behavior.

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 guidance provided. The description does not indicate when to use this tool versus delete_note_tag or update_note, nor does it mention prerequisites like whether tags must exist beforehand or are created on-the-fly.

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 of behavioral disclosure but only repeats the 20-item limit already present in the schema. It fails to disclose idempotency, transaction behavior (atomic vs partial), authentication requirements, or 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 single-sentence description is efficiently structured with the action front-loaded and zero redundant words. Every element serves a descriptive purpose.

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 2-parameter batch operation with complete schema coverage and no output schema, the description is adequate for invocation, though lacking behavioral richness that would help an agent handle edge cases or optimize usage.

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

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

With 100% schema coverage, the baseline is 3. The description adds no new syntax details, parameter relationships, or format guidance beyond what the schema already provides (completely overlapping with the note_ids description regarding the 20-item limit).

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 the action (batch add), resources (notes to knowledge base/topic), and key constraint (max 20 per batch). However, it does not explicitly differentiate from sibling tools like 'add_note_tags' (tags vs topics) or 'remove_note_from_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?

The description provides the batch size limit (20), but offers no guidance on when to use this tool versus alternatives, prerequisites (e.g., note existence), or error handling strategies.

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 provided, the description carries the full burden and successfully discloses two key behavioral traits: (1) the soft-delete nature (moves to trash rather than immediate destruction), and (2) the specific permission scope required. It does not mention reversibility, rate limits, or error cases.

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

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

Two sentences efficiently convey all necessary information: the first states the action and mechanism (trash), the second states the permission requirement. No redundant words or tautology; every element 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?

Given the simplicity (1 parameter, no output schema) and lack of annotations, the description adequately covers the essential behavioral context (trash behavior, auth scope). It could be improved by mentioning error cases (e.g., note not found) or return value structure, but it is complete enough for a straightforward deletion 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 coverage is 100% with the single parameter 'note_id' already described as '笔记 ID' in the schema. The description confirms the operation applies to the note but does not add syntax details, format constraints, or examples beyond what the schema provides, warranting the baseline score.

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 ('删除' / delete) with clear resource ('笔记' / note) and distinguishes the specific behavior by specifying it moves to trash ('移入回收站') rather than permanent deletion. This clearly defines the tool's function without ambiguity.

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 clear prerequisite context by stating the required OAuth scope ('note.content.trash'), which is essential usage information. However, it does not explicitly differentiate from siblings like 'update_note' or 'save_note', though the verb 'delete' makes this relatively clear.

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

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

Discloses the critical behavioral constraint that system tags are protected/deletion-resistant. Since no annotations exist, description carries full burden; could improve by stating error behavior (exception vs silent failure) or idempotency (safe to retry?).

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 sentence, ~20 characters. Action verb front-loaded, constraint cleanly parenthesized. Zero redundancy or waste while capturing essential scope limitation.

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?

Adequate for a 2-parameter deletion tool with no output schema. Covers primary function and important constraint. Minor gap: could specify return behavior (void/success boolean) or confirmation of deletion.

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 has 100% description coverage ('笔记 ID', '要删除的标签 ID'), clearly documenting both note_id and tag_id. Description does not repeat these details but doesn't need to; baseline 3 appropriate when schema already fully documents parameters.

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

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

Excellent specificity: '删除' (delete) + '笔记的指定标签' (note's specified tag) clearly identifies the resource and action. The parenthetical constraint '(系统标签不可删除)' immediately distinguishes scope/capabilities from sibling tools like delete_note or remove_note_from_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?

Provides explicit when-not guidance '(系统标签不可删除)' indicating system tags are protected. However, lacks explicit when-to-use guidance versus siblings like remove_note_from_topic or the inverse operation add_note_tags.

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 communicates the authorization requirement (scope) and the data completeness guarantee (full text vs. summary via post_media_text mention). It does not disclose rate limits or caching behavior, but covers the critical safety/auth aspects.

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

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

Two tightly constructed sentences: the first establishes purpose and key return value, the second states the auth prerequisite. Zero redundancy, efficiently 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?

Given the absence of an output schema, the description minimally compensates by mentioning one key return field (post_media_text), but fails to describe the complete response structure or pagination behavior. Adequate for a simple 2-parameter retrieval tool but leaves 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?

With 100% schema description coverage, the structured fields already define both parameters clearly (including the critical fact that post_id comes from list_topic_blogger_contents). The description adds no additional input semantics, meeting the baseline expectation.

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 the tool retrieves 'blogger content details' (获取博主内容详情) with the specific value-add of including 'full original text' (完整原文), which distinguishes it from the sibling listing tool. However, it does not explicitly contrast when to use this versus list_topic_blogger_contents.

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 provides essential prerequisite information (the scope topic.blogger.read is required), but lacks explicit guidance on when to use this tool versus alternatives like list_topic_blogger_contents. The workflow dependency is buried in the schema parameter description rather than the main 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?

No annotations provided, so description carries full burden. It discloses the required OAuth scope (topic.live.read) and reveals return content structure (post_summary, post_media_text). However, it lacks details on error handling, idempotency, or rate limits that would fully characterize the operation's behavior.

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

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

Two sentences with zero waste: first sentence declares purpose and return payload, second states auth requirement. Information density is high with no filler or repetition of schema details.

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 lacking output schema, the description compensates by explicitly naming the key return fields (post_summary, post_media_text) and the required scope. Given the tool's narrow focus (fetching a specific live record) and complete input schema, the definition provides sufficient context for invocation.

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

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

Input schema has 100% description coverage (topic_id and live_id fully documented). Description text does not add redundant parameter details, meeting the baseline for high-coverage schemas. It references list_topic_lives in the live_id schema description, providing useful lineage context.

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?

Description uses specific verb '获取' (get) + resource '直播详情' (live broadcast details) and explicitly distinguishes from sibling note tools (get_note, list_notes) by targeting 'live' content. It further clarifies the specific data returned: AI summary and full transcription.

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 clear prerequisite: '需要 topic.live.read scope' (requires topic.live.read scope). Implies usage context by detailing the specific outputs (AI summary, transcription) available through this endpoint, though it does not explicitly name sibling alternatives like list_topic_lives in the main description text.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and partially succeeds by listing comprehensive returned content (attachments, transcriptions, etc.), implying a rich read operation. However, it omits critical behavioral aspects such as error handling for invalid IDs, authentication requirements, rate limits, or 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 consists of a single, front-loaded sentence that immediately states the core purpose followed by a concise enumeration of return content types without redundant phrasing or wasted words. Every element earns its place by conveying specific information about the operation's scope and output richness.

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's simple two-parameter structure with complete schema documentation and no output schema, the description adequately explains what data is retrieved by enumerating content types, sufficient for an agent to understand the tool's utility. While error handling and authentication details are missing, the overall completeness is reasonable for a straightforward retrieval 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?

The input schema has 100% description coverage with both parameters ('id' and 'image_quality') fully documented in the schema itself, establishing the baseline score of 3. The description adds no supplemental information about parameter semantics or formats, but this is acceptable given the schema's completeness.

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 '获取' (get/retrieve) with resource '笔记' (note) and enumerates detailed content types returned (body, tags, attachments, audio transcriptions, web links), distinguishing it from sibling mutation tools like delete_note or update_note. However, it does not explicitly characterize the operation as read-only to absolutely clarify its distinction from state-modifying siblings.

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

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

The description provides no guidance on when to use this tool versus alternatives such as list_notes for browsing multiple notes or save_note for creation, nor does it mention prerequisites like obtaining the note ID from list_notes. This absence of contextual decision-making criteria leaves agents without explicit boundaries for tool selection.

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

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

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?

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?

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 provided, description carries full burden. It successfully discloses return fields (accessid/host/policy/signature), upload target (Alibaba Cloud OSS), failure mode (signature fails on mime_type mismatch), and downstream dependency (save_note). Minor gap: no mention of token expiration/TTL.

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 sentences with zero waste: purpose, return values, workflow integration, and critical warning. The warning emoji effectively signals high-priority constraint. Information is front-loaded and structured logically.

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?

Lacking output schema, description compensates by enumerating return fields and explaining the full integration flow with sibling tools. Complete enough for invocation, though token expiration time would strengthen it further.

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%, but description adds critical validation semantics not present in schema: the warning that mime_type must match actual file format or OSS signature fails. This constraint is essential for correct invocation and not inferable from the enum list alone.

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

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

Description clearly states specific action (获取/get) and resource (OSS image upload token/credential), and distinguishes from sibling `upload_image` by specifying this returns multipart/form-data credentials for Alibaba Cloud OSS rather than performing a direct 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 documents the complete workflow chain (get token → upload to OSS → obtain image_id → use save_note), specifies the HTTP method (multipart/form-data POST), and includes a warning about the prerequisite condition (mime_type must match actual file format).

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 full burden. It successfully discloses the fixed page size (20 items) and cursor-based pagination pattern. Missing safety classification (read-only implications), rate limits, or return structure 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?

Two compact sentences with zero redundancy. Front-loaded with purpose and constraint (20 items), followed immediately by usage instructions. Appropriately sized for the tool's complexity.

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?

Adequate for a single-parameter listing tool: covers pagination mechanics and page size. However, without an output schema, the description omits return value structure (what fields the notes contain), which would be necessary for complete contextual understanding.

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% (since_id fully documented). Description adds value by clarifying the pagination workflow—specifically that subsequent requests should use the last note ID from the previous page—providing semantic context beyond the schema's basic cursor definition.

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?

Clear verb-resource combination ('获取笔记列表' / Get note list) and specifies the fixed page size (20 items). However, it fails to distinguish from sibling list_topic_notes regarding scope (global vs topic-scoped lists).

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 specific pagination instructions (first request use 0, subsequent use last ID from previous page), which guides invocation. However, lacks guidance on when to use this versus list_topic_notes or other filtering 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 provided, description carries full disclosure burden. It successfully discloses auth requirement ('需要 topic.blogger.read scope') and output data shape ('摘要，不含原文'), but omits pagination behavior (items per page), read-only safety guarantees, or error conditions.

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?

Extremely compact single sentence with parenthetical clarification. Every clause earns its place: action clause, output specification, and permission requirement. No redundancy or filler text.

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

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

Appropriate for a 3-parameter list operation with simple types. Without output schema, description adequately specifies return format (summary list). Only minor gap is lack of pagination metadata disclosure (e.g., default page size).

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

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

Schema coverage is 100% so baseline is 3. Description adds critical semantic context not in schema: the required OAuth scope ('topic.blogger.read'). It also clarifies the content type returned, helping contextualize why the parameters (topic_id, follow_id) are needed.

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

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

Description uses specific verb '获取' (get/fetch) with clear resource '内容列表' (content list) and distinguishes from sibling get_blogger_content_detail by specifying it returns only '摘要，不含原文' (summaries without original text). Clearly scoped to a specific blogger within a knowledgeBase.

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

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

Implies usage context by specifying output is summaries not full text (guiding choice vs get_blogger_content_detail), but does not explicitly state workflow prerequisites like 'use list_topic_bloggers first to obtain follow_id' - that reference exists only in the schema, not the description. No explicit 'when not to use' 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 provided, the description carries the full disclosure burden. It successfully communicates the authorization requirement (scope), but does not address pagination limits (despite the 'page' parameter), read-only safety, or error behaviors (e.g., invalid topic_id). It meets minimum viable disclosure but lacks richness.

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 optimally concise: two clauses totaling roughly 20 characters that immediately state the purpose followed by the authorization requirement. Zero redundancy; every element 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 list operation with two flat parameters, the description is minimally adequate. However, without an output schema or annotations, gaps remain: it omits what constitutes a 'blogger' object, pagination page-size limits, and how this relates to list_topic_blogger_contents.

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

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

Schema description coverage is 100%, with topic_id clearly documented as an alias from list_topics and page documented with default behavior. The description does not add parameter-specific semantics beyond what the schema provides, warranting the baseline score of 3 for well-documented schemas.

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

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

The description clearly states the action (获取/get) and resource (博主列表/blogger list) scoped to a knowledge base (知识库). It identifies what the tool retrieves, though it doesn't explicitly differentiate from the sibling tool list_topic_blogger_contents which retrieves content rather than the bloggers themselves.

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 concrete authorization prerequisite (需要 topic.blogger.read scope), indicating when the tool can be invoked. However, it lacks explicit guidance on when to use this versus similar list operations or any workflow prerequisites beyond the scope requirement.

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 reveals filtering behavior (only completed and AI-processed lives) and authorization requirements, but omits safety classification (read-only), pagination limits, or error behaviors.

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?

Extremely concise with two sentences that earn their place: the first defines the operation and filters, the second states prerequisites. Information is front-loaded with no redundant language.

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 list operation with 100% schema coverage and no output schema, the description provides sufficient context by explaining what subset of data is returned (completed/AI-processed) and the auth requirement. It appropriately delegates parameter details to 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 100%, establishing a baseline of 3. The description implicitly links the 'knowledge base' mentioned in the first sentence to the `topic_id` parameter, but the schema already explicitly defines `topic_id` as '知识库 ID', so no additional semantic value is added beyond the structured definition.

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 (获取/get) and resource (直播列表/live stream list), and clearly defines scope (知识库中/in knowledge base). It distinguishes from siblings like `get_live_detail` by specifying this returns a filtered list (completed and AI-processed), though it doesn't explicitly name 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?

The description states the required scope (topic.live.read), providing prerequisite context. However, it lacks explicit guidance on when to choose this over `list_topic_notes` or `get_live_detail`, though the filtering criteria (completed + AI-processed) imply usage context.

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 communicates the fixed pagination behavior (每页 20 条/20 items per page), but omits other behavioral traits like read-only safety, ordering, 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?

Single sentence with zero waste. Front-loaded with action and scope, includes pagination detail, and avoids redundancy with the schema. Every element 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?

Adequate for a simple 2-parameter list operation with good schema coverage. However, lacking an output schema, the description omits what fields the notes contain, their format, or how to handle empty results. Also lacks explicit differentiation from 'list_notes' despite its existence.

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?

Despite 100% schema coverage (baseline 3), the description adds crucial semantic context: it implies the relationship between 'topic_id' (知识库/knowledge base) and the results, and specifically mentions the page size (20) which explains the effect of the 'page' parameter beyond the schema's basic definition.

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 defines the scope (获取/retrieve, 笔记列表/note list) and distinguishes from sibling 'list_notes' by specifying '指定知识库内' (within specified knowledge base). It identifies the resource and constraints precisely.

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 guidance on when to use this tool versus the sibling 'list_notes' or other retrieval tools. While the topic-scoping implies usage, there are no explicit when/when-not instructions or alternative recommendations.

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 significant load by disclosing pagination limits (fixed 20 per page), return structure (topics[], has_more, total), and detailed object fields (stats breakdown). Missing safety hints (read-only implication not stated).

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?

Information-dense Chinese description effectively packs pagination rules, return schema, and object structure into one sentence. No redundant text, though slightly dense.

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

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

Despite lack of output schema, description comprehensively documents the response structure and pagination behavior adequate for a simple list operation. Complete for its complexity level.

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 has 100% coverage for the single 'page' parameter. Description adds crucial context by specifying the page size (20 items), which is necessary for proper pagination logic, exceeding baseline expectations for fully documented schemas.

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

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

Clearly states it retrieves a list of knowledge bases (topics) with specific pagination (20 items per page). Identifies the resource accurately, though it doesn't explicitly differentiate from sibling list operations like list_topic_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?

No explicit guidance on when to use this versus siblings (e.g., list_topic_notes) or prerequisites. Usage must be inferred from the resource name and described return values.

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, so description carries full burden. It discloses result ordering ('按相关度从高到低排序') and authorization requirements ('需要 note.recall.read scope'). However, lacks explicit safety declaration (read-only vs destructive), error behavior, or result structure details that would be expected for a tool without 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?

Four structured segments: function definition, usage scenarios, result behavior, and auth requirements. Zero redundancy, well front-loaded with colons and quotes creating clear visual structure. Every sentence earns its place.

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

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

For a 2-parameter search tool with 100% schema coverage and no output schema, description adequately covers purpose, scope constraints, and sorting behavior. Minor gap in not describing the return structure (e.g., whether it returns note IDs, titles, or content snippets), but sufficiently complete for invocation.

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

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

Schema has 100% description coverage with clear Chinese descriptions ('搜索关键词或语义描述', '返回数量，默认 3，最大 10'). Description does not add param semantics beyond schema, which is appropriate given the schema is comprehensive; 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?

Description explicitly states '全局语义搜索：在所有笔记中进行语义召回' (global semantic search/retrieval across all notes), providing specific verb+resource that clearly distinguishes it from sibling recall_knowledge (which targets knowledge bases) and list_notes (likely exact filtering).

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 explicit applicable scenarios with quoted examples: '适用场景：「搜一下」「找找我哪些笔记提到了 XX」'. Clearly indicates when to use (semantic search, finding mentions) though could more explicitly contrast with list_notes for exact matching or recall_knowledge for external knowledge.

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, so description carries full burden. It discloses result sorting (by relevance) and required permission scope (note.topic.recall.read). However, it lacks disclosure of safety characteristics (implied read-only but not stated), error handling, 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?

Four information-dense segments: operation definition, scope constraint, usage scenario, and result/permission characteristics. Every clause earns its place; no redundancy or tautology despite being in Chinese.

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?

Appropriate for a search tool: explains return behavior (relevance sorting) and authorization requirements despite lacking output schema. With 100% schema coverage and clear scope disclosure, it is complete enough for invocation, though error scenarios could be mentioned.

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%, establishing a baseline of 3. The description mentions 'within specified knowledge base' (topic_id) and 'search' (query) but does not add syntax, format details, or constraints beyond what the schema already documents. The example usage pattern provides contextual glue between parameters.

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

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

Specific verb 'semantic search/recall' with resource 'knowledge base' and scope constraint 'within specified knowledge base'. The term '知识库' (knowledge base) clearly distinguishes this from the sibling generic 'recall' 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?

Provides explicit applicable scenario pattern 'Search for XX in my XX knowledge base' and mentions required scope. However, it does not explicitly name the sibling 'recall' tool as an alternative or define when NOT to use this tool.

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 full burden of disclosure. It fails to clarify whether the operation is destructive (permanent deletion) or reversible (unlinking), or what happens to the note after removal. Does not mention idempotency or 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 sentence with no redundant text, but it is arguably too terse given the tool's behavioral ambiguity and lack of annotations. The brevity results in under-specification rather than efficient communication.

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, and given the potential confusion with 'delete_note', the description should explain the relationship between notes and topics, confirm the note persists after removal, and state what the operation returns. Currently incomplete.

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

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

Schema description coverage is 100% (both topic_id and note_ids are documented), so the description does not need to repeat parameter details. It provides no additional parameter semantics beyond the schema, meeting the baseline for high-coverage schemas.

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

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

Description clearly states the action (remove) and target (note from knowledge base/topic) using specific verbs. However, it fails to distinguish from sibling tool 'delete_note', leaving ambiguity about whether the note itself is deleted or merely unlinked from the 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?

No guidance provided on when to use this tool versus 'delete_note' or 'batch_add_notes_to_topic'. Given the sibling tools, clarifying that this only removes the association (not the note object) would be essential for correct agent selection.

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

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

No annotations provided, so description carries full burden. Discloses critical behavioral traits: asynchronous AI processing for link notes, varying return schemas by note_type, and image URL pre-validation requirements. Minor gap on rate limits or error behaviors, but strong coverage of operational model.

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?

Efficient structure with bold headers separating workflow instructions from return value documentation. Front-loaded purpose statement, zero redundancy. Chinese text is dense but well-organized with visual markers (⚠️) for critical 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?

Comprehensive despite missing output schema. Description compensates by documenting return value structures for each note type (including the `tasks` array for links). Covers 7 parameters with validation rules (tag limits, parent constraints) and cross-tool dependencies. Complete for agent invocation.

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

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

Schema coverage is 100% (baseline 3), but description adds essential workflow semantics: explains `image_urls` requires prior `upload_image` call, notes that `content` is unnecessary for link notes, and clarifies conditional requirements (`link_url` required for link type). Adds value beyond individual field 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?

Description opens with specific verb '新建笔记' (create new note) and immediately distinguishes from sibling tool `update_note` via the explicit constraint '⚠️ 仅支持新建，不支持编辑已有笔记' (only supports creating new, not editing existing). Clear scope boundary.

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

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

Explicitly states when NOT to use (editing) and provides complete workflows referencing sibling tools: specifies prerequisite `upload_image` for image notes, and mentions `get_note_task_progress` for querying async link processing. Clear alternative paths documented.

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, so description carries full disclosure burden. It successfully communicates critical behavioral traits: type restrictions (plain_text only), destructive replacement semantics for tags (覆盖/overwrite), and partial update capability (optional fields). Missing: error behavior for invalid note_id, permission requirements, or atomicity guarantees.

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 sentences, zero waste. Front-loaded with core purpose (sentence 1). Immediate constraint warning with emoji (sentence 2). Validation rule (sentence 3). Behavioral detail (sentence 4). Excellent density and scannability.

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 mutation tool with 4 parameters, 100% schema coverage, and no annotations/output schema, description adequately covers: purpose, type constraints, validation rules, and mutation semantics (replace vs append). Could be improved by mentioning return value format or error cases, but sufficient for correct invocation.

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

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

Schema coverage is 100% with detailed Chinese descriptions already covering 'new' values and optionality. Description adds crucial validation logic not present in schema: '至少需要传 title、content、tags 中的一个' (at least one required). Adds warning emoji structure for constraints. Adds value beyond schema despite high coverage 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?

Description clearly states the specific action (更新/update) on the resource (已有笔记/existing notes) and identifies the updatable fields (title, content, tags). It distinguishes scope from siblings by limiting to 'plain_text' type explicitly, differentiating from 'save_note' (creation) and media-specific 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 clear constraints for invocation: 'plain_text only' restriction, and validation rule requiring at least one of title/content/tags. Explains tag replacement semantics which implicitly contrasts with sibling 'add_note_tags'. However, lacks explicit 'when not to use' alternatives (e.g., doesn't explicitly direct users to 'save_note' for new notes or 'add_note_tags' for appending).

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 of behavioral disclosure. It mentions the successful return value (image_url) and its downstream use, but omits critical mutation-related details such as file size limits, network requirements, error scenarios, or idempotency.

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 efficiently structured sentences convey the operation, destination, return value, and specific integration context without redundancy. Information is front-loaded and 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?

Without annotations or an output schema, the description adequately establishes the basic upload-to-note workflow but leaves gaps regarding error handling, supported file size limits, or the fact that parameters are mutually exclusive (though this is covered in 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?

The input schema has 100% description coverage, documenting all three parameters including their mutual exclusivity (二选一) and defaults. The description adds no additional parameter semantics beyond the schema, warranting the baseline score of 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?

The description clearly states the action (upload), destination (OSS), and return value (image_url). It distinguishes from siblings by specifying the integration point—creating image notes—linking it to the save_note workflow within the note-taking domain.

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 provides implied usage context by noting the return value is for the image_urls parameter when creating image notes, guiding the agent toward the correct workflow. However, it lacks explicit when/when-not guidance or comparison to siblings like get_upload_token or get_upload_config.

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