Agent Reliability

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

The description goes beyond the readOnly/idempotent annotations by explaining refusal semantics in detail: 'answered is false and abstention_reason plus missing_topics say what was not covered — a refusal is a real result here, not an error.' It also discloses that the tool returns only claims bearing on the question with sources and editorial confidence, which is useful behavioral context.

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, all high-value: the core action, the return format, and routing to search. There is no redundant filler, and the most important scoping information is front-loaded.

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

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

For a single-parameter tool with an output schema, the description is complete. It covers the key edge case (corpus cannot answer), names the output fields for that case, and provides sibling differentiation. Nothing essential is missing for correct 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?

Schema coverage is 100% and the parameter description already states 'The question to answer, in the words the user asked it.' The tool description reinforces the verbatim natural-language requirement ('when the user asked a question in words') but does not add material new semantics beyond the schema, so 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?

The description opens with a specific verb and resource: 'Answer a question from the corpus, or refuse.' It clearly distinguishes itself from the sibling search tool by stating 'Use this when the user asked a question in words; use search when you want to see the candidates yourself.' This differentiates it without ambiguity.

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

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

The description explicitly states when to use the tool and names the alternative: 'Use this when the user asked a question in words; use search when you want to see the candidates yourself.' It also clarifies that a refusal is a legitimate outcome, preventing the agent from misinterpreting abstention as an error.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond annotations: unknown ids land in a 'missing' field with a near-miss suggestion, the rest are still compared, and missing attributes render as null.

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 dense sentences with no filler. The purpose is front-loaded, the usage trigger is in the second sentence, and the error behavior is in the third. Every sentence earns its place.

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

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

Given the simple parameter schema, rich annotations, and presence of an output schema, the description is complete. It covers what the tool returns, when to use it, how to prepare inputs, and how unknown ids are handled.

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 parameter is already well documented. The description reinforces the workflow by saying to resolve names first via search or get_topic and then pass the ids, adding practical context beyond the schema.

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

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

The description names a specific verb ('compare') and resource ('knowledge objects side by side'), then enumerates what the output contains. It also distinguishes the tool from siblings by giving explicit question shapes ('X vs Y', 'is X the same as Y').

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 explicit when-to-use triggers and a clear prerequisite: search or get_topic first if only names are available, then pass ids. It does not explicitly name when-not alternatives such as get_related, but the context is clear enough for an agent to route correctly.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond that: an unknown id is not a dead end, and the answer names near-miss ids to retry. This is meaningful supplementary information.

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, each earning its place: the operation and result, the precondition for calling, and the failure-mode behavior. It is front-loaded with the core purpose and contains 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 single-parameter tool with an output schema and strong annotations, the description is nearly complete. It covers what is returned, when to call it, and what happens with an unknown id. The only minor gap is the omitted get_related source in the usage sentence, but the schema compensates for that.

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 schema already explains that id comes from search, answer, get_topic, or get_related and is the last segment of the canonical URL. The tool description reinforces the source of the id but does not add meaningful parameter semantics beyond the schema.

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

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

The description uses a specific verb ('Fetch'), names a precise resource ('one knowledge object by id'), and states the included content ('its claims and the sources each claim cites'). This clearly distinguishes it from sibling tools like get_latest, get_overview, and get_sources.

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 explicit invocation timing: use it once search, answer, or get_topic has produced an id. It does not explicitly contrast against sibling tools, and it omits get_related which the schema mentions as an id source, but the core usage context is clear.

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 read-only, idempotent, non-destructive behavior; the description adds useful behavioral context beyond them by stating that ranking is by verification date and that topic is deliberately ignored. It does not clutter with unnecessary return details because an output schema exists.

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, each earning its place: the core definition is front-loaded, the practical use cases follow, and the distinction from search/get_topic closes it. There is no filler or repetition.

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-optional-parameter read-only tool with an output schema, the description fully equips an agent: what is returned, what ordering is used, when to use it, and which sibling tools to prefer instead. Nothing critical 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?

The only parameter (limit) is fully documented in the schema with default, range, and ordering semantics ('newest verification first'), so the description carries no additional parameter burden. Per the high schema-coverage baseline, a 3 is appropriate.

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

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

The description names a concrete resource ('knowledge objects'), specifies the ordering ('most recently verified'), and immediately distinguishes itself from relevance-based siblings by noting 'it ignores your topic entirely'. This lets an agent know exactly what get_latest returns and how it differs from search/get_topic.

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 explicit use cases ('judge how current the corpus is' or 'see what changed since you last read it') and an explicit exclusion/alternative: use search or get_topic when topical relevance, not recency, is desired. No ambiguity remains about when to choose this tool.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context about the tool's role as a preliminary orientation step and discloses the nature of its outputs (counts, tags, freshness), which goes beyond the annotations without contradicting them.

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 fluff. The first sentence front-loads the tool's content and scope, and the second immediately gives actionable usage guidance. Every word earns its place.

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 parameterless overview tool with a rich output schema and safety-oriented annotations, the description fully covers purpose, usage, and context. Nothing essential is missing for an agent to decide when to invoke 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?

The input schema has zero parameters, so parameter semantics are not applicable. Per the rubric, a 0-parameter tool receives a baseline of 4; the description appropriately focuses on the tool's output rather than parameters.

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

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

The description clearly states the resource ('Corpus overview') and the specific content returned: counts by type, published tags, freshness. It distinguishes itself from siblings by positioning this as the first-stop tool for assessing corpus knowledge, which separates it from query tools like answer or search.

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 explicit when-to-use guidance: 'Use this first when you land here and do not yet know whether this corpus can answer your question.' It implies when not to use it (when you already know the corpus can answer), but it does not explicitly name alternatives or exclusion conditions, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds crucial behavioral details beyond annotations: pagination limits (25 default, 200 max), response budget (64 KB), and the semantics of the cursor (one cursor for both directions, outgoing first, absence means last page). It also notes the 'never truncated' guarantee. This is rich, non-redundant context that helps the agent anticipate 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?

The description is four sentences, each informative. It front-loads the core purpose and then explains pagination and usage. While not as terse as some two-sentence examples, every sentence earns its place; there is no fluff. Slightly longer than necessary but still well-structured and easy to parse.

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 an output schema (not shown here but flagged as present), so the description does not need to explain return fields. It covers the main invocation flow: start with an id from get_entity, understand pagination via cursors, and know when to switch to search. It also addresses the edge case of over-budget pages. For a graph traversal tool, this is complete and actionable.

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 schema already documents each parameter well (id, limit, cursor). The description adds extra meaning about cursor behavior ('One cursor walks both directions, outgoing first; its absence means you have the last page') and the default limit, which goes beyond the schema's static descriptions. This adds value, though not a huge jump over the schema, so a 4 is appropriate.

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

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

The description states a specific verb ('traverse') and resource ('knowledge graph'), then details the behavior: returning outgoing and incoming relations with relation types. It also distinguishes itself from siblings by explicitly saying 'Use this after get_entity' and 'use search when you have a question and no starting object', making the purpose unmistakable.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Use this after get_entity to widen an answer' and 'use search when you have a question and no starting object'. It names the alternative (search) and the condition that selects it, leaving no ambiguity for the agent.

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?

The description adds substantial behavioral detail beyond the annotations: default page size of 25, maximum of 200, response budget around 64 KB, page over budget returned shorter with next_cursor, and cursor absence meaning last page. This goes well beyond the annotations' readOnly and idempotent hints.

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 dense but every clause contributes: purpose, pagination behavior, filtering rationale, and usage context with sibling differentiation. It is well structured, front-loading the core purpose before explaining paging and filters.

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 description covers what the tool returns, how paging works, when to use it, and how it relates to get_entity. With annotations declaring readOnly and non-destructive behavior, plus an output schema present, no critical context is missing for an agent to decide when and how to call this 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 schema descriptions are already rich, including details like 'Opaque; do not construct one' for cursor. The description mentions filter names but does not add significant parameter-level meaning beyond the schema, so it earns the baseline for high schema coverage.

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

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

The description states the tool exposes 'The instance's source registry' and that each entry includes evidence tier, reliability, and access date. It clearly distinguishes from siblings by noting that get_entity already tells which sources a claim cites, so get_sources is the way to retrieve registry entries or sample the registry.

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 explicit usage guidance: 'Use this when you need the registry entry behind a citation, or a sample of the whole registry to judge the corpus before trusting it'. It also points to get_entity as the alternative for knowing which sources a claim cites, and suggests filters to avoid unnecessary paging.

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?

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses pagination behavior: 25 default, 200 max, ~64 KB budget, short pages still include next_cursor, and absence of next_cursor signals the last page. It also reveals the unknown-tag fallback behavior, which is valuable runtime context.

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 dense but every sentence earns its place: purpose, pagination details, usage routing, and edge-case behavior. It is front-loaded with the core action and scoping 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?

Given the pagination complexity, output schema, sibling tools, and annotations, the description covers everything needed to call the tool correctly: default/max limits, cursor semantics, unknown-tag behavior, and alternatives.

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 baseline is 3, but the description adds meaningful semantics: cursor behavior, response budget implications, and the unknown-tag behavior. This enriches the tag and cursor parameters beyond their schema definitions.

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: 'List the knowledge objects carrying a tag,' and clarifies that topics are content-backed tags. It also explicitly distinguishes this tool from search and get_overview, making its purpose unmistakable.

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 explicit when-to-use guidance: 'Use this to browse a known topic; use search when you have a question rather than a tag, and get_overview to see which tags exist.' This directly routes the agent among sibling tools.

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

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

The description goes well beyond the readOnly/idempotent annotations by explaining BM25 rarity weighting, field-specific weights, the minimum information-share requirement, and centrality's tie-break-only role. This clarifies behaviors that an agent could not infer from annotations or schema.

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

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

The description is long but every sentence carries distinct, decision-relevant information about matching and ranking. It is front-loaded with the core purpose and then deepens with mechanisms that affect result interpretation.

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 search tool with nuanced relevance behavior, the description is complete: it explains what is searched, how matching handles accents, how scoring works, what breaks ties, and the expected workflow with get_entity. The output schema can handle return-value details.

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

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

Schema coverage is 100%, so the schema already documents query and limit. The description adds meaningful guidance about query formulation: use the user's own words, common-only terms won't qualify, and rarer terms weigh more. This improves parameter understanding beyond the schema.

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

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

The description states a clear verb and resource: full-text search over the knowledge graph. It also distinguishes the tool from get_entity by framing it as the right choice when you have a question rather than an id.

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 explicitly says to use this whenever a question is available rather than an id, and to follow up with get_entity. This gives an agent a concrete decision rule and names the relevant sibling alternative.

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