ima-mcp

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

With no annotations, the description carries the full burden. '关联添加' hints that this creates a link/reference rather than copying the note's content, which is useful, but it says nothing about permissions, idempotency (what happens if the note is already linked), or whether the source note itself is modified.

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?

It is a single front-loaded sentence with no filler, which is structurally clean. However, that brevity reflects under-specification rather than efficiency, since key operational detail is simply absent.

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

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

A four-parameter mutation tool with no annotations, no output schema, and zero documented parameters needs considerably more than one sentence. Nothing covers the required title, the optional folder, error/duplicate behavior, or how to find a valid knowledge base.

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

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

Schema description coverage is 0% across four parameters, and the description explains none of them. The mandatory 'title' parameter is especially puzzling for an operation on an existing note, and 'folder_id' is never mentioned, so an agent cannot reason about them from the description.

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 sentence states a specific verb (add/link, 关联添加) and names both the resource being moved (an existing IMA note) and the target (an IMA knowledge base). This distinguishes it reasonably from ima_upload_file_to_knowledge (files vs. existing notes), though it does not explicitly name that sibling to sharpen the contrast.

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

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

There is no statement of when to use this versus alternatives, and notably no reference to ima_get_addable_knowledge_bases, which is the obvious prerequisite for obtaining a valid knowledge_base_id. Preconditions and exclusion cases are left entirely to inference.

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

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

With no annotations, the description must carry the full behavioral burden. It usefully clarifies that content is appended to the end rather than replacing the note, and that the input is Markdown, but it omits permissions, behavior on invalid or missing note_id, return value, and other mutation side effects—significant gaps for a write tool.

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

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

The description is a single front-loaded sentence with no wasted words. Every part of the sentence adds information about the action, target, and content type.

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 are no annotations, no output schema, and no parameter descriptions in the schema. The description is too sparse for a mutation tool: it leaves note-existence requirements, note_id acquisition, append behavior on errors, and return semantics unstated.

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

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

Schema description coverage is 0%, and both parameters are required and undocumented in the schema. The description only implies that note_id identifies an existing note and content is Markdown; it does not explain where to obtain note_id, its format, or any content size/format constraints.

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

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

The description states a specific verb (追加/append) and resource (已有 IMA 笔记末尾/existing IMA note end), plus content type Markdown. It is clear enough to distinguish from reading or creating notes, though it does not explicitly contrast with siblings like ima_create_note or ima_insert_images_to_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?

There is no explicit when-to-use, when-not-to-use, or alternative guidance. The word '已有' implies the note must already exist, but the description does not tell the agent how to choose this over ima_create_note or what to do if the note is missing.

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

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

No annotations exist, so the description carries the full behavioral burden, yet it says nothing about return shape (e.g., which entries matched), whether the check is scoped to a folder or the entire knowledge base, whether it is read-only, or how partial/batch failures behave. Only the one-line purpose is conveyed.

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

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

A single front-loaded sentence with no filler, appropriate for a narrow check tool. It is efficient, though terseness here borders on under-specification given the unannotated 3-parameter schema.

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

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

With no annotations, no output schema, 0% parameter coverage, and a nested batch-style array (up to 2000 items), a one-sentence description is not enough to call the tool confidently. Missing are the batch semantics, folder scoping, and what a 'hit' looks like.

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

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

Schema description coverage is 0% and the schema includes a nested params array of {name, media_type} objects plus an optional folder_id, none of which are explained. The description implies knowledge_base_id and the notion of 'name', but leaves media_type and folder_id semantics entirely undocumented for the agent.

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

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

States a specific verb ('check') plus the exact resource ('same-name entries within the IMA knowledge base') and frames it as a pre-upload step, which the sibling set lacks (siblings include ima_upload_file_to_knowledge and ima_search_knowledge). It does not explicitly contrast itself with ima_search_knowledge, so the boundary is inferred rather than stated.

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?

'Before uploading a file' gives a clear trigger condition for when to call it. There are no exclusions and no named alternative for cases where the caller wants broader search rather than a duplicate check.

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 implies a write/mutation operation but says nothing about side effects, whether a missing folder is auto-created, permission requirements, or what happens on duplicate names (a sibling ima_check_repeated_names hints this matters).

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

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

A single short sentence with the verb and format front-loaded, and no padding. Its problem is under-specification rather than verbosity, which is penalized elsewhere.

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 3-parameter mutation tool with zero annotation coverage, no output schema, and 0% schema descriptions, one sentence is not enough. The agent cannot resolve folder targeting behavior or confirm the tool's relationship to the append/import siblings.

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

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

Schema description coverage is 0% across 3 parameters, and the description only clarifies that 'content' is Markdown. It adds no meaning for folder_id vs folder_name — whether both can be set, which wins, or whether an unknown folder_name is created — which is exactly the ambiguity an agent needs resolved.

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

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

States a specific verb and resource ('create IMA note') with the content format (Markdown), which is more than a tautology. But it never distinguishes itself from the sibling ima_append_note, which is the key ambiguity an agent faces when deciding how to add content to an existing note versus creating a new one.

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

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

There is no statement of when to use this tool versus ima_append_note, ima_import_urls, or ima_add_note_to_knowledge, and no prerequisites or exclusions. The agent must infer usage entirely from the name.

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

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

With no annotations, the description carries the full burden. It discloses one meaningful behavior — results are filtered to destinations the caller can write to — but says nothing about pagination, ordering, result size, permission failures, or whether an empty list is possible. That is thin for a read tool with zero annotation coverage.

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

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

A single short sentence with the scoping qualifier front and center; no filler. It is lean rather than padded, though the brevity comes at the cost of the missing pagination and return-value information noted elsewhere.

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 paginated list tool with no output schema, the definition should at least sketch what each returned entry contains (identifiers, names) and how cursor/limit interact. Neither is covered, so an agent cannot predict the result shape or how to page through it.

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

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

Schema description coverage is 0% and the description never mentions 'limit' (default 50) or 'cursor'. Since both parameters are undocumented in the schema, the description had to compensate for pagination semantics and does not, leaving the agent to guess at page size and continuation behavior.

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

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

The description names a specific verb+resource — list the IMA knowledge bases the current user can add content to — and the qualifier '可添加内容' meaningfully distinguishes it from siblings like ima_search_knowledge_bases or ima_get_knowledge_base. It stops short of explicitly naming those alternatives, but the scope is unambiguous.

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

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

The purpose implies the workflow (find a target knowledge base before calling ima_add_note_to_knowledge or ima_upload_file_to_knowledge), but the description never states when to use this versus the search/get siblings, nor any preconditions. Usage must be inferred.

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

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

No annotations are provided, so the description carries the full burden and it does disclose real behavior: mutations happen (upload), accepted formats are PNG/JPEG/WebP, there is a hard size cap of strictly under 3MiB, and the returned URL is explicitly temporary. It omits lifetime/expiry semantics for the temporary file and whether cleanup is required.

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

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

A single front-loaded sentence that names the action, the input constraints, and the return value with no filler or 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?

For a mutation tool with no annotations and no output schema, the description should explain the returned value more fully. It states a temporary download_url is returned but not how long it stays valid or what an agent should do with it, leaving a notable gap for an upload 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 0% and image_path is completely undocumented in the schema, so the description must compensate. It does add meaningful constraints on what image_path must point to: a local file in one of three formats, under 3MiB. It still doesn't clarify path semantics (absolute vs relative, whether directories or URLs are rejected).

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

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

The description states a specific verb and resource: uploads a local image (PNG/JPEG/WebP, strictly under 3MiB) as an IMA temporary file and returns a temporary download_url. This is clear and even corrects the misleading tool name 'get_image_url', which implies retrieval rather than upload. It does not distinguish itself from siblings such as ima_insert_images_to_note or ima_upload_file_to_knowledge.

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

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

Use is only implied: you need a local image file of the listed formats. The description never says when to choose this over ima_insert_images_to_note or ima_upload_file_to_knowledge, nor does it state prerequisites or what the returned URL is used for.

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

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

No annotations exist, so the description carries the full behavioral burden, and it discloses nothing beyond the purpose sentence. It does not say whether this is read-only (implied by 获取 but unstated), whether missing IDs error or are skipped, what fields are returned, or what the batch size limits are.

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

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

A single short sentence with no filler, and the resource and keying parameter are front-loaded. It is efficient, though the terseness contributes to the gaps in other dimensions.

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

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

The tool has one undocumented parameter, no annotations, and no output schema, so the description is the only source of behavioral and return-value information — and it supplies neither. An agent cannot tell what 'knowledge base information' contains or how a batch lookup behaves.

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

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

Schema description coverage is 0%, so the description must compensate; it does clarify that the 'ids' parameter means knowledge base IDs. It does not, however, resolve the singular/plural mismatch — the description says 'ID' (singular) while the schema requires an array of 1-20 items — nor explain batch semantics or error handling for invalid IDs.

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

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

The description states a specific verb and resource: retrieve IMA knowledge base information by knowledge base ID. An agent can tell what the tool returns at a high level. However, it never distinguishes itself from siblings such as ima_search_knowledge_bases, ima_get_addable_knowledge_bases, or ima_list_knowledge.

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 no when-to-use guidance, no prerequisites, and no alternatives. With four knowledge-base-related siblings, the agent gets no help choosing between a lookup by ID, a search, and an 'addable' listing.

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. '获取' implies a read, but nothing is said about permission requirements, error behavior when media_id is invalid, which media types are covered, or what each of the two return modes actually yields.

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

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

One short sentence with no padding, which is appropriate in size. But it is under-specified rather than concise — the brevity comes at the cost of clarity about the dual return behavior.

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 tool with no annotations, no output schema, and an undocumented parameter, the description does far too little. It should at minimum explain the two return modes, when each occurs, and what media_id refers to.

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 single parameter media_id has 0% schema description coverage and the description never mentions it. There is no indication of where media_id comes from (a knowledge list result?) or what format it takes, so the description fails to compensate for the schema gap.

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

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

The description names a specific verb (获取/get) and resource (知识库媒体/knowledge-base media), so the general action is clear. However, the 'or' construction ('原文访问地址或笔记扩展信息') makes the actual return ambiguous and does not differentiate it from siblings like ima_get_image_url or ima_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?

There is no explicit when-to-use guidance, no prerequisites, and no pointer to alternatives. The two possible outputs implicitly hint at use cases, but the agent must infer which situation selects this tool over ima_get_image_url or ima_get_note_content.

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

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

No annotations exist, so the description must carry the full behavioral load, but it only discloses a default output format ('默认返回纯文本' / returns plain text by default). It says nothing about permissions, behavior with missing/invalid note IDs, or what else can be returned when the format is changed.

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

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

Two short sentences, front-loaded with the purpose and then the default behavior — no filler. It is efficient, though arguably too terse for a tool with an unexplained numeric parameter.

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

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

With no annotations, no output schema, and 0% schema description coverage on two parameters, the description should explain both the retrieval semantics and the format option. It covers only the plain-text default, leaving the format parameter's value space and the returned content shape undocumented.

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

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

Schema description coverage is 0%, so the description should compensate, yet note_id is not explained at all and target_content_format's numeric values (0 = ? presumably plain text, others = ?) are never enumerated. The phrase '默认返回纯文本' only loosely hints that the numeric parameter controls format, leaving an agent unable to choose a non-default value safely.

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

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

The description states a specific verb and resource ('获取 IMA 笔记内容' / get the content of an IMA note), which clearly sets it apart from retrieval-adjacent siblings such as ima_search_notes or ima_list_notes that return lists rather than content. It does not explicitly name those siblings, so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus ima_search_notes, ima_list_notes, or ima_get_image_url, and no prerequisites (e.g., that the note ID must come first). The only usage hint is the default behavior note, which is not a selection criterion.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does add one genuinely useful API constraint (folder_id is required by the interface; pass knowledge_base_id to target the root), but it says nothing about deduplication, whether import is synchronous, permission requirements, or partial-failure behavior for a batch write.

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, front-loaded with purpose and followed immediately by the one non-obvious invocation rule. No filler or restatement of the name.

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

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

With three parameters, no output schema, and no annotations, the description covers purpose and the folder_id quirk but omits what happens on success/failure, whether results are immediate, and how duplicate URLs are handled. Adequate to call correctly, not complete enough to predict behavior.

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

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

Schema coverage is 0%, so the description must compensate. It explains folder_id's optionality and the root-directory workaround involving knowledge_base_id, and it constrains urls to webpage/WeChat article links — good coverage of two of three parameters. It never mentions the 10-URL batch ceiling or URL format expectations, leaving gaps.

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

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

States a specific verb (导入/import) and resource (webpage or WeChat article URLs) into a named target (IMA 知识库). The resource type (URLs) implicitly separates it from ima_upload_file_to_knowledge and ima_add_note_to_knowledge, but no sibling is named explicitly.

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

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

Usage is only implied by the resource type — an agent can infer this is the tool for URL-based ingestion versus file upload or note creation. The only conditional guidance given concerns folder_id placement, not when to choose this tool over its siblings.

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

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

With no annotations, the description carries the full burden and does so well: it discloses accepted image sources, format limits (PNG/JPEG/WebP), a strict <3MiB size cap, batching semantics (text merged into one batch, one batch per image, ordered append), and fail-fast behavior on error. It omits auth/permission requirements and what a partial failure leaves behind.

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

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

Front-loaded with the action and resource, then packed with the operational constraints an agent needs (formats, size cap, batching order, dry_run) in a few dense clauses with no filler.

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

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

For a mutation tool with no annotations and no output schema, the description covers the critical write behavior, image constraints, and failure mode well. The unexplained file_path parameter and the absence of any statement about what a successful or partially failed call returns leave a real gap.

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

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

Schema description coverage is 0%, so the description is the only source of parameter meaning. It explains content (Markdown), dry_run (batch preview), and implies note_id, but file_path is never mentioned at all — an agent cannot tell whether it is an alternative to content, a supplementary upload path, or something else, which is an invocation hazard for this tool.

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

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

The description gives a specific verb and resource ('向 IMA 笔记末尾追加 Markdown 内容') and adds the distinguishing capability of auto-embedding referenced images. It implicitly separates this tool from the plain ima_append_note sibling, but never names that sibling or explicitly contrasts with it.

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

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

Usage context is only implied: it applies when the Markdown content references images that need embedding. There is no explicit statement of when to prefer this over ima_append_note, nor any prerequisite or exclusion guidance, leaving the agent to infer the choice.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states that folder_id can enter a folder. It does not explain pagination behavior, result ordering, permissions, or return shape, even though limit and cursor parameters strongly imply a paginated list.

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

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

The description is a single short sentence with no wasted words and front-loads the core browsing action. However, its brevity reflects 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?

For a paginated list tool with no annotations, no output schema, and zero schema parameter documentation, this description is too thin. It should at least clarify the role of knowledge_base_id, limit, and cursor, and how browsing relates to sibling search tools.

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

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

Schema description coverage is 0%, so all four parameters are undocumented in the schema. The description explains only folder_id, leaving knowledge_base_id, limit, and cursor with no meaning beyond their names.

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 verb and resource (浏览知识库内容) and adds the specific folder navigation behavior. However, it does not distinguish this from the sibling ima_search_knowledge or ima_get_knowledge_base, so an agent cannot tell from the text alone when this browse action is preferred.

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

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

No explicit when-to-use guidance is given, nor are alternatives such as ima_search_knowledge mentioned. Browsing is only implied by the word 浏览, leaving the agent to infer the use case.

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

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

With no annotations, the description must carry the full behavioral burden, but it only restates the purpose. It says nothing about pagination behavior, ordering, permissions, or whether results are truncated by limit, all of which matter for a paginated list tool.

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

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

It is a single front-loaded sentence with no filler, but the brevity reflects under-specification rather than economy. The one line does not earn its place as a complete definition.

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 three-parameter paginated list tool with no annotations, no output schema, and no parameter documentation, the description is far too thin. An agent cannot determine how to page through results or what version controls.

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

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

Schema description coverage is 0% and the description offers no explanation of limit, cursor, or version. The cursor's string-typed default of "0" and the meaning of version are completely undocumented anywhere.

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

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

The description names a specific verb and resource (list IMA notebooks), which is enough for an agent to know what it does. It does not distinguish itself from sibling list/search tools (ima_list_notes, ima_search_notes, ima_list_knowledge), so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus the many sibling listing/search tools, and no prerequisites or exclusions are stated. The agent must infer usage entirely from the name.

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

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

No annotations are provided, so the description carries the full behavioral burden. It only discloses that an empty folder_id means all notes; it says nothing about pagination via limit/cursor, default sort order, permissions, or what the response contains, which are important for a list operation with four parameters.

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 with zero waste and is front-loaded with the core action and scope. Every sentence earns its place, though the overall definition remains under-specified in other dimensions.

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 four undocumented parameters, no annotations, and no output schema, the description is too thin for correct invocation. It omits essential details such as pagination behavior, sort semantics, and return shape, so an agent would have to guess how to use limit, cursor, and sort_type.

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

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

Schema description coverage is 0%, so the description must compensate for all four parameters. It adds meaning only for folder_id (empty means all notes); limit, cursor, and sort_type receive no explanation in either the schema or the description, leaving most parameters semantically opaque.

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

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

The description states a specific verb and resource: '列出 IMA 笔记' (list IMA notes), and adds scope with 'folder_id 为空时列出全部笔记' (when folder_id is empty, list all notes). It is clear what the tool does, but it does not distinguish itself from the sibling ima_search_notes, which is the likely alternative for finding 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 implies usage: use it to list notes, optionally scoped by folder_id, and leave folder_id empty to list all notes. However, it gives no explicit guidance on when to use this tool versus ima_search_notes, nor any exclusions or prerequisites.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it does not say whether arbitrary HTTP verbs/mutations are possible, what permissions are required, whether the call is destructive or reversible, how errors surface, or what rate limits apply. For a raw pass-through that can reach any unwrapped endpoint, that is a significant gap; the only behavioral hint is 'raw/direct'.

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

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

A single short sentence with the core idea front-loaded and no filler. It is efficient, though its brevity is partly the cause of the disclosure gaps scored elsewhere.

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 nested-object, raw-API escape hatch with no annotations and no output schema, the agent needs at least a path-format example, allowed methods, and expected request/response shape. None of that is present, leaving an agent unable to construct a correct call from the definition alone.

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

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

Schema description coverage is 0%, so the description must explain both parameters and does not. It never says whether api_path is relative to which base/version, whether it needs a leading slash or query string, or how the nested 'body' object is mapped (JSON payload vs query params for GET-style paths).

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

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

States a specific action: calling an IMA OpenAPI relative path directly, framed as the escape hatch for endpoints that have no dedicated wrapper. Against a sibling list that is entirely composed of named, purpose-built wrappers, an agent can tell this is the generic fallback rather than a task-specific tool. It stops short of naming what kinds of paths are valid, which keeps it from a 5.

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

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

The phrase '用于未封装的新接口' (for new/unwrapped interfaces) implies the selection condition: use this only when no dedicated sibling tool covers the endpoint. But it never explicitly says 'prefer the named tools first' nor lists any exclusions, and gives no prerequisites such as auth or path format requirements.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: not that the operation is read-only, not the result format (note hits vs. files), and not that results are paginated. A bare 'search' with zero annotation coverage leaves the agent guessing about safety and return shape.

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 definition is a single short, front-loaded sentence with no filler, so it is not verbose. But its brevity is under-specification rather than economy — the one sentence cannot support a three-parameter, unannotated search tool.

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

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

With no annotations, no output schema, and 0% schema coverage on three parameters, the description is the only source of behavioral information and provides almost none. It omits pagination via cursor, result content, and prerequisites for obtaining the knowledge base ID, all of which an agent needs to call it correctly.

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

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

Schema description coverage is 0%, so all three parameters depend on the description for meaning, yet it only vaguely gestures at knowledge_base_id ('指定 IMA 知识库') and query ('搜索内容'). The cursor parameter — the mechanism for paging through results — is never mentioned at all, leaving a third of the inputs undocumented in both schema and description.

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 pairs a specific verb (搜索/search) with a specific resource scope — content inside a designated IMA knowledge base — which separates it from ima_search_notes and ima_search_knowledge_bases at a coarse level. However, it never explicitly names those siblings or states what kind of content (notes, files, media) is searched, so differentiation is only implied.

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

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

There is no explicit when-to-use, when-not-to-use, or prerequisite guidance. An agent must infer from the name and the sibling list whether to use this versus ima_search_notes or ima_search_knowledge_bases, and nothing indicates whether a knowledge_base_id must be discovered first via ima_list_knowledge or ima_search_knowledge_bases.

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 bears the full disclosure burden. It reveals the dual-mode behavior (empty query → default listing), which is genuinely useful, but says nothing about read-only nature, pagination behavior despite a cursor parameter, result size, or permissions.

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 no filler, and the useful empty-query behavior is stated up front. It is efficient but under-informative rather than bloated.

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

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

With no annotations, no output schema, zero schema coverage, and a crowded sibling namespace, the description would need to clarify scope, pagination, and result shape. It covers only the empty-query case, leaving an agent unable to confidently distinguish or invoke this tool correctly.

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

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

Schema description coverage is 0% and the schema has three parameters (query, limit, cursor) with no descriptions. The description explains query's empty-string semantics, but limit and cursor — including why a cursor exists if this is a simple list — are left entirely undocumented in both places.

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

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

The description states a verb+resource ('搜索或列出 IMA 知识库'), but conflates two operations (search vs list) into one tool and never disambiguates against close siblings like ima_search_knowledge, ima_list_knowledge, or ima_get_knowledge_base. An agent cannot tell from the text whether this targets knowledge-base containers or their 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?

The only usage hint is 'query 为空时按接口返回默认列表' (empty query returns a default list). There is no guidance on when to choose this over the many sibling list/search tools, and no prerequisites or exclusions.

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

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

With no annotations at all, the description carries the full behavioral burden, and it discloses almost nothing: no mention of pagination behavior (the start/end params), result caps, matching semantics (substring vs fuzzy), or permissions. Only the title-vs-body distinction adds context, which is largely restating a schema enum.

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

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

A single compact sentence with the verb and scope front-loaded and zero filler. It is efficient, though its brevity is part of the under-specification problem rather than a virtue in itself.

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

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

For a 4-parameter search tool with no annotations, no output schema, and no documented parameters, the description should explain pagination and result shape. It leaves the agent to guess how start/end work and what a result contains.

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

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

Schema description coverage is 0% across 4 parameters. The description covers the search_type concept in prose (title or body), but says nothing about the query string format or the start/end pagination parameters, which an agent must infer from bare names and defaults.

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

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

States a specific verb and resource ("搜索 IMA 笔记" / search IMA notes) and notes the two searchable scopes (title or body). It is clearly distinguishable from list-style siblings like ima_list_notes, though it never names an alternative explicitly.

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

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

The description only implies "use this to search notes"; it gives no conditions for choosing this over ima_list_notes or ima_get_note_content, and no prerequisites, rate limits, or exclusions.

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

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

With no annotations, the description carries the full burden, and it does disclose that this is a multi-stage mutating pipeline (media creation, COS upload, knowledge insertion) with a dedup check. However, it says nothing about required auth/permissions, what happens on a duplicate hit, whether partial failures leave orphaned media, or how long the default 300s timeout behaves.

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

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

A single short line, front-loaded with the action and resource, with the pipeline stages in a compact colon-list. No waste, though the terseness is partly the cause of the specification gaps.

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

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

For a 7-parameter mutating upload tool with no annotations and no output schema, the description is far too thin: it explains neither parameter behaviors nor the failure/duplicate semantics an agent needs before committing a file to a knowledge base.

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

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

Schema coverage is 0%, so all 7 parameters (file_path, knowledge_base_id, folder_id, password, content_type, timeout_ms, fail_if_repeated) are undocumented. The description's mention of 查重 loosely hints at fail_if_repeated but explains none of the other parameters, leaving a severe gap for an upload tool with a password field and a timeout.

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

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

States a specific verb and resource (upload local file to IMA knowledge base) and enumerates the pipeline stages (precheck, dedup, create media, COS upload, add knowledge). It distinguishes itself implicitly from ima_import_urls by specifying a *local* file, but never names that sibling explicitly.

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

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

The phrase '上传本地文件' implies this is the route for local files rather than URLs or existing notes, but there is no explicit when-to-use/when-not statement and no mention of the obvious alternative ima_import_urls or ima_add_note_to_knowledge. Usage must be inferred.

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