ISHOB Knowledge Archive

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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds real behavioral context beyond them: robots.txt compliance, a no-retention/no-redistribution policy, and a cost of $0.0005 via x402. Cost and legal constraints are exactly the kind of traits an agent can't get from the annotation block, though failure/rate-limit behavior is still unstated.

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 short, front-loaded sentences: what it does, what it returns, then the legal and cost caveats. No filler and each sentence carries distinct 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?

With no output schema, the description correctly discloses the return format ('clean Markdown'), and it covers cost, compliance, and retention. For a single-parameter read tool with supporting annotations, nothing essential to correct invocation 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?

There is a single url parameter with 100% schema description coverage ('Public http(s) URL'), so the schema already carries the meaning. The description's 'public' reinforces the constraint but adds no syntax or format detail, making the baseline 3 appropriate.

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

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

The description gives a specific verb+resource: it fetches a live public web page and returns clean Markdown. The scope word 'live' and 'public' help distinguish it from archive-oriented siblings, but it never explicitly names or contrasts with get_document, get_fulltext, or search_archive, so an agent must infer the boundary itself.

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 implies when to use it (fetching a live public page) and states two preconditions ('public', 'robots.txt respected'), but offers no explicit when-not guidance or named alternatives among the siblings. Usage is inferable rather than 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds two useful facts not in the structured data: the fixed page size of 100 resources and that access is free (no cost/quota concern). It says nothing about pagination termination or total-count behavior, so it remains mid-range.

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 compact sentence with the core resource and scoping facts front-loaded; nothing is redundant. The trailing fragment 'Free.' is slightly clipped but still earns its place as cost 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?

With no output schema, no parameter documentation, and no annotation beyond the safety hints, the description leaves key call-time questions unanswered: how to detect the last page, whether results are ordered, and what a 'resource' entry contains. For a browsing tool with pagination semantics, this is under-specified.

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 carry the burden for both parameters. It only implies a topic filter and a page-based read ('per page'); it never names the page parameter, its zero-based default, or the slug pattern the topic string must match, which is exactly the kind of constraint the pattern regex encodes but cannot explain.

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 (browse) and resource (the catalog) plus two scoping facts: page size of 100 resources and optional topic filtering. However, it does not distinguish this from sibling listing tools like list_topics or search_specs, leaving the agent to infer the difference from names alone.

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 mentions that topic filtering is optional but gives no guidance on when to choose this over list_topics or search_specs/search_archive. No prerequisites, no when-not-to-use, no alternative named.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuine non-schema behavior: this call is paid ($0.001 via x402), which an agent needs to know before invoking. It stops short of noting rate limits or failure modes on payment.

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 with no waste; the returned content is front-loaded and the cost caveat follows immediately. Nothing could be removed without losing 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?

For a single-parameter, read-only paid lookup with no output schema, the description covers both what comes back and the payment requirement. It could add a sentence on when to prefer get_fulltext, but nothing essential 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?

Only one parameter, and schema description coverage is 100%, so the schema fully documents the id format and its source tools. The description adds nothing beyond that, which is the expected baseline when the schema does the work.

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?

Names a specific resource ('one resource') and enumerates the returned content: metadata, abstract, license, attribution. This differentiates it from siblings like get_fulltext and get_references. The verb is only implied ('Record ... for'), which keeps it 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?

No when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The id provenance (search_archive / get_catalog_page) appears only in the schema, not the description, so routing context is inferred rather than 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?

Annotations only cover read-only and closed-world semantics; the description adds genuinely new behavior: the result is section-structured, includes license metadata, and requires payment of $0.01 via x402. The payment requirement is the kind of trait structured fields do not express. It stops short of describing failure/rate-limit behavior.

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

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

One compact sentence, front-loaded with what is returned, then license and cost. Every clause carries information and nothing is padded.

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

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

For a single-parameter, no-output-schema tool, the description covers output shape (sections, license) and the notable payment constraint. Missing only an explicit pointer to the id source workflow, which the schema partially supplies.

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 id parameter already documents its source (search_archive / get_catalog_page) and format example. The description adds no parameter-level detail, 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 resource being retrieved ('one resource') and characterizes the payload ('structured full text (sections), with license'), which separates it from a plain text or reference fetch. It does not explicitly contrast with siblings like get_document or get_references, so an agent must infer the distinction.

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 paid/cost note ('Paid ($0.01, x402)') flags a meaningful usage consideration an agent should weigh before calling. However, there is no statement of when to prefer this over get_document, get_references, or extract_webpage, so routing is left 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context by disclosing a per-call charge and the x402 payment mechanism, but it never explains what x402 entails or what happens on payment failure, so the disclosure is a fragment rather than full guidance.

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 cost. Nothing is padded, though 'Paid ($0.002, x402)' is compressed to the point of being cryptic rather than purely economical.

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

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

With no output schema, the description must convey the return shape, and 'parsed reference list' is only a partial answer — no indication of fields, ordering, or whether references are limited/paginated. For a paid tool whose result is unstructured to the agent, this leaves real gaps.

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

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

Schema description coverage is 100% and the single 'id' parameter is already documented with its source tools and an example. The description adds nothing about the parameter, so the baseline 3 for schema-covered parameters 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?

Names a specific resource ('reference list of one resource') and the modifier 'Parsed' signals the output is structured extraction rather than raw text, distinguishing it from get_fulltext or get_document. It stops short of explicitly contrasting itself with those siblings, so a 4 rather than 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 when-to-use guidance, no prerequisite (e.g. that the id comes from search_archive/get_catalog_page, which only appears in the schema), and no mention of alternatives such as get_fulltext for the body text. The only operational note is that the call costs money.

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=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by noting the counts are 'live' (current data, not cached) and that the call is free, but it says nothing about result size, ordering, or pagination.

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, zero filler, with the resource description front-loaded ahead of the cost note. Nothing could be removed without losing 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?

For a zero-parameter, read-only list tool with no output schema, the description covers what is returned (topics plus counts) and the cost. Minor gaps around ordering/truncation of results remain but are not critical for invocation.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 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 (List) and resource (knowledge topics) plus a scope qualifier (live resource counts), so an agent knows exactly what it gets back. It does not, however, distinguish itself from any sibling tool by name or category.

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 trailing 'Free' hints at a cost-free discovery call, but there is no statement of when to call this versus search_specs, query_specs, or the get_* siblings. An agent must infer that this is a browsing/discovery entry point.

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 (readOnlyHint=true, openWorldHint=false), but the description adds a genuinely valuable behavioral trait: the call is paid ($0.001, x402). Cost/payment requirements are exactly the kind of context annotations do not convey, so this earns meaningful credit.

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 tight sentences with no filler, and the primary purpose is front-loaded before the cost note. Efficient and appropriately sized for the amount of 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?

With 7 parameters, 57% coverage, and no output schema, the definition is only minimally complete. It does not describe the result shape beyond 'source document and license', does not explain the limit/pagination behavior, and provides no guidance on how the filters combine.

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 57%. The description touches the main filters (quantity, family, unit, value range, source document words) and roughly mirrors the schema's own examples, but it adds no format or semantic detail beyond the schema and omits limit entirely, so it hovers at the baseline.

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

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

The description states a specific resource (a structured specification table) and enumerates the filter dimensions (quantity, unit family, unit/value range) plus returning source document and license. It is clear what the tool does, but it never distinguishes itself from the sibling search_specs, so an agent cannot tell the two apart without opening both schemas.

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 guidance, no statement of prerequisites, and no mention of the sibling search_specs as an alternative. The only routing-adjacent information is the paid price, which tells the agent nothing about when this tool is the right 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 readOnlyHint=true and openWorldHint=false already declaring a safe, closed-corpus read, the description adds 'All words must match' (AND semantics) and the 'Free' cost note. It says nothing about result ordering, pagination, or what a hit contains, so it adds only modest context beyond the annotations.

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 short clauses, front-loaded with the action and resource, zero filler. Every phrase 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?

For a 7-parameter search tool with no output schema, the definition omits result shape, pagination behavior and the meaning of the filter parameters. It is minimally usable for the required query parameter but incomplete for the optional filters.

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 43%, so limit, license, year_from and year_to carry no documentation anywhere. The description partially compensates by clarifying that the query matches titles, keywords and authors, but adds nothing about the filter parameters or their interaction.

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 ('Search the ISHOB archive') and narrows scope to titles, keywords and authors. However, it never distinguishes itself from the sibling search_specs, so an agent must infer which search surface applies.

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?

'Free' hints at a cost consideration but gives no when-to-use guidance, no exclusions, and no pointer to the obvious alternative search_specs. The agent is left to guess which search tool to pick.

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 readOnlyHint and openWorldHint already declared, the description adds genuinely new operational context: the call is paid at $0.001 via x402, and numeric-constraint tokens in the query are matched rather than treated as literal text. Pricing and matching semantics are exactly the kind of thing structured fields cannot convey. It stops short of describing result ordering, pagination, or failure behavior on an unpayable request.

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 short sentences, front-loaded with what the search covers before the query-syntax note and the cost note. No filler or redundancy. It loses a point only because the parenthetical field list is slightly dense while the more decision-relevant information (pricing, sibling choice) is buried at the end.

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 five-parameter search tool with no output schema, the description covers purpose, matching behavior, and cost, which is a reasonable core. But it leaves four of five parameters unexplained and gives no basis for choosing against query_specs or search_archive, both of which matter for correct invocation in this sibling set.

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% (just the query property), so the description must carry the other four parameters, and it does not. topic, category, limit, and year_from are never mentioned, and their names alone do not reveal the expected forms (topic slug pattern, category enum, year bounds). The description's "50 Nm" example restates the query field's own schema description rather than compensating for the 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: full-text search over abstracts and full texts, returning extracted technical specifications with values, ranges, tolerances and units. That is concrete enough to distinguish it from document-fetching siblings like get_document or get_fulltext. However, it never distinguishes itself from the sibling query_specs, which on name alone reads as the closest alternative, so an agent cannot confidently choose between the two.

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 or when-not-to-use guidance, and no alternative is named despite an eight-tool sibling set containing both query_specs and search_archive. The only usage-adjacent content is a behavioral note that numeric constraints like "50 Nm" are matched, which describes how the query works rather than when to pick this tool.

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