weishengxin

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

With no annotations at all, the description carries the full burden and delivers: it discloses asynchronous background execution, a global single-job constraint, an admission throttle of one new job per 5 seconds, and that accepted/busy/rate_limited are not completion states. This is exactly the non-obvious runtime behavior an agent would otherwise have to discover by failing.

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 English text is dense, front-loaded, and every clause earns its place (submission action, completion caveat, concurrency limit, throttle, retry rule). The full Chinese restatement roughly doubles the length without adding new information for a single-language reader, which is the only waste.

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

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

An output schema exists, so return values need not be explained, and the description covers submission, admission gating, and polling. It leaves unstated where module_id values come from (list_modules) and what the params override object actually supports, which matters for a tool with a free-form params bag.

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 all four parameters are already documented in the schema, including request_id's UUID and no-auto-regeneration rule. The description reinforces request_id idempotency ("retry the same ID") but adds no new syntax, format, or constraint detail beyond what the schema states, so the baseline applies.

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

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

States a concrete verb and resource ("Submit one TSV dataset") plus the mode of execution ("serial background plotting"), which is far more than the bare name conveys. It also names the sibling to use afterwards (get_result), so the agent can place this tool relative to get_result/get_module_schema without opening a schema.

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

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

Gives explicit follow-up routing ("accepted is not completion; poll get_result") and explicit retry semantics for the busy/rate_limited outcomes ("wait and retry the same ID"). It does not cover prerequisites such as obtaining a valid module_id from list_modules or previewing inputs via get_module_demo, so a small gap remains.

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

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

No annotations are supplied, so the description carries the full behavioral burden; it implies a read-only lookup but never says so outright. It discloses nothing about pagination behavior, empty-result handling, or total-count semantics, and does not mention that results come back paged. For a low-risk read tool this is acceptable but leaves real gaps.

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

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

Two short, front-loaded sentences that state the action first and the loading hint second; nothing is wasted. The bilingual duplication lengthens it, but that appears to be a deliberate localization convention rather than 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?

With an output schema present, the description needn't explain return values, and all four parameters are fully documented in the schema with zero required fields. What remains missing is only the when-to-use routing relative to siblings, which is a minor gap for a self-contained lookup tool.

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

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

Schema coverage is 100%, so the schema already documents limit, offset, faq_id, and keyword with matching semantics. The description adds only the framing that keyword and FAQ ID are two lookup modes, without explaining precedence when both are supplied or that all space-separated terms must match.

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: 'Find website usage guidance and common troubleshooting answers' via keyword or FAQ ID. The purpose is unambiguous and distinct from siblings like draw_plot or get_module_schema, though the description never explicitly contrasts itself with them.

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

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

'Load only when needed' gives a weak just-in-time usage hint, implying this is an on-demand lookup rather than something to call preemptively. There is no explicit when-not-to-use guidance and no named alternative among the siblings for related documentation needs.

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

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

With no annotations supplied, the description carries the full burden and does disclose key traits: it is a non-executing read ('no plotting occurs'), and it will not fabricate output ('missing links are not invented'). It does not mention permissions or pagination, but those are less critical for a per-module lookup.

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?

Content is front-loaded in two compact clauses covering purpose then caveats. The bilingual duplication doubles the length, but each language version is tight and carries the same substantive constraints, not 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?

An output schema exists, so return structure need not be described, and the single required parameter is fully documented in the schema. What remains — that this is a read-only preview and that missing entries are not synthesized — is explicitly covered, which is sufficient for a one-parameter lookup tool.

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

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

Schema coverage is 100% and the single module_id parameter is documented in the schema as the exact id from list_modules. The description adds no further meaning about the identifier, so the schema does the work — the baseline of 3 applies.

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

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

States a concrete verb and resource: retrieves configured example image/page links plus a reading guide for a module. The caveats 'no plotting occurs' and 'examples are not results for the user's data' implicitly separate it from draw_plot and get_result, though neither sibling is named outright.

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

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

Usage is implied rather than stated: an agent can infer this is for previewing what a module's output looks like, not for obtaining actual data. There is no explicit 'call this when...' clause and no named alternative to use instead, leaving the choice between get_module_demo and get_result partly to inference.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It signals a read-only retrieval ('Read'), lists the returned content categories, and usefully discloses that the FAQ payload is optional/lazy-loadable, which is a cost signal. However, it doesn't describe whether results are cached, how large a TSV schema payload is, or what happens if the module_id is not found.

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

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

Content is front-loaded with the output payload first, then the usage rule, then the multi-input caveat — a sensible order. It is compact in English, though the fully duplicated Chinese sentence doubles the length without adding information for a single-language reader.

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?

An output schema exists, so the description is not obliged to explain return values, and the tool is a simple two-parameter read. Purpose, pre-draw timing, and the optional FAQ behavior are all covered, which is everything an agent needs to invoke this 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 100%, so the baseline is 3, and the description adds real meaning: it explains that aliases are part of what get_module_schema returns (and that 'inputs' should be used for multi-input modules), and that the full FAQ behind include_details is optional. This gives semantics for both parameters beyond their schema text, though it does not spell out the module_id lookup contract.

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 ('Read') plus an enumerated resource: a module's TSV input format, column meanings, example, parameter aliases, defaults and constraints. It partially differentiates from siblings by noting that the full FAQ (get_faq) is optional, but it never distinguishes itself from get_module_demo or get_result, leaving some ambiguity about which lookup serves which need.

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

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

It gives clear situational guidance: 'Read once before drawing' positions this as a pre-flight step before draw_plot, and 'full FAQ is optional' tells the agent when not to pull in the heavier FAQ content. The instruction 'Use inputs for multi-input modules' is a useful but cryptic hint, and no explicit exclusion against the demo/result siblings is stated.

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

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

With no annotations, the description carries the full burden. It does disclose the key-scoped visibility constraint and implies a read-only lookup, which is useful. However, it says nothing about result retention or expiry, whether a pending request returns a partial response, or any rate/retry limits, leaving meaningful behavioral gaps for a polling 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?

Front-loaded with the action and scope, followed by the usage rule; no filler. The full bilingual restatement roughly doubles length, which is presumably intentional for the audience but is still duplicated content.

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

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

An output schema exists and covers return values, the single parameter is fully documented, and the definition supplies the one rule an agent most needs (query instead of resubmitting). Only the absence of status-transition and result-lifetime context keeps it from being 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?

Schema coverage is 100% and the schema already explains that request_id is the one originally used in draw_plot. The description adds no format, syntax, or validity details beyond that, so the baseline 3 applies.

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

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

States a specific verb (Check) and resource (an existing drawing request's status and file links), plus the access scope ('within the current key's result scope'). This clearly separates it from draw_plot, which submits work rather than reading it back.

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

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

Gives an explicit trigger ('Use after timeouts') and an explicit prohibition ('do not submit a duplicate task'), which effectively routes the agent away from re-calling draw_plot. It does not cover other legitimate cases, such as routine polling for a submitted job, so it stops short of full when/when-not coverage.

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 burden and does disclose a non-obvious behavioral trait: entries with available=false are introduction-only and cannot be executed. It also states that summaries and suitability are returned and that empty keyword triggers browsing, though it never explicitly says the tool is read-only or how results are paged.

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 content is dense and front-loaded, leading with purpose before caveats. The bilingual duplication roughly doubles the length, which is a real cost, but each clause still carries meaning.

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?

An output schema exists, so return values need no explanation, and the description still flags the important available=false executability caveat. For a simple three-parameter listing tool this is close to sufficient; only explicit read-only and pagination framing are missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds one piece of meaning beyond the schema by explaining that an empty keyword browses pages, but limit/offset behavior is left entirely to 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 gives a specific verb and resource ('Discover available bioinformatics plotting modules by purpose or data features'), which is clearly distinct from sibling tools like draw_plot or get_module_schema. It stops short of explicitly naming the siblings an agent should choose between.

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 an implied usage hint that an empty keyword browses all pages and that searchable terms are purposes or data features, but it never states when an agent should call this instead of get_module_schema or draw_plot. The selection logic is left largely to inference.

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