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

With no annotations, the description carries the burden of behavior disclosure. It mentions that the note must already exist and that a notebook_id can be repurposed as note_id, but it does not mention side effects, permissions, or error conditions. This is minimal but not fully transparent.

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 sentences, with the purpose front-loaded and the prerequisite guidance in the second sentence. Every word contributes value.

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

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

For a simple add operation with no output schema, the description is adequate: it states the purpose, explains how to obtain the key parameter, and references prerequisites. It could optionally mention failure behavior, but the tool is straightforward.

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 covers all four parameters with descriptions, including the nuance that note_id can be a doc_id or notebook_id. The description repeats this information without adding new meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a clear action: '将已有的 IMA 笔记添加到知识库' (add an existing IMA note to the knowledge base). The word '已有的' (existing) distinguishes this tool from create_note, which creates new 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?

It provides explicit prerequisites for obtaining note_id: either create_note to get a doc_id, or use get_media_info's notebook_id. This gives clear context for when to use the tool and how to prepare inputs, though it doesn't directly contrast with sibling tools.

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

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

With no annotations provided, the description carries the full burden. It discloses the IMA_COOKIE environment variable requirement, the RAG-based behavior, deep full-text search, and the specific ID field warning. It does not describe return format or failure modes, but it meaningfully adds context beyond the input schema.

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 front-loaded with a clear purpose statement, followed by auth requirement, a warning about the ID, and example queries. Each sentence adds value, though there is minor redundancy with the web-interface equivalence and full-text mention. Overall well-structured for its length.

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 annotations and output schema, the description covers essential operational needs: tool purpose, required IMA_COOKIE, correct knowledge_base_id sourcing, and example questions. It stops short of describing output format or error cases, but for selecting and invoking the tool, it is sufficiently 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?

The input schema already provides 100% coverage with descriptions for both parameters, including the instruction to use cookie_knowledge_base_id. The description adds typical usage examples (e.g., 'what were the main conclusions of last week's meeting?'), which slightly enrich the question parameter's semantics, but the core meaning is already in the schema. 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 clearly states it asks questions to a knowledge base using IMA's RAG search engine (semantic search + knowledge graph + LLM), and differentiates itself from siblings like list_knowledge_bases_full (listing) and get_note_content (retrieving notes) by focusing on natural-language question answering over full document text.

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 clear context: same Q&A capability as the web interface and typical usage examples. It also instructs using cookie_knowledge_base_id from list_knowledge_bases_full, which is a useful alternative reference. However, it does not explicitly state when not to use this tool vs other retrieval tools.

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

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

With no annotations, the description carries the burden. It communicates the check action, per-file return status, and supported types, implying a read-only operation. But it lacks specifics on duplicate criteria (exact name match, extension handling), folder vs. whole-KB scope, and the exact shape of the returned status, so transparency is only partial.

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 short sentences, front-loaded with purpose and then scope. There is no filler; every clause adds value.

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

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

The core purpose and scope are clear for a simple pre-upload check. However, with no output schema, the description should have detailed the format of the duplicate status and how folder_id affects the check. These gaps make it only minimally 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?

Since schema description coverage is 100%, the baseline is 3. The description adds no extra meaning beyond the schema for folder_id or knowledge_base_id; it only refers to files generically, so it neither compensates nor enhances.

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 explicitly states the tool checks for existing same-name files in the knowledge base before upload and returns duplicate status per file. It clearly scopes to file types (PDF/Word/PPT/Excel/images) and excludes webpages/notes, which distinguishes it from siblings like upload_file and create_note.

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

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

It tells when to use the tool ('before uploading files') and gives an explicit exclusion ('not applicable to web pages and notes'). However, it does not directly name alternative tools, so it stops short of full 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?

No annotations are provided, so the description carries the burden. It adds behavioral context by mentioning content_format=1 and clarifying that folder_name is for the IMA-side folder, not the knowledge base folder. It also signals the follow-up workflow with add_note_to_knowledge_base. However, it omits details about return values, error conditions, or permanence, which a create operation might warrant. Still, it adds value beyond the schema.

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 three short sentences, front-loaded with the primary purpose. It then adds key details about content format, the next-step relationship, and folder semantics. Every sentence carries essential information with no redundancy or fluff.

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 create tool with no output schema, the description covers the core purpose, parameter meaning, and workflow with a sibling tool. It lacks an explicit mention of the return value or response format, which would be useful since no output schema exists. However, given the tool's simplicity and the absence of nested objects, it is reasonably complete. A score of 5 would require explicit return/error handling details.

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?

Both parameters have schema descriptions with 100% coverage, so the baseline is 3. The description adds minimal extra parameter semantics: it repeats the Markdown support already in the schema and echoes the folder distinction. The only unique detail is content_format=1, but that's not a parameter property. Therefore, the description does not significantly enhance parameter understanding beyond what the schema provides.

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 an IMA note' (创建一篇 IMA 笔记) with a specific verb and resource. It also distinguishes itself from sibling tools like add_note_to_knowledge_base by explaining the note can be added to a knowledge base after creation, clarifying its role as the creation step.

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 explicit workflow guidance: 'After creation, you can add the note to a knowledge base via add_note_to_knowledge_base.' This implicitly tells the agent when to use this tool (to create) and when to use the alternative (to add). It also clarifies folder_name applies to IMA notes, not knowledge base folders, preventing misuse. However, it doesn't enumerate all sibling tools or state explicit exclusions, so a 4 rather than 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 provided, the description carries the full burden. It discloses the permission filtering behavior ('当前用户有权限添加内容'), which is valuable context. However, it does not mention pagination behavior, return format, or any side effects, leaving some ambiguity for a list operation.

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 sentences: the first states the core purpose, and the second provides a usage condition. There is zero redundancy or filler; every word contributes to understanding.

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 is a simple list operation with two pagination parameters and no output schema, the description covers purpose and usage context sufficiently. It does not explain return structure, but the simplicity and sibling tools mitigate this gap, making it nearly 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?

The input schema has 100% coverage: both 'limit' and 'cursor' have descriptive text including types, ranges, and defaults. The description adds no additional parameter semantics beyond what the schema already 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 clearly specifies the action ('获取' = get) and resource ('知识库列表' = knowledge base list) with a specific qualifier ('当前用户有权限添加内容' = current user has permission to add content). This distinguishes it from sibling tools like list_knowledge_bases_full, which likely lists all knowledge bases without the add-permission filter.

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 explicitly states when to use this tool: '仅在未指定目标知识库时使用' (use only when the target knowledge base is not specified). This provides a clear contextual condition, though it does not name an alternative tool explicitly, so it falls short of 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 carries the transparency burden. It discloses that URL types return accessible URLs, while note types (media_id starting with note_) automatically fetch and return note_content as plain text. This adds meaningful behavioral detail, though it does not cover edge cases or errors.

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 focused sentences, front-loaded with the core action. Every sentence adds necessary detail; there is no redundancy or filler.

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

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

For a single-parameter tool with no output schema, the description fully explains the expected behavior and output format across media types. It covers the source of the parameter and the conditional return values, making it complete for the tool's complexity.

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 schema only describes media_id as '媒体条目 ID.' The description enriches this by explaining where the ID comes from (ask_knowledge_base references) and that the note_ prefix changes behavior. This adds real semantic value despite the schema's 100% coverage.

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 original content or download links for knowledge base entries. It specifies the input source (media_id from ask_knowledge_base references) and differentiates behavior by media type, distinguishing it from sibling tools like get_note_content.

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 guidance on when to use: pass media_id obtained from ask_knowledge_base's references field. It describes behavior for different media types but does not explicitly contrast with alternatives or state exclusions, so it falls short of 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 are provided, so the description carries the full burden. It discloses that the output is plain text and clarifies the ID mapping, which is useful. However, it does not mention potential errors, authentication requirements, or what happens with invalid IDs. For a simple read tool, this is adequate but not rich.

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

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

The description is two sentences, front-loaded with the main purpose, and every sentence adds value. It avoids redundancy and is 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's simplicity, no output schema, and good sibling context, the description covers the essential aspects: what it does, how to get the ID, and the output format. It could mention error behavior or return details, but for a read tool with clear parameter guidance, it is sufficiently 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?

The schema has 100% parameter coverage, so the baseline is 3. The description adds value by explaining that note_id corresponds to notebook_id from get_media_info or doc_id from search, which is not present in the schema. This semantic enrichment goes beyond the schema.

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

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

The description uses a specific verb '读取' (read) and resource '笔记正文' (note content), making the function clear. It also distinguishes this tool from siblings by stating it is the dedicated interface for reading note original text, and clarifies the ID source relationships with get_media_info and search APIs.

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 clear context on when to use it: read note content, and how to obtain the required note_id (from get_media_info or note search). It does not explicitly state when not to use it or mention alternative tools, but the guidance on ID provenance is valuable.

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 responsibility for disclosing behavior. It only repeats the count limit and folder_id omission already present in the schema, adding no new context about side effects, permissions, error handling, or return values. A mutation tool like this should disclose what happens when URLs are added or if some fail.

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 entire description is one concise sentence that front-loads the primary purpose and follows with a specific usage note. It contains no filler and is directly actionable, earning full marks for efficiency.

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 that this is an import operation with side effects and no annotations or output schema, the description is too sparse. It fails to mention success/failure behavior, permission requirements, whether content is fetched, or any post-add actions. The description covers the 'what' but not the 'how' or 'what to expect.'

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 baseline is 3. The description adds no additional meaning beyond the schema: the 1-10 URL limit and root-directory behavior are already documented in the property descriptions. It does not elaborate on knowledge_base_id auto-resolution or any formatting requirements.

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's purpose: adding web or WeChat article URLs to the knowledge base. It specifies the exact resource (URLs) and action (add to knowledge base), and the 1-10 URL limit distinguishes it from sibling tools like create_note or add_note_to_knowledge_base.

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 stating its core function, but it doesn't explicitly compare against sibling tools or state when to choose this tool over alternatives. It does provide a useful context tip about omitting folder_id for root, but this is more about parameter handling than 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the scope (including shared knowledge bases), the dual ID formats and their usage contexts, the unique entry point status, and the authentication requirement. It does not cover rate limits or error cases, but for a listing tool this is adequate.

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, well-structured sentence that front-loads the main purpose and then efficiently conveys ID format usage, uniqueness, and authentication requirements. Every clause contributes value with no redundancy.

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

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

There is no output schema and no annotations, yet the description provides the essential context: what the list contains, the two ID variants and their intended uses, and the configuration requirement. It does not describe the full response envelope, but for tool selection and invocation it is sufficiently 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?

The input schema already fully describes the single optional parameter (need_folder_number) with its default value, so schema coverage is 100%. The description adds no additional parameter-specific semantics, hence 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 tool retrieves the complete knowledge base list, including subscribed shared bases, and specifies that it returns two ID formats for different downstream tools. It distinguishes itself from siblings by being positioned as the only entry point for knowledge base IDs.

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 explicitly declares '这是获取知识库 ID 的唯一入口' (this is the only entry point for getting knowledge base IDs), and gives direct instructions on which ID format to use with which tool. It also mentions the IMA_COOKIE prerequisite, making it clear when and how to use the 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the internal pipeline: duplicate name check, media creation, COS upload, and knowledge base registration. However, it does not mention outcomes on duplicate names or potential side effects beyond the listed steps, which would be useful.

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 concise, consisting of two sentences. The first sentence states the primary purpose and supported formats, and the second enumerates the internal process steps. No redundant or filler content is present.

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 file upload tool, the description is fairly complete: it covers supported formats and the multi-step backend process. However, it does not specify the behavior when a duplicate file name is detected (e.g., rejection, overwrite, or renaming), leaving a notable gap in edge-case handling. No output schema exists, so return value explanation is not required.

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 already describes all three parameters with 100% coverage. The description adds no additional semantic information about the parameters themselves, such as default behaviors or constraints, 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 clearly states the verb 'upload' and the resource 'local files to knowledge base', with a comprehensive list of supported file formats. This distinguishes it from siblings like import_urls, which handle URLs, and create_note, which creates 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 supported file types imply the intended use case, but there is no explicit statement of when to use this tool versus alternatives. For instance, it does not say 'use import_urls for URLs' or exclude non-file inputs. The context is clear but not explicitly guided.

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