BioAI 日知

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

Annotations already cover read-only, idempotent, non-destructive behavior, but the description adds real value beyond them: the result is capped at 20 events, and official-website fields in directory metadata are explicitly flagged as not automatically verified sources — a meaningful trust caveat for consumers of this data.

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 dense sentences; the return contents are front-loaded and the verification caveat follows. Every clause carries information, though the second sentence is a caution that could sit in a general notice rather than this one tool's description.

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, return-shape detail is unnecessary, and annotations cover the safety profile. The description supplies the bounded-result and provenance caveats an agent needs; only per-parameter guidance is missing.

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

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

Schema coverage is 50%: only 'language' is documented, while 'slug' carries just a pattern with no prose. The description adds nothing about either parameter — not the slug format, not what omitting language yields — so it fails to compensate for the coverage 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?

States a specific verb and resource ('Read one company directory profile') and enumerates what the profile carries: name/alias provenance, verification status, and up to 20 published events. The word 'one' implicitly distinguishes it from search_companies, though no sibling is named explicitly.

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

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

The singular 'one company profile' implies this is the detail-view tool to use after a search, but the description never states when to prefer it, nor when not to use it, nor names search_companies as the alternative for discovery.

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?

Annotations already declare readOnly/idempotent/openWorld=false, so the bar is lower. The description adds genuinely new behavior: a 6000-character return cap, the exact payload contents (source text, URLs, status, provenance), and the important scope constraint that it never fetches arbitrary external URLs, which reinforces the openWorldHint=false annotation.

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

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

Three tight sentences: identity/mode first, return payload second, the critical negative constraint last. No filler and every clause carries information.

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

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

An output schema exists so return values need not be detailed, yet the description still summarizes them usefully. Combined with annotations covering the safety profile, an agent has everything needed 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 coverage is only 33%, so the description must compensate. It explains the record-vs-event semantics of kind and the UUID identity of id, but the language parameter and its 'omit for legacy copy' behavior are documented only in the schema, leaving a 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+resource ('Read one stored source record by UUID') and clarifies the dual mode via kind='event'. It implicitly distinguishes itself from list-style siblings like search_resources by emphasizing 'one', but never names an alternative tool.

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

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

Usage is implied by the kind='event' branch and the UUID requirement, but the description never states when to prefer this tool over search_resources or get_source_status, nor any prerequisite for having a valid id. Adequate but with clear routing gaps.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value: result pagination ("bounded page"), a field-level caveat that last_success_at means successful collection rather than last update, and an explicit scope exclusion for credentials, configuration, and internal error logs.

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

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

Three sentences, front-loaded with what is returned, then a semantic caveat, then a scope exclusion — each sentence earns its place. Slightly dense phrasing ("source verification/collection status") costs it the top mark.

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-value explanation is unnecessary, and the data-scope and last_success_at caveats are genuinely complete. But with five optional parameters at 20% coverage, an agent still lacks guidance on query/company/language usage, leaving 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 only 20% (language alone), so the description must carry the other four parameters. It never mentions query, company, offset, or limit, and only gestures at pagination via "bounded page" without explaining ranges or filtering 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 uses a specific verb ("Inspect") and a concrete resource ("source verification/collection status and the current topic definitions"), so an agent knows exactly what comes back. It does not, however, distinguish itself from siblings like get_resource or search_resources, 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 statement of when to call this versus get_resource/search_resources, no prerequisites, and no exclusions. Usage must be inferred from the phrase "publicly visible," which is not enough routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and repeatability are covered. The description adds a genuine trust caveat (topic matches are discovery aids, not a census or verification certificate) and implies history toggles historical names, but says nothing about pagination behavior despite limit/offset.

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, no padding, with the core purpose front-loaded. The second sentence is dense but earns its place by setting accuracy expectations.

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 described, and annotations cover the safety profile. For an 8-parameter, zero-required search tool with very low schema coverage, the description covers the meaningful facets; only pagination semantics are left implicit.

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 only 13% (just 'language'), so the description must carry the load, and it does map facets to parameters: name search (query), historical names (history), topic, track and region. It leaves limit, offset and language unaddressed, but the uncovered ones are largely self-describing.

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 ('Find') and resource ('directory companies') with the facets searched (current or historical name, topic, track, region). It is clearly distinguished from get_company and search_resources by the word 'directory companies', though it never names a 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?

There is no when-to-use/when-not-to-use guidance and no routing to alternatives such as get_company for details or search_resources for other artifact types. The closing caveat limits trust in topic matches but is a coverage disclaimer, not usage 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds genuine value by disclosing a scope/trust caveat (sources are not asserted to be editor-reviewed) and the days=0 special case, but says nothing about pagination, result caps, or rate limits.

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

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

Three tight sentences with the core purpose front-loaded and the caveat placed last. Every sentence carries weight, though the editorial caveat could be trimmed slightly.

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 described. However, for a 9-parameter tool with only 11% schema coverage, the description leaves too many parameters and no pagination/filtering guidance for a fully complete picture.

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 only 11%, so the description must compensate. It maps keywords to query, topic to the topic enum, academic/industry category to academic, and time window to days (with the days=0 edge case), but leaves limit, offset, company, language, and journal_tier entirely unaddressed.

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 ('search') and resource ('stored public research abstracts and industry source records'), and clarifies the tool does not claim sources are editor-reviewed. It is clearly distinguishable from get_resource and search_companies by resource type, though it doesn't name those siblings 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 implied by the search-verb framing, but there is no explicit when-to-use guidance or routing against alternatives like get_resource or get_source_status. The one hint, 'days=0 searches all stored dates,' is a parameter detail rather than selection guidance.

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