Edgepedia

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 behavior: a hard bound of at most 6 hops and the fact that each hop is returned with the sentence that justifies it, disclosing the shape of the search rather than just its existence.

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?

A single front-loaded sentence with the action and constraint stated before the input-sourcing clause. No filler, no redundancy with the title, and the flow constraint (6 hops) is not buried.

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 not required, and the description still summarizes it briefly. Combined with annotations and a fully documented schema, an agent has what it needs, though it never states what happens when no chain exists within 6 hops.

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. The description goes beyond the schema by clarifying that both arguments are ids obtained from `search`, which tells the agent where to source valid values rather than guessing at titles or slugs.

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?

Specific verb+resource: 'Find the shortest chain of in-text links from one Edgepedia article to another' states exactly what the tool does. It differentiates itself from siblings by tying its input to `search`'s output ('pass two ids as search returns them'), so an agent can distinguish it from fetch/related/resolve/search 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?

Gives clear context for use: call `search` first, then pass the returned ids. It implicitly positions the tool after search in a workflow, but offers no explicit exclusions (e.g., when to prefer `related` or `resolve` instead), so it falls 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description goes further by disclosing the return shape, that topic ids page 120 at a time, how `citations: false` changes output, and the licensing obligation to show the `credit` line. It stops short of discussing truncation/cursor behavior, which lives only in the 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?

Purpose and return fields are front-loaded, then progressively more specialized behaviors. Dense and largely earned, though the middle sentences pile several distinct features (topic paging, citations, credit) into a run that could be split.

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 17 params at full schema coverage and an output schema, the description needn't enumerate returns, yet it does enough to orient the agent (Markdown body, citations, topic listing). It omits explicit when-to-use guidance relative to the four siblings, which is the remaining 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: the `topic:` id convention with concrete examples (`topic:root`, `topic:geo`), the 120-per-page default, and the behavioral contract of `citations: false`. These go beyond the terse schema strings.

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 (read), resource (an Edgepedia article), scope (in full, as Markdown with citations) and ties the input to a sibling ('by a `search` result's id'). An agent can tell this apart from search/related/resolve 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?

It implies the workflow (get an id from `search`, then fetch it) and explains topic: ids and the citations flag, but never states when to prefer this over siblings like `related` or `resolve`, nor any exclusions. Usage is implied rather than prescribed.

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/non-destructive/openWorld=false, so the safety bar is covered. The description adds real behavioral context beyond that: results come back grouped, and each group is a `topic` id that can be fetched for more.

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 front-load the purpose, then the input convention, then the follow-up. The phrase 'a few from each neighboring topic' is slightly loose but informative rather than filler.

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

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

An output schema exists, so return values need not be spelled out, and the description still adds the grouping and pagination-by-topic follow-up. Complete enough for a 2-param read tool with full schema coverage.

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 `id` and `by` are already documented in the schema. The description reinforces the `id` convention ('as for `fetch`') but says nothing about `by`, so it adds only marginal value over the structured fields – baseline 3.

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?

Specific verb+resource ('find encyclopedia articles related to an Edgepedia article') and it concretely decomposes 'related' into topic-mates, neighbors, and geography neighbors. It also names the sibling `fetch` for the id convention, so an agent can place it among the siblings 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?

Clearly implies the retrieval context and gives a concrete chaining rule ('fetch a group's `topic` id for more'), plus the 'id as for `fetch`' convention. It does not explicitly contrast with `connect` or `search`, so exclusions are absent.

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/non-destructive (and closed-world), so the safety profile is covered. The description adds real behavioral context beyond them — that the result carries a confidence and an ambiguity flag, and that a ranked `alternatives` list comes back — which helps the agent interpret output.

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?

Dense but front-loaded: the core purpose leads, then a single sentence covers inputs and one covers output/resumption. It is slightly long with parenthetical examples, but no sentence is redundant.

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 4-param, output-schema-backed lookup tool, everything needed to call it correctly is present: required vs optional params, their interaction, and the downstream handoff to `fetch`. Return-value detail is a bonus rather than a necessity.

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. The description earns above baseline by giving concrete examples ('Mercury', `context`: "planet orbit") and by clarifying that `type` uses the same topic id that `fetch` names as `topic:…`, cross-linking the two params' semantics.

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 — resolving a name to an Edgepedia article — and immediately differentiates itself from siblings by framing the task as disambiguation (best match, confidence, ambiguity, alternatives). An agent can tell this apart from `search`, `fetch`, `connect`, or `related` without opening any schema.

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

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

Gives clear usage context: pass a name from a text, optionally with surrounding words or a topic id, and it routes downstream by saying 'pass an id to `fetch`'. It does not explicitly contrast with the sibling `search`, so the when-not-to-use case is left implicit.

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, closed-world behavior, so the description's added value is in matching semantics: other names and misspellings match, and fulltext fallback results are flagged with `match: fulltext`. It also discloses that a `topic:` result may appear and that limit/page reach further results, though it does not describe ranking or result-count behavior beyond 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?

Purpose and the key query constraint are front-loaded, and every sentence carries information. The middle sentence is long and clause-heavy, packing matching behavior, return fields, topic results, and fetch handoff together, but it remains readable.

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 six parameters, full schema coverage, annotations, and an output schema, the description covers the important operational details: query shape, fuzzy/fulltext matching, pagination, topic results, and fetch handoff. The main remaining gap is the lack of guidance on choosing this tool versus the sibling resolve or related tools.

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 would be 3; the description earns more by clarifying that the query should be a subject name rather than a question and by explaining that limit and page traverse further results. The topic and sort parameters are left mostly to their schema descriptions, but the query guidance is meaningfully richer than the schema text.

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 — searching an encyclopedia for facts about a person, place, thing, event, or concept — and names Edgepedia with its scale and citation coverage. An agent can immediately distinguish this from fetch, which is explicitly mentioned as the follow-up tool for a returned 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 gives clear query-shape guidance (pass a subject name such as "Mount Fuji" or "photosynthesis", not a question) and explains the handoff to fetch. It does not explain when to prefer search over the sibling tools resolve or related, so it stops short of explicit alternatives/exclusions.

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