Spain's contributions to world science, exploration and culture, rigorously sourced
Scored across 9 tools
Each tool targets a distinct operation: answering from the corpus, full-text search, comparing multiple objects, fetching single entities, browsing by tag, exploring relations, checking freshness, overview, and source registry. The descriptions draw clear boundaries, especially between answer and search, so an agent is unlikely to confuse them.
Most retrieval tools follow a consistent get_* pattern (get_entity, get_related, get_sources, get_topic, get_latest, get_overview). The bare-verb tools answer, compare, and search are predictable query-style actions and not resource-named, so the naming convention is mostly consistent even if not perfectly uniform.
Nine tools is well within the ideal range for a knowledge-graph corpus server. Each tool covers a distinct need — discovery, search, retrieval, comparison, relation traversal, provenance, and freshness — without redundancy or bloat.
The surface fully covers the read-side lifecycle of a curated knowledge corpus: discover topics and overview, search, answer, fetch entities, traverse relations, compare objects, inspect sources, and assess freshness. Since this appears to be a read-only knowledge base, the absence of mutation tools is not a gap.
Answer a question from the corpus, or refuse. Returns only the claims that bear on the question, each with the sources it cites and its editorial confidence. When the corpus cannot answer, answered is false and abstention_reason plus missing_topics say what was not covered — a refusal is a real result here, not an error. Use this when the user asked a question in words; use search when you want to see the candidates yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | The question to answer, in the words the user asked it. |
| Name | Required | Description |
|---|---|---|
| claims | No | |
| entity | No | |
| margin | No | Relative gap between the best candidate and the runner-up. A small margin means the corpus cannot tell them apart. |
| answered | Yes | |
| coverage | No | Share of the question's information the winning object accounts for, weighted by term rarity. |
| candidates | Yes | Near misses, so a refusal is still a lead. Present whether or not the question was answered. |
| match_score | No | |
| matched_fields | No | |
| missing_topics | Yes | Meaningful words in the question that appear nowhere in the winning object — the gap, named. |
| match_threshold | Yes | The coverage this corpus requires before it will answer at all. |
| match_confidence | No | How well the answer fits the QUESTION — retrieval confidence, not editorial. Never confuse it with a claim's own confidence, which is how much the corpus stands behind the statement. |
| matched_question | No | The stored question this was matched to, when the answer came from one. |
| abstention_reason | No | Why the corpus declined: empty_query, no_candidates, below_coverage, ambiguous_candidates or no_intent_match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavior beyond that: it details the return composition (claims with sources and editorial confidence) and explains the refusal semantics (answered=false, abstention_reason, missing_topics). This gives the agent a precise model of what happens in both success and abstention 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?
The description is three sentences, each earning its place: the core action, the behavioral detail, and the routing guidance. It is front-loaded with the main purpose and avoids any filler or redundant restatement of the title.
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 one parameter, a complete output schema, and annotations covering safety and idempotency, the description needs to handle only the behavioral and selection nuances. It does so thoroughly by explaining refusal behavior and distinguishing itself from search. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single 'question' parameter. The description reinforces the intended usage ('in the words the user asked it') but adds no new semantic information beyond the schema. A baseline 3 is appropriate when the schema carries the parameter burden.
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: 'Answer a question from the corpus, or refuse.' It clearly distinguishes the tool from the sibling search by saying 'Use this when the user asked a question in words; use search when you want to see the candidates yourself.' This leaves no ambiguity about what the tool does.
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 guidance: 'Use this when the user asked a question in words' and explicitly names the alternative: 'use search when you want to see the candidates yourself.' It also handles the refusal case, explaining that a refusal is a real result, not an error.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Two to six knowledge objects side by side: their cards, every indexed attribute as a matrix (the same fields api/index.json publishes, null where an object does not say), the tags they share, the relations that run between them, the neighbours they have in common, and each one's claims with sources and confidence. Use this when the question is 'X vs Y', 'is X the same as Y' or 'how does X differ from Y' — search or get_topic first if you only have names, then pass the ids. An unknown id lands in missing with a near-miss suggestion and the rest are still compared.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Two to six knowledge object ids, as returned by search, get_topic or get_related, in the order you want the columns. |
| Name | Required | Description |
|---|---|---|
| found | Yes | True only when every id resolved. |
| claims | Yes | Every compared object's claims, keyed by object id. |
| facets | Yes | |
| missing | Yes | The ids that resolved to nothing, in the order asked. |
| objects | Yes | |
| recovery | No | |
| shared_tags | Yes | |
| relations_between | Yes | |
| shared_neighbours | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, non-destructive, and closed-world, and the description adds meaningful behavioral context: unknown ids land in a 'missing' field with a near-miss suggestion, comparison continues with the remaining objects, and missing attributes are represented as null. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences deliver output scope, usage context, and edge-case behavior with no filler. The most important information—what the comparison includes and when to use it—is front-loaded, and the unknown-id behavior closes the description efficiently.
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 one required parameter, a rich output schema, and annotations covering safety, the description still adds everything needed for correct invocation: when to use it, how to prepare input ids via other tools, what the output contains, and how failures are reported. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the ids parameter, including source, cardinality, and column ordering. The description adds extra parameter behavior by explaining how unknown ids are handled and that the rest are still compared, which enriches the 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 states a specific verb (compare), a specific resource (knowledge objects), and a detailed scope: side-by-side cards, indexed attribute matrix, tags, relations, common neighbours, and claims. It also distinguishes itself from siblings by specifying when 'X vs Y' questions call for this tool rather than search or 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?
Explicit usage conditions are given: use when the question is 'X vs Y', 'is X the same as Y', or 'how does X differ from Y'. It also instructs to call search or get_topic first when only names are known and then pass the resulting ids, clearly routing the agent to the correct workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one knowledge object by id, with its claims and the sources each claim cites. Use this once search, answer or get_topic has given you an id. An unknown id is not a dead end: the answer names near-miss ids you can retry with.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The knowledge object's id, as returned by search, answer, get_topic or get_related — the last segment of its canonical URL. |
| Name | Required | Description |
|---|---|---|
| found | Yes | |
| entity | No | |
| recovery | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior, and the description adds useful extra context: the structure of the returned data, the prerequisite that an id comes from a prior tool, and the error-recovery behavior where unknown ids produce near-miss retry candidates. There is 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?
The description is three sentences, each earning its place: the core operation, the workflow trigger, and the error-recovery behavior. There is no filler or repetition, and the most important 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 simple single-parameter read-only lookup with an output schema available, the description covers purpose, usage context, and failure behavior. The output schema handles return structure, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes the single parameter 'id' in full detail, including where it comes from and its URL format, so schema coverage is 100%. The description only says 'by id,' adding no meaningful semantic information beyond the schema. 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 states a specific verb and resource: 'Fetch one knowledge object by id,' and further specifies the return content ('with its claims and the sources each claim cites'). This is concrete enough to distinguish it from sibling tools like get_overview or get_sources, even without naming them.
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 an explicit trigger: 'Use this once search, answer or get_topic has given you an id,' which clearly establishes a workflow context. It also provides failure-recovery guidance for unknown ids. However, it does not explicitly mention when not to use this tool or name alternative siblings for different needs, so it stops short of full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most recently verified knowledge objects (freshness signal). Use this to judge how current the corpus is, or to see what changed since you last read it. It ranks by verification date and ignores your topic entirely — use search or get_topic when you want objects that are relevant rather than recent.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many recently verified objects to return, newest verification first. |
| Name | Required | Description |
|---|---|---|
| total | Yes | |
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: it ranks by verification date, serves as a freshness signal, and ignores topic relevance, which is a critical behavioral trait for agent selection.
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 wasted words. The primary purpose and freshness signal are front-loaded, followed by practical usage guidance and a clear pointer to alternatives.
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 tool with one optional parameter, full annotations, and an output schema, the description covers everything an agent needs to invoke it correctly. It explains purpose, ordering behavior, topic-agnostic behavior, and when to prefer sibling 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?
The input schema fully documents the single optional limit parameter with its default, range, and meaning. The description adds no parameter-specific detail, but schema coverage is 100%, so this meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it returns the most recently verified knowledge objects, ranked by verification date. It also explicitly distinguishes itself from topic-relevant tools by stating it ignores topic entirely.
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 clearly states when to use the tool: to judge corpus currency or see recent changes. It also gives explicit alternatives, telling the agent to use search or get_topic when relevance matters instead of recency.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Corpus overview: what this instance knows, counts by type, published tags, freshness. Use this first when you land here and do not yet know whether this corpus can answer your question.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| tags | Yes | |
| by_type | Yes | |
| instance | Yes | |
| description | Yes | |
| total_media | Yes | |
| total_objects | Yes | |
| newest_verification | Yes | |
| oldest_verification | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate those. It adds context about returned data (counts, tags, freshness) but does not disclose additional behavioral traits such as authentication or rate limits, which is acceptable given 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 compact and front-loaded: it opens with the core purpose, then lists contents, then gives a clear usage directive. Every sentence contributes value with no 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 zero-parameter tool with full annotations and an output schema, the description is complete. It tells the agent what the tool returns, when to use it, and how it fits into the workflow. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema description coverage, so there is no parameter burden on the description. The baseline of 4 applies because no parameter documentation is needed.
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-like resource ('Corpus overview') and specifies what it contains: 'what this instance knows, counts by type, published tags, freshness.' It clearly distinguishes itself from siblings by positioning itself as the initial orientation tool.
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?
Provides explicit guidance: 'Use this first when you land here and do not yet know whether this corpus can answer your question.' This gives clear context for when to use the tool, though it does not explicitly name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The instance's source registry — each entry with its evidence tier, reliability and access date. PAGED: 25 entries by default, 200 at most, and a response budget of about 64 KB per call — a page over budget comes back shorter WITH a next_cursor, never truncated. Read next_cursor and call again to continue; its absence means you have the last page. Filter by object_id, tier, host or accessed_since to avoid paging through a registry you do not need. 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; get_entity already tells you which sources a claim cites.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Only sources whose URL is served by this host, compared without a leading www. A source with no URL never matches. | |
| tier | No | Only sources of this evidence tier, spelled exactly as get_sources reports it. | |
| limit | No | How many entries to return. Defaults to 25. | |
| cursor | No | Continue from a previous call: pass the next_cursor it returned. Opaque; do not construct one. | |
| object_id | No | Restrict the answer to the sources cited by this knowledge object. Omit it to page the whole registry. | |
| accessed_since | No | Only sources accessed on or after this ISO date (YYYY-MM-DD). |
| Name | Required | Description |
|---|---|---|
| found | Yes | |
| total | Yes | How many sources matched the filters, before paging. |
| sources | Yes | |
| recovery | No | |
| returned | Yes | |
| next_cursor | No | Pass to the next call to continue. ABSENT means this was the last page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond the schema: pagination details (25 default, 200 max, ~64 KB budget, over-budget pages come back shorter WITH next_cursor, never truncated), how to detect the last page, and the semantics of a source with no URL never matching a host filter. This is rich behavioral disclosure.
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 compact and front-loaded: a one-sentence definition, then pagination semantics, then filtering guidance, then usage routing. Every sentence earns its place and none are redundant with 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 read-only list tool with an output schema and 100% schema coverage, the description fully covers what an agent needs: what the resource is, when to use it versus siblings, how pagination works, and how to narrow results. The output schema covers return values, so 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?
Schema description coverage is 100%, and each parameter has a meaningful schema description (e.g., cursor is 'Opaque; do not construct one', host has 'A source with no URL never matches'). The description adds the pagination context (next_cursor meaning, page budget) but doesn't need to repeat parameter-level details. Baseline 3 is appropriate since the schema already carries the full weight.
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+resource ('The instance's source registry') and immediately distinguishes it from siblings by saying 'Use this when you need the registry entry behind a citation, or a sample of the whole registry... get_entity already tells you which sources a claim cites.' It clearly identifies the resource as a source registry and its role relative to 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?
Explicit when-to-use: '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; get_entity already tells you which sources a claim cites.' It also gives filtering advice ('Filter by object_id, tier, host or accessed_since to avoid paging') which is practical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the knowledge objects carrying a tag (topics are content-backed tags). PAGED: 25 objects by default, 200 at most, and a response budget of about 64 KB per call — a page over budget comes back shorter WITH a next_cursor, never truncated. Read next_cursor and call again to continue, and its absence means you have the last page. 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. An unknown tag comes back with the topics that do exist, so a miss still moves you forward.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | The topic to list, spelled exactly as get_overview publishes it. Every published topic has objects under it, so an empty answer means the topic does not exist. | |
| limit | No | How many objects to return. Defaults to 25. | |
| cursor | No | Continue from a previous call: pass the next_cursor it returned. Opaque; do not construct one. |
| Name | Required | Description |
|---|---|---|
| tag | Yes | |
| total | Yes | How many objects carry this tag, before paging. |
| results | Yes | |
| recovery | No | |
| returned | Yes | |
| next_cursor | No | Pass to the next call to continue. ABSENT means this was the last page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds pagination behavior (25 default, 200 max, ~64 KB budget, short pages with next_cursor), cursor semantics ('absence means you have the last page'), and unknown-tag behavior ('comes back with the topics that do exist'). These are meaningful behavioral details beyond annotations, with no contradiction.
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 packs purpose, pagination, cursor usage, and alternative-routing into a compact paragraph. Every sentence carries distinct information; no filler. The pagination note is conveniently 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 paged read-only list tool with an output schema, the description covers all required operational knowledge: how to handle cursors, edge case of unknown tags, and when to choose alternatives. Nothing an agent needs to invoke correctly 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 input schema already has 100% descriptive coverage of all three parameters (tag, limit, cursor). The description reinforces defaults and cursor semantics but doesn't add significant new meaning 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 and resource: 'List the knowledge objects carrying a tag' and clarifies that topics are content-backed tags. Explicitly differentiates from search and get_overview later in the text, which helps an agent distinguish this tool 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?
Provides explicit routing: '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.' Also gives guidance for unknown tags. This is explicit when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search over the knowledge graph. Matching ignores accents and apostrophes, so query in the user's own words; every hit carries the fields it matched and a score. BM25 relevance: each query term is weighted by how RARE it is in this corpus and by where it hits (name 3, tags 2, questions 2, body 1). A hit must also cover a minimum share of the question's information, measured in the same rarity weights — matching only common words does not qualify. Centrality (how many objects point at this one) breaks TIES ONLY and is never part of the score, so it cannot make an irrelevant object rank. Two hits with the same matched_fields can still differ: the score is rarity-weighted, so matching a rare term is worth more than matching a common one. Use this whenever you have a question rather than an id, then follow up with get_entity.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many ranked hits to return, best first. | |
| query | Yes | What to look for, in the user's own words. Matched against titles, questions, claim text and tags; accents and apostrophes are ignored, so 'jose' finds 'José'. |
| Name | Required | Description |
|---|---|---|
| total | Yes | |
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral detail beyond them: accent/apostrophe normalization, matched-field reporting, BM25 rarity weighting, per-field weights, minimum information coverage, and centrality's strictly tie-breaking role. This is rich, non-obvious behavior 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 front-loaded with the core purpose and then builds each subsequent sentence on that foundation. Every sentence earns its place: normalization rules, result content, scoring mechanics, tie-breaking, and usage routing. Despite its length, 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?
The description is complete for an agent to decide when to call search and how to use it correctly, given that an output schema exists for return values and annotations cover safety. It explains the ranking model, matches, tie-breaking, and follow-up workflow, leaving no meaningful gap for this read-only 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%, so the schema already documents both query and limit. The description adds meaningful semantic value beyond the schema by explaining that queries should use the user's own words, that accents and apostrophes are ignored, and that scoring depends on rarity and hit location—information that materially affects how an agent should construct queries.
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: 'Full-text search over the knowledge graph.' It clearly states what the tool does, differentiates it from id-based retrieval via the instruction to follow up with get_entity, and describes the matching behavior, so an agent can distinguish it from 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?
The description gives explicit usage guidance: 'Use this whenever you have a question rather than an id, then follow up with get_entity.' This names the relevant alternative and the condition that selects search instead, which is exactly the kind of when-to-use versus when-not-to-use guidance needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_related5 fields changedInput schema / properties / cursorAdded value: +{
+ "description": "Continue from a previous call: pass the next_cursor it returned. Opaque; do not construct one.",
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / limitAdded value: +{
+ "description": "How many relations to return, across both directions. Defaults to 25.",
+ "maximum": 200,
+ "minimum": 1,
+ "type": "integer"
+}Output schema / properties / next_cursorAdded value: +{
+ "description": "Pass to the next call to continue. ABSENT means this was the last page.",
+ "type": "string"
+}Output schema / properties / returnedAdded value: +{
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Output schema / properties / totalAdded value: +{
+ "description": "How many relations this object has in both directions, before paging.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}answer14 fields changedOutput schema / properties / abstention_reasonAdded value: +{
+ "description": "Why the corpus declined: empty_query, no_candidates, below_coverage, ambiguous_candidates or no_intent_match.",
+ "type": "string"
+}Output schema / properties / candidatesAdded value: +{
+ "description": "Near misses, so a refusal is still a lead. Present whether or not the question was answered.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "coverage": {
+ "type": "number"
+ },
+ "id": {
+ "type": "string"
+ },
+ "score": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "id",
+ "score",
+ "coverage"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / claims / items / properties / relevanceAdded value: +{
+ "type": "number"
+}Output schema / properties / claims / items / requiredPrevious value: -[
- "text",
- "confidence",
- "sources"
-]New value: +[
+ "text",
+ "confidence",
+ "sources",
+ "relevance"
+]Output schema / properties / coverageAdded value: +{
+ "description": "Share of the question's information the winning object accounts for, weighted by term rarity.",
+ "type": "number"
+}Output schema / properties / entity / properties / xAdded value: +{
+ "additionalProperties": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "description": "Indexed instance-specific attributes, grouped by namespace — the same fields api/index.json publishes. Absent when the instance declares none.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}Output schema / properties / marginAdded value: +{
+ "description": "Relative gap between the best candidate and the runner-up. A small margin means the corpus cannot tell them apart.",
+ "type": "number"
+}Output schema / properties / match_confidenceAdded value: +{
+ "description": "How well the answer fits the QUESTION — retrieval confidence, not editorial. Never confuse it with a claim's own confidence, which is how much the corpus stands behind the statement.",
+ "type": "number"
+}Output schema / properties / match_scoreAdded value: +{
+ "type": "number"
+}Output schema / properties / match_thresholdAdded value: +{
+ "description": "The coverage this corpus requires before it will answer at all.",
+ "type": "number"
+}Output schema / properties / matched_fieldsAdded value: +{
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / matched_question / descriptionAdded value: +"The stored question this was matched to, when the answer came from one."Output schema / properties / missing_topicsAdded value: +{
+ "description": "Meaningful words in the question that appear nowhere in the winning object — the gap, named.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / requiredPrevious value: -[
- "answered"
-]New value: +[
+ "answered",
+ "match_threshold",
+ "missing_topics",
+ "candidates"
+]compareget_entity1 field changedOutput schema / properties / entity / properties / xAdded value: +{
+ "additionalProperties": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "description": "Indexed instance-specific attributes, grouped by namespace — the same fields api/index.json publishes. Absent when the instance declares none.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}get_latest1 field changedOutput schema / properties / results / items / properties / xAdded value: +{
+ "additionalProperties": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "description": "Indexed instance-specific attributes, grouped by namespace — the same fields api/index.json publishes. Absent when the instance declares none.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}get_related2 fields changedOutput schema / properties / incoming / items / properties / entity / properties / xAdded value: +{
+ "additionalProperties": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "description": "Indexed instance-specific attributes, grouped by namespace — the same fields api/index.json publishes. Absent when the instance declares none.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}Output schema / properties / outgoing / items / properties / entity / properties / xAdded value: +{
+ "additionalProperties": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "description": "Indexed instance-specific attributes, grouped by namespace — the same fields api/index.json publishes. Absent when the instance declares none.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}get_sources10 fields changedInput schema / properties / accessed_sinceAdded value: +{
+ "description": "Only sources accessed on or after this ISO date (YYYY-MM-DD).",
+ "maxLength": 10,
+ "minLength": 4,
+ "type": "string"
+}Input schema / properties / cursorAdded value: +{
+ "description": "Continue from a previous call: pass the next_cursor it returned. Opaque; do not construct one.",
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / hostAdded value: +{
+ "description": "Only sources whose URL is served by this host, compared without a leading www. A source with no URL never matches.",
+ "maxLength": 120,
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / limitAdded value: +{
+ "description": "How many entries to return. Defaults to 25.",
+ "maximum": 200,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / object_id / descriptionPrevious value: -"Restrict the answer to the sources cited by this knowledge object. Omit it to get the instance's whole source registry."New value: +"Restrict the answer to the sources cited by this knowledge object. Omit it to page the whole registry."Input schema / properties / tierAdded value: +{
+ "description": "Only sources of this evidence tier, spelled exactly as get_sources reports it.",
+ "maxLength": 60,
+ "minLength": 1,
+ "type": "string"
+}Output schema / properties / next_cursorAdded value: +{
+ "description": "Pass to the next call to continue. ABSENT means this was the last page.",
+ "type": "string"
+}Output schema / properties / returnedAdded value: +{
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Output schema / properties / totalAdded value: +{
+ "description": "How many sources matched the filters, before paging.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Output schema / requiredPrevious value: -[
- "found",
- "sources"
-]New value: +[
+ "found",
+ "sources",
+ "total",
+ "returned"
+]get_topic7 fields changedInput schema / properties / cursorAdded value: +{
+ "description": "Continue from a previous call: pass the next_cursor it returned. Opaque; do not construct one.",
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / limitAdded value: +{
+ "description": "How many objects to return. Defaults to 25.",
+ "maximum": 200,
+ "minimum": 1,
+ "type": "integer"
+}Output schema / properties / next_cursorAdded value: +{
+ "description": "Pass to the next call to continue. ABSENT means this was the last page.",
+ "type": "string"
+}Output schema / properties / results / items / properties / xAdded value: +{
+ "additionalProperties": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "description": "Indexed instance-specific attributes, grouped by namespace — the same fields api/index.json publishes. Absent when the instance declares none.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}Output schema / properties / returnedAdded value: +{
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Output schema / properties / total / descriptionAdded value: +"How many objects carry this tag, before paging."Output schema / requiredPrevious value: -[
- "tag",
- "results",
- "total"
-]New value: +[
+ "tag",
+ "results",
+ "total",
+ "returned"
+]search5 fields changedOutput schema / properties / results / items / properties / coverageAdded value: +{
+ "description": "Share of the question's information this object accounts for, weighted by term rarity. 1 means every meaningful word in the query is present; a low value with a high score means the object matched common words only.",
+ "type": "number"
+}Output schema / properties / results / items / properties / matched_fields / descriptionPrevious value: -"Which fields the query hit: name, tags, content. Does NOT determine the score on its own."New value: +"Which fields the query hit: name, tags, questions, summary, claims. Does NOT determine the score on its own."Output schema / properties / results / items / properties / score / descriptionPrevious value: -"Text match, weighted by where the token hits (name 3, tags 2, content 1 per query token), plus a centrality bonus of up to 0.9 for objects that other objects point at. That bonus is why two hits can share matched_fields and still score differently: the decimal is inbound edges, not text relevance."New value: +"BM25 relevance: each query term is weighted by how RARE it is in this corpus and by where it hits (name 3, tags 2, questions 2, body 1). A hit must also cover a minimum share of the question's information, measured in the same rarity weights — matching only common words does not qualify. Centrality (how many objects point at this one) breaks TIES ONLY and is never part of the score, so it cannot make an irrelevant object rank. Two hits with the same matched_fields can still differ: the score is rarity-weighted, so matching a rare term is worth more than matching a common one."Output schema / properties / results / items / properties / xAdded value: +{
+ "additionalProperties": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "description": "Indexed instance-specific attributes, grouped by namespace — the same fields api/index.json publishes. Absent when the instance declares none.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}Output schema / properties / results / items / requiredPrevious value: -[
- "id",
- "type",
- "name",
- "summary",
- "tags",
- "evidence_tier",
- "confidence",
- "last_verified",
- "canonical_url",
- "api_url",
- "score",
- "matched_fields"
-]New value: +[
+ "id",
+ "type",
+ "name",
+ "summary",
+ "tags",
+ "evidence_tier",
+ "confidence",
+ "last_verified",
+ "canonical_url",
+ "api_url",
+ "score",
+ "matched_fields",
+ "coverage"
+]answer1 field changedInput schema / properties / question / descriptionAdded value: +"The question to answer, in the words the user asked it."get_entity3 fields changedInput schema / properties / id / descriptionAdded value: +"The knowledge object's id, as returned by search, answer, get_topic or get_related — the last segment of its canonical URL."Output schema / properties / entity / properties / mediaAdded value: +{
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "alt": {
+ "type": "string"
+ },
+ "caption": {
+ "type": "string"
+ },
+ "credit": {
+ "type": "string"
+ },
+ "height": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "id": {
+ "type": "string"
+ },
+ "license_spdx": {
+ "type": "string"
+ },
+ "permissions": {
+ "additionalProperties": {
+ "type": "boolean"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "supports": {
+ "type": "string"
+ },
+ "url": {
+ "type": "string"
+ },
+ "width": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "id",
+ "url",
+ "alt",
+ "credit",
+ "license_spdx",
+ "permissions"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / entity / requiredPrevious value: -[
- "id",
- "type",
- "name",
- "summary",
- "tags",
- "evidence_tier",
- "confidence",
- "last_verified",
- "canonical_url",
- "api_url",
- "questions",
- "claims"
-]New value: +[
+ "id",
+ "type",
+ "name",
+ "summary",
+ "tags",
+ "evidence_tier",
+ "confidence",
+ "last_verified",
+ "canonical_url",
+ "api_url",
+ "questions",
+ "claims",
+ "media"
+]get_latest1 field changedInput schema / properties / limit / descriptionAdded value: +"How many recently verified objects to return, newest verification first."get_overview2 fields changedOutput schema / properties / total_mediaAdded value: +{
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Output schema / requiredPrevious value: -[
- "instance",
- "description",
- "total_objects",
- "by_type",
- "tags",
- "newest_verification",
- "oldest_verification"
-]New value: +[
+ "instance",
+ "description",
+ "total_objects",
+ "by_type",
+ "tags",
+ "newest_verification",
+ "oldest_verification",
+ "total_media"
+]get_related1 field changedInput schema / properties / id / descriptionAdded value: +"The knowledge object to walk out from, by id."get_sources1 field changedInput schema / properties / object_id / descriptionAdded value: +"Restrict the answer to the sources cited by this knowledge object. Omit it to get the instance's whole source registry."get_topic1 field changedInput schema / properties / tag / descriptionAdded value: +"The topic to list, spelled exactly as get_overview publishes it. Every published topic has objects under it, so an empty answer means the topic does not exist."search4 fields changedInput schema / properties / limit / descriptionAdded value: +"How many ranked hits to return, best first."Input schema / properties / query / descriptionAdded value: +"What to look for, in the user's own words. Matched against titles, questions, claim text and tags; accents and apostrophes are ignored, so 'jose' finds 'José'."Output schema / properties / results / items / properties / matched_fields / descriptionAdded value: +"Which fields the query hit: name, tags, content. Does NOT determine the score on its own."Output schema / properties / results / items / properties / score / descriptionAdded value: +"Text match, weighted by where the token hits (name 3, tags 2, content 1 per query token), plus a centrality bonus of up to 0.9 for objects that other objects point at. That bonus is why two hits can share matched_fields and still score differently: the decimal is inbound edges, not text relevance."get_entity1 field changedOutput schema / properties / recoveryAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "available": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "available_count": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "available_truncated": {
+ "type": "boolean"
+ },
+ "did_you_mean": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "hint": {
+ "type": "string"
+ },
+ "next_tool": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "available_count",
+ "available",
+ "next_tool",
+ "hint"
+ ],
+ "type": "object"
+}get_related1 field changedOutput schema / properties / recoveryAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "available": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "available_count": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "available_truncated": {
+ "type": "boolean"
+ },
+ "did_you_mean": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "hint": {
+ "type": "string"
+ },
+ "next_tool": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "available_count",
+ "available",
+ "next_tool",
+ "hint"
+ ],
+ "type": "object"
+}get_sources1 field changedOutput schema / properties / recoveryAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "available": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "available_count": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "available_truncated": {
+ "type": "boolean"
+ },
+ "did_you_mean": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "hint": {
+ "type": "string"
+ },
+ "next_tool": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "available_count",
+ "available",
+ "next_tool",
+ "hint"
+ ],
+ "type": "object"
+}get_topic1 field changedOutput schema / properties / recoveryAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "available": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "available_count": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "available_truncated": {
+ "type": "boolean"
+ },
+ "did_you_mean": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "hint": {
+ "type": "string"
+ },
+ "next_tool": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "available_count",
+ "available",
+ "next_tool",
+ "hint"
+ ],
+ "type": "object"
+}answerget_entityget_latestget_overviewget_relatedget_sourcesget_topicsearchSourced history: 85,753 dated events, each quoted from a citable Wikipedia revision id.
The Laws of the Game and world football's major competitions, every claim cited to primary sources
Normalized search over public-sector tenders in TED (EU official procurement notices) -- Spain + EU
AI legal copilot for foreigners in Spain: immigration and housing rental, cited to Spanish law.
Add one secure layer between your agents and this server.
