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

Annotations already cover read-only and non-destructive behavior. The description adds valuable context about Aleph's data model: relationships are entities themselves, so they won't appear as plain fields on the record, and results are grouped by relationship type. This helps the agent set expectations 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?

Two sentences with no filler. The core action and output shape are front-loaded, and the data-model explanation is kept to one compact second sentence.

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 is adequate for a read-only network traversal tool: it identifies the input, the output, and an important conceptual gotcha. It does not describe pagination or exact response structure, but the schema covers limit and properties, so no critical operational detail 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 100%, so each parameter is already documented in the schema. The description does not add new parameter-level detail beyond implying traversal and grouping, which is sufficient but not exemplary given full 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 ('List'), a clear resource ('entities connected to this one'), and the output structure ('grouped by relationship type'). It also names representative relationship types, making the tool's role distinct from siblings like aleph_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 phrase 'This is how you walk a network' gives a clear when-to-use signal, and the explanation that relationships are entities helps an agent understand why it must use this tool rather than looking for plain fields on a record. It does not explicitly discuss alternatives, but the intended traversal use case 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, openWorldHint, and destructiveHint=false, and the description's 'Read' matches. It adds that the tool returns extracted text rather than metadata, but it doesn't say whether output is a raw string, how max_chars affects the result, or what happens when no text is extracted. No contradiction with 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 sentences, no filler. The core purpose is front-loaded, and the usage note is second. 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?

For a read-only tool with two well-documented params and no output schema, the description gives the agent what it needs: what it does, what input to pass, and why to use it. A minor gap is not spelling out the return shape or truncation effect, but the schema already documents max_chars.

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 covers both parameters fully (100%), but the description adds semantic context for entity_id: it must be a Document, Pages, Email or similar entity from a search result. That is useful beyond the schema's generic 'Entity ID of the document.'

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 ('Read') and resource ('extracted text of a document entity'), enumerating example entity types (PDF page, email, article) and a concrete purpose (quoting/verifying). This clearly distinguishes it from siblings like aleph_get_entity, which would satisfy a general 'fetch entity' interpretation.

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 states when to use it: after a search, when you need the actual text to quote or verify, and it tells you to pass an entity ID from search results. It does not explicitly name alternative tools or exclusion criteria, so a small inference is left to 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?

Annotations already cover read-only, open-world, and non-destructive behavior. The description adds useful expectations about what the returned metadata contains, which is especially valuable since there is no output schema. No contradiction with 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 tight sentences with the key content front-loaded and no filler. Every clause contributes to selection or invocation.

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 simple read-only call with one required parameter, the description adequately covers what the tool returns and when to use it. It does not specify error behavior or where to find the ID, but those are minor 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 parameter 'collection_id' is self-documented as 'Collection (dataset) ID.' The description adds the 'dataset' synonym but does not need to elaborate further; 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 clearly identifies the resource as 'one dataset' and specifies the exact content returned: publisher, source URL, coverage, update frequency, and entity-type breakdown. This makes it easy to distinguish from entity-search or collection-listing siblings even without reading their 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?

The description provides a concrete usage rule: use it to judge source trustworthiness and currency. It lacks explicit when-not-to-use guidance or named alternatives, so it stops slightly 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 and openWorldHint with destructiveHint false, covering safety. The description adds a concrete behavioral guarantee: the response includes every populated property, setting expectations for payload shape and completeness. No contradiction with 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 concise sentences with the core action and scope front-loaded, followed by a single usage instruction. No filler or redundant restatement of the schema.

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 fetch tool with annotations covering safety and a clear usage hook, nothing essential is missing. There is no output schema, but the 'every populated property' phrase gives enough return-format expectation; invalid-ID behavior is not required 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 description coverage is 100% and the parameter description 'Entity ID from a search result.' is already clear. The tool description reinforces that the ID comes from search results but adds no new format or 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?

States a specific verb ('Fetch'), a precise resource ('one entity by ID'), and scope ('every populated property'). The 'Use after aleph_search' hook ties it to the search workflow and distinguishes it from sibling tools like aleph_search or aleph_expand_entity, so an agent can select it 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?

Explicitly says to use after aleph_search to see the full record behind a hit, which gives a clear context. It doesn't mention alternatives or when not to use it, but the workflow guidance is enough for a single-purpose fetch 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?

Beyond the readOnlyHint and non-destructive annotations, the description explains what behavior to expect depending on the input: a list of schemata when omitted, and properties/links when a name is supplied. This adds return-behavior context without contradiction, though it does not cover finer details like error cases.

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 deliver the tool's purpose, invocation pattern, and usage context with no repetition or filler. The information is front-loaded, and each sentence contributes to the agent's ability to call the tool correctly.

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 simple read-only reference tool with one optional parameter and no output schema, the description provides enough information to invoke it and understand its result shape at a high level. It might be slightly richer about the exact structure of the returned schema properties, but that is not essential 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?

The schema already documents the sole parameter at 100% coverage, but the description adds meaningful context by explaining the no-argument behavior, providing example names, and tying the parameter to practical use (picking filters or expanding properties). This goes beyond the baseline schema-only value.

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 tool as a reference for the followthemoney data model and specifies its two calling modes: no argument lists all schemata, a schema name returns properties and links. This distinguishes it from sibling tools like aleph_get_entity or aleph_search, which operate on entities rather than the schema model 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?

The description states a clear use case: 'Use it to pick the right schema filter or expand property.' It also gives direct guidance on when to pass a schema name versus no argument. It does not explicitly name alternatives or exclusion criteria, so it falls slightly short of a perfect score.

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 communicate readOnlyHint=true and destructiveHint=false, and the description is consistent with them. It adds a useful nuance that collections are 'available to you', implying permission-scoped results, but doesn't go further into pagination, result shape, or filtering behavior beyond 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?

The description is two tight sentences with the core purpose front-loaded and a practical follow-up about using collection IDs downstream. Every sentence earns its place with 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 an optional-parameter list tool with rich schema descriptions and safety annotations, the description is complete: it states what the tool lists, what the returned IDs are for, and how this fits into a larger search workflow. No output schema exists, but the tool's return value is inferable as a list of collection objects.

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 all five parameters already have meaningful documentation. The description's category examples (leaks, company registries, sanctions lists) reinforce the category parameter but add no parameter-level detail 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 starts with a specific verb and resource, 'List or search the datasets (collections) available to you', and gives concrete examples of collection types. It also differentiates itself from aleph_search by framing collections as the source-discovery layer and explicitly pointing the agent to pass collection IDs to aleph_search afterward.

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 a clear usage context: use this tool to discover what sources exist before scoping an aleph_search query. It doesn't explicitly state when not to use it versus aleph_get_collection, but the discovery-oriented guidance is enough for most routing decisions.

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 this as read-only and non-destructive, so the safety profile is covered. The description adds useful behavior beyond annotations: it searches only datasets the user 'can read,' returns compact summaries rather than full entities, and suggests facets for clustering by countries or datasets.

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: scope, entry-point role, result format, and facet guidance. The core action is front-loaded and there is no redundant or filler 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?

Given a rich 100% schema-described parameter set, clear annotations, and no output schema, the description covers the essential workflow: search broadly, receive IDs, pass them to other tools. It could be slightly stronger by naming a sibling like aleph_get_entity for retrieving full details, but it is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds mild parameter context by explaining that facets reveal country/dataset clustering, but it does not need to repeat query, limit, offset, or filter semantics already well documented in 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 and resource: 'Search entities ... across every Aleph dataset you can read.' It also positions itself as 'the main entry point' and clarifies that results are compact summaries with entity IDs, which distinguishes it from direct-fetch and similarity sibling 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?

The description gives clear context: this is the main entry point and should be used first, producing entity IDs to feed into other Aleph tools. It does not explicitly name alternatives or state when not to use it, but the entry-point workflow is clearly communicated.

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, open-world, and non-destructive behavior. The description adds valuable context beyond that by stating results are 'ranked candidates, not confirmed matches' and advising verification with birth dates, addresses, or registration numbers. This meaningfully informs downstream agent 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 three concise sentences with no filler. It front-loads the purpose, then gives a practical use case, and closes with an important caveat. 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?

There is no output schema, but the description explains that the tool returns ranked candidates rather than confirmed matches and gives verification guidance. It does not describe the exact result shape, but for a simple read-only lookup with two parameters, the provided context is largely sufficient.

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% with descriptions for both parameters: 'entity_id' and 'limit'. The description only indirectly refers to entity_id as 'this one' and does not add meaningful parameter-level detail beyond the schema, so the baseline score of 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 clearly states the operation ('Find') and the resource ('entities that may be the same real-world person or company as this one'), and gives a concrete use case linking a leak to a company registry. It distinguishes the tool from simple entity retrieval, but it does not explicitly contrast it with siblings like aleph_expand_entity or aleph_xref_results.

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 guidance on when to use the tool: 'Use it to link a subject between a leak and a company registry.' It also sets expectations that results are candidates, not confirmations. However, it does not state when not to use it or mention alternative 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond this: it returns aggregate statistics rather than specific records, and it contextualizes the open-world nature by warning against concluding absence before checking 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?

Two sentences, no filler. The core capability is front-loaded, and the practical use case is stated succinctly in the second sentence. Every clause adds value.

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 statistics tool, the description is complete: it explains what the tool returns, how results are broken down, and when to invoke it. No output schema exists, but the aggregate breakdown is named, so an agent can make an informed call.

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 schema description coverage is 100%, so there are no parameter semantics to explain. The description appropriately focuses on output semantics instead, which is the useful information for an agent selecting this tool.

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?

Description uses specific language—'Size and shape of the Aleph instance'—and states exactly what it returns: dataset and entity counts with breakdowns by type, category, and country. It also clearly communicates its role as a coverage-gauge tool, which distinguishes it from entity/search/collection tools among the 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?

The description explicitly tells the agent when to use this tool: 'Use it to gauge coverage before concluding something is absent.' It does not explicitly list exclusions or name alternative tools, but the use case is distinct enough from siblings like search or entity retrieval that the guidance 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?

The description explicitly says this is read-only and that it does not trigger a new cross-reference computation, which adds useful behavioral context beyond the annotations. It is consistent with the readOnlyHint and destructiveHint annotations, and no contradiction 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 concise sentences each earn their place: what the tool returns, when it is useful, and a behavioral caveat about not starting a new run. The main verb and resource are 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 simple read-only paged tool, the description plus full schema covers the purpose, inputs, and side-effect profile. It could mention behavior when no cross-reference results exist, but that is a minor gap given the schema and annotations.

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 already includes descriptions for all three parameters, including defaults and bounds for limit and offset. The description adds contextual framing about the collection but does not need to compensate for missing schema information, so baseline 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 states a specific verb ('Read') and resource ('cross-reference results already computed'), explains what those results are (entities resembling entities elsewhere in Aleph, scored and ranked), and clarifies that this is distinct from starting a new cross-reference run. This clearly differentiates it from related sibling 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?

It gives a concrete use case: finding overlaps between your own casefile and public registries. It also clarifies that this tool does not start a new cross-reference run. However, it does not explicitly name alternative sibling tools or state when not to use this tool.

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