Agent Reliability

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it promises sourced answers with confidence and explicitly guarantees it never returns an unsourced answer. No contradiction with annotations was 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?

Three tight sentences, each earning its place: the first states the core action, the second describes the output guarantee, and the third gives routing guidance. It is front-loaded and free of 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 single-parameter read-only tool with an output schema and rich annotations, the description covers purpose, behavior, output characteristics, and the key sibling distinction. Nothing essential for 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?

Schema description coverage is 0%, but there is only one self-descriptive parameter, 'question'. The description reinforces its meaning by saying 'asked a question in words', which clarifies that natural-language questions are expected. This adequately compensates for the absence of a parameter 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 opens with a specific verb and resource: 'Answer a question from the corpus.' It further distinguishes itself from the sibling search tool by stating it returns matched claims with sources and confidence, so an agent can tell what this tool does at a glance.

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 routing guidance: use this tool when the user asked a question in words, and use search when the agent wants to inspect candidates itself. This directly names the alternative and the condition that selects between them.

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 destructiveHint, so the description does not need to restate safety. It adds context about the returned data (claims and sources), but no further behavioral caveats such as error cases or limitations.

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 with no waste. The action is front-loaded, and the usage condition is stated efficiently. Every clause 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?

The tool is simple (one parameter), has an output schema, and safety annotations. The description explains what it fetches and when to call it, making it complete for correct invocation. No critical information 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 schema only defines id as a string with length constraints. The description adds that the id comes from search/answer/get_topic, giving the agent a source, but does not explain the id format or meaning in more depth. This partially compensates for the 0% 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 a specific verb and resource ('Fetch one knowledge object by id') and includes the return content ('with its claims and the sources each claim cites'), which distinguishes it from search/overview/sources tools.

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?

Explicitly instructs when to use this tool ('once search, answer or get_topic has given you an id'), providing a clear precondition. It does not explicitly exclude sibling tools for other scenarios, but the context is sufficient.

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 behavioral context by indicating that results are ordered by verification recency and that this is a freshness signal, which is useful 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?

The description is two sentences with no fluff. It front-loads the core purpose ('Most recently verified knowledge objects') and then provides context for when to use it. 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 one-parameter, read-only tool with an output schema, the description is complete. It explains the tool's purpose, the freshness angle, and when to use it. The only parameter is defined in the schema, and the output schema covers return format. Nothing needed for 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?

Schema description coverage is 0%, so the description must compensate for parameter explanation. It does not mention the 'limit' parameter at all, though the schema provides type, default, minimum, and maximum. Since the parameter is simple, the gap is moderate, but the description still fails to state that it controls the number of returned objects.

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 tool returns 'most recently verified knowledge objects' and frames it as a freshness signal. This distinguishes it from siblings like get_entity (specific entity), get_overview (overview), and search (general search) by emphasizing recency and verification. The verb 'get' and resource are specific and 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 description gives explicit use cases: 'judge how current the corpus is' and 'see what changed since you last read it.' This tells when to use the tool. It does not mention alternatives or when not to use it, but the use cases are clear enough for a simple listing 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the kind of information returned (counts, tags, freshness) and the intended first-use role, but does not go deeper into behaviors like freshness thresholds or caveats. This is adequate given the 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?

The description is two sentences with no filler. The first sentence front-loads the core purpose and contents, and the second provides immediately actionable usage guidance.

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 tool with a rich output schema and annotations covering safety, the description is complete. It tells the agent what the tool reports, when to call it, and how it fits relative to the overall workflow. No critical 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?

The tool has zero parameters, so the baseline is 4. There is nothing for the description to clarify about input semantics, and the schema confirms no parameters are required.

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 identifies a specific resource ('Corpus overview') and the exact content delivered: counts by type, published tags, and freshness. It also differentiates itself from siblings by framing itself as the entry-point discovery tool, unlike search or get_entity.

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 says 'Use this first when you land here and do not yet know whether this corpus can answer your question,' giving a clear when-to-use trigger. It does not explicitly mention alternatives or when not to use it, but the guidance strongly implies this precedes other 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 adds behavioral detail beyond the annotations by specifying that both outgoing and incoming relationships are returned and that each includes its relation type. Annotations already cover read-only, idempotent, non-destructive safety, so the extra description meaningfully enriches the tool's behavior without contradicting 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?

Two tightly written sentences with no filler. The core behavior is front-loaded, and the usage sequencing is delivered in the second sentence. 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?

For a single-parameter, read-only graph traversal tool with an output schema and safety annotations, the description covers the essential context. It could clarify whether 'neighbours' means only immediate adjacency versus multi-hop traversal, but overall it is sufficiently complete for an agent to invoke the tool effectively.

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 only one parameter, id, with 0% schema description coverage. The description implies id is the identifier of a previously fetched object via 'after get_entity', but it never explicitly defines id's format, origin, or what object types are valid. This gives enough context for inference but leaves the parameter semantics partly implicit.

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 concrete function: return graph neighbours of an object with outgoing/incoming relations and relation types. It also distinguishes the tool from get_entity by framing it as the follow-up step to widen an answer, so an agent can tell what this tool is for without opening the 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?

The description explicitly advises using this tool after get_entity to widen an answer with adjacent objects, giving clear usage context. It does not enumerate exclusions or compare against the full sibling list, but the key routing guidance is present.

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 destructiveHint, covering the safety profile. The description adds meaningful behavioral context by explaining that the tool can return either the full registry or a filtered citation set, and by framing it as a trust/verification operation.

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 sentences with no filler. The core capability is front-loaded, and the usage guidance is concise and directly actionable.

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 with an output schema available, the description covers the main behavior and use cases. The main gap is not explicitly mapping the one parameter to the 'cited by one object' mode, but this is a minor omission given the low complexity.

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 the undocumented object_id parameter. It implies that passing an object filters to cited sources, but it never names object_id or explains its format, constraints, or default behavior when omitted.

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 identifies the resource ('source registry') and the two retrieval modes ('whole source registry' or 'sources cited by one object'). It conveys a specific purpose, though it doesn't explicitly contrast with sibling tools like get_entity or get_related.

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 concrete use cases: 'check what a claim rests on' and 'judge the corpus before trusting it.' It lacks explicit exclusions or named alternatives, so it doesn't fully guide an agent away from sibling tools, but the intended 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful semantic that topics are content-backed tags, but it does not disclose potential behaviors like pagination, limits, or empty-result handling; those gaps keep it at the baseline.

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 the core action, followed by targeted routing guidance. Every sentence earns its place; there is no filler or duplication of schema 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 one-parameter, read-only, idempotent tool with an output schema present, the description provides everything needed to invoke it correctly: what it lists, what the input represents, and how it differs from alternatives. The output schema covers return shape, and annotations cover side-effect expectations.

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 schema has only the tag parameter with no description, so the description carries the burden at 0% schema coverage. It compensates by defining tags as content-backed topics and repeatedly contextualizing 'tag' as the value to pass. It stops short of giving examples or format details, but the single parameter is simple enough that this is sufficient.

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: 'List the knowledge objects carrying a tag', and immediately clarifies that topics are content-backed tags. It distinguishes itself from siblings by naming search and get_overview as different operations, so an agent can select it without opening 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?

It explicitly states when to use this tool: to browse a known topic. It also gives exclusion criteria by directing users to 'search when you have a question rather than a tag' and to 'get_overview to see which tags exist'. This is clear, actionable 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 cover safety (readOnly, idempotent, non-destructive). The description adds meaningful behavior beyond that: accent/apostrophe-insensitive matching and the guarantee that each hit includes its relevance score and matched fields. This enriches understanding of how the tool 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?

Two sentences, no waste. The purpose and key matching behavior are front-loaded, followed by 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?

With an output schema present, the description doesn't need to explain return values. It covers matching behavior, output guarantees (relevance score, matched fields), and usage scenario. It could mention result ordering or default behavior of limit, but schema covers the limit default. Overall quite complete for a two-parameter search 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 0%, so the description must compensate. It gives concrete guidance for the query parameter ('query in the user's own words'), explaining the accent-insensitive behavior. The limit parameter is not explicitly described, but its schema (default, min, max) covers the basics. It adds value for the key parameter, 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 ('Full-text search') and resource ('the knowledge graph'), and explicitly distinguishes from get_entity by saying 'Use this whenever you have a question rather than an id'. This is a clear, unambiguous purpose that differentiates it from siblings.

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 explicit when-to-use guidance ('whenever you have a question rather than an id') and names the follow-up tool (get_entity), which implies the alternative path. This is direct and actionable without being verbose.

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