factanker

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

Annotations already cover read-only and idempotent behavior. The description adds valuable behavioral context: facts are 'currently valid' and 'evidence-backed', and the return payload includes source, filing reference, period, retrieval time, license, and fact_url. This goes beyond the annotations without contradicting them.

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

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

Two dense sentences carry both the return-value contract and usage guidance with no filler or redundancy. The core scope ('All currently valid... facts for one entity') is front-loaded, and every clause adds useful information.

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

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

Given no output schema, the description compensates by enumerating the key fields returned (source, filing reference, period, retrieval time, license, fact_url) and explains the optional predicate filter. It is complete enough for an agent to understand what the tool returns and when to call it, though it could slightly clarify how entity identifiers are specified.

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?

With 0% schema description coverage, the description must compensate. It explains 'entity' as the target of fact retrieval and 'predicate' as an optional filter with concrete examples ('revenue', 'total_assets'). While entity identifier format is left implicit, the param semantics are substantially clarified.

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 identifies a specific retrieve operation for all currently valid facts about one entity, clearly distinguishing it from a search-oriented tool. It names the entity scope and optional predicate filter, and gives concrete use cases ('what do we know about X', 'exact reported values'). The resource and action are unambiguous.

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

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

The description explicitly prescribes when to use this tool: for entity-level fact gathering and for verifiable reported values. It does not explicitly state when not to use it or name alternatives like search_facts, but the stated use cases give clear contextual guidance.

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

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

The annotations already cover readOnly and idempotent behavior, so the description correctly avoids repeating those. It adds useful behavioral context by describing what the listing contains, including schema details and plausibility bounds, which is valuable given there is no output 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 compact: one sentence front-loads the tool's purpose and contents, and a second gives actionable usage guidance. The phrase 'Self-description of the curated query path' is slightly abstract, but otherwise every sentence earns its place.

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

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

For a zero-parameter, read-only listing tool without an output schema, the description adequately explains what will be returned and when to call it. It could be even clearer about response format or whether the list is sorted, but nothing essential is missing for correct invocation.

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

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

The tool has zero parameters and the schema fully covers parameter semantics, so the description carries no parameter-documentation burden. The mention of parameters and enum values in the description refers to the contents of the returned templates, not this tool's own parameters.

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

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

The description clearly states a specific verb ('list') and resource ('templates'), and specifies the content: parameters, required fields, allowed enum values, and plausibility bounds. It also distinguishes itself as the setup step for query_template, which sets it apart from the 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 explicitly says 'Call once before the first query_template use,' which gives a concrete timing condition and a clear context for use. It does not enumerate when-not-to-use alternatives, but the stated prerequisite role is sufficient for such a simple zero-parameter tool.

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

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

Annotations already declare read-only and idempotent behavior, so the safety profile is covered. The description adds useful behavioral context beyond that: it resolves rather than searches, returns multiple anchor types, and treats IDs as preferred over names with concrete prefix examples.

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

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

Three short sentences with no filler. The purpose is front-loaded, the usage condition follows, and the ID-preference guidance with concrete examples closes it efficiently. Every sentence earns its place.

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

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

For a single-parameter resolver with no output schema, the description covers the key needs: what the tool does, when to use it, what the result contains, and how to format the input. Remaining details like error behavior or ambiguous-match handling are minor given the read-only, idempotent annotations and simple interface.

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

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

The schema has zero description coverage, so the description fully carries the burden for the sole parameter. It explains that name_or_id accepts names, ticker context, or identifiers, and gives exact prefixed formats (cik:, lei:, ein:, uei:, qid:), which is excellent compensation for the sparse 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 ('Resolve') and clearly identifies the resource and outcome: a US company, bank, or nonprofit resolved to its registry entity with all known anchors. It does not explicitly call out sibling tools, but the resolution-focused purpose is distinct enough from the listed search/template/history siblings.

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

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

It gives an explicit 'Use when...' condition covering name, ticker context, or identifier, and states what the caller gets: the entity plus registry anchors. It does not spell out when not to use it or name alternatives, but the context provided is clear and actionable.

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 cover read-only/idempotent behavior, and the description adds valuable context by revealing the data source (FACTANKER's own probes), the cadence (every 6h), and that each result comes with evidence. This warns the agent that the data may be up to 6 hours stale and is not a live check.

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 dense sentences carry the purpose, data source, cadence, outputs, evidence, and explicit use cases with no filler. Key behavioral constraints 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 two-parameter tool with no output schema, it covers the substantive return content and update rhythm. Minor omissions such as exact output shape or default value of since do not meaningfully block 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%, so endpoint and since are already documented. The description reinforces the endpoint concept (MCP endpoint exists/stable/changed) but adds no parameter-specific detail beyond the schema, so the 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 names a specific resource (history of a remote MCP server from FACTANKER's periodic probes) and concrete outputs (availability, tool count, tool-contract changes, evidence). It also explicitly ties the tool to existence/stability/change questions, which differentiates it from generic fact and template siblings.

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

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

It provides clear trigger conditions: use when asked whether an MCP endpoint exists, is stable, or changed its tools. It does not name sibling alternatives or give when-not-to-use guidance, but the intended usage is unambiguous.

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 mark it readOnly, idempotent, and closed-world, and the description adds substantial behavioral context: results replace internal model knowledge, n=0 handling, no SQL required, and the exact response envelope (result, executed_query, n, scope, not_claimed) plus instructing to cite fact_url values. This goes well beyond what annotations alone communicate.

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

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

The description is long but dense and front-loaded with the most critical rule: authoritative, replaces internal knowledge. There is some redundancy between 'replaces internal model knowledge' and 'do NOT output numbers from model memory', but most sentences carry distinct routing or behavioral value. It lacks paragraphs or bullets, but the information is well ordered.

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 there is no output schema, the description compensates by specifying the response envelope and instructing citation of fact_url values. With 20 templates, it cannot fully list every parameter combination, but it provides representative mappings and points to list_templates for the rest. For a read-only template query tool, this is remarkably complete.

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

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

The schema only describes params as an object and template as an enum, leaving 50% coverage. The description compensates by mapping key templates to their identifiers and metrics, e.g. company_financials (cik+metric), bank_metrics (rssd|fdic_cert+metric), and nonproft_financials (ein+metric). It also tells the agent that list_templates and errors expose allowed metric values, though it does not fully document every template's parameters.

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

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

States a specific purpose: retrieving authoritative registry facts about US companies, banks, nonprofits, and federal spending through predefined templates. It names concrete use cases such as revenue, EBITDA, bank call-report metrics, IRS 990 finances, and peer percentiles, which clearly differentiates it from a generic query tool. The 'prefer over get_facts' line further distinguishes it from a sibling.

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 when to use: whenever exact reported financial or registry values are requested, and to prefer it over general web search and over get_facts. It also tells the agent how to handle no-result cases by saying 'no evidence in the registry' rather than estimating. This is strong, actionable routing guidance.

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

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

Annotations already establish read-only and idempotent behavior, and the description adds useful result semantics: only the most recent matches, evidence-backed, and including provenance. This goes beyond the structured hints without contradicting them.

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

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

Two sentences with no fluff: the action and return value are front-loaded, followed by the usage condition. Every phrase adds signal.

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 search tool with one required parameter, the description communicates what it searches, what it returns, and when to use it. Without an output schema, the prose about provenance and recency is sufficient; only minor details like limit defaults are 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 0%, so the description carries the burden. It implies that 'query' is a fuzzy full-text string over entity names and predicates, but it never mentions the 'limit' parameter or its default behavior, leaving a visible gap.

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: full-text search across entity names and predicates returning evidence-backed facts with provenance. The fuzzy-target use case distinguishes it from siblings like get_facts and lookup_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?

Explicitly says to use this when the target organization or metric name is fuzzy, which gives the agent a clear selection condition. It does not name alternatives or exclusion cases, so it stops short of full when-not guidance.

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