finance-foundation

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

No annotations are present, so the description carries the full burden. It discloses that the response contains 'nodes and typed edges' with examples, which is useful. But it does not clarify whether traversal is one-hop or multi-hop, what limits or pagination exist, or how missing entities are handled, leaving several behavioral traits implicit.

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 first defines the tool at a high level with concrete edge-type examples; the second gives a practical usage scenario. Every phrase 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 two-parameter tool with no output schema, the description covers the essential information: what the tool returns, how to invoke it, and a canonical use case. Minor gaps remain, such as traversal depth, explicit support for non-company entity types, and id format, but these are not blocking 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?

With 0% schema description coverage, the description is the only source of parameter meaning. It helps by framing id as an entity identifier and entity_type as the starting entity type (e.g., 'a company'), and it gives examples of target relationship types. It doesn't document every enum value or id format, but the enum in the schema and these examples provide meaningful guidance.

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 operation — 'Knowledge-graph neighborhood of an entity' — and uses the verb 'traverse' with concrete destination examples (exchange, jurisdiction, funds, peers). It also names edge types (lists_on, domiciled_in, managed_by, sector_peer), which clearly distinguishes it from sibling tools like search or lookup that are not graph traversals.

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 includes an explicit use-case directive: 'Use to traverse from a company to its exchange, jurisdiction, funds and peers.' This gives clear context for when to use the tool. However, it does not explicitly mention alternatives or state when not to use it, so it lacks full exclusionary 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?

With no annotations provided, the description carries the full behavioral burden and does so well. It discloses that the operation is LLM-powered, validated against taxonomy and checksum/format rules, read-only, output-only to the caller, and never added to the dataset. It also states the character limit, giving the agent essential side-effect and constraint information.

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 dense but efficiently structured: it opens with the core action, then lists output contents, validation details, side-effect guarantee, and input limit. Every sentence earns its place, with no filler or 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 transformation tool with no output schema, the description does a good job setting expectations: it names the output format, enumerates entity categories, notes validation, and clarifies that results stay with the caller. It could be more explicit about the exact JSON return shape or error behavior for invalid/over-limit input, but the provided detail is sufficient 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% for the single parameter, so the schema already documents the 'text' parameter adequately. The description adds value by mentioning the 6000-char limit and examples of acceptable text (article, filing excerpt, notes), but this is marginal enhancement rather than essential compensation for a coverage 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?

The description states a specific verb ('Extract'), a clear resource ('financial entities and relationships from unstructured text'), and an exact output format ('Finance Foundation Schema v0.1 JSON'). It enumerates the entity types and relational elements, making the tool's purpose unmistakable and distinct from sibling tools like search or lookup.

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 implies when to use this tool: when you have unstructured financial text and want structured entities/relationships. It does not explicitly name alternatives or state when not to use it, but the input constraint ('unstructured text') and transform-only behavior provide sufficient context for an agent to choose it over read-only query 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?

With no annotations, the description carries the behavioral burden; it discloses the default limit and type-specific filter behavior for companies and assets. However, it does not mention pagination, result shape, or behavior for other entity types, leaving notable gaps.

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 with the core operation, including concrete filter and limit details without redundancy. It is concise, though slightly terse given seven entity types and six parameters.

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 plus schema enables basic calls with entity_type, q, limit, and the company/asset filters, but it leaves the remaining four entity types and their parameter applicability undocumented. The lack of an output schema also means return-value semantics are unstated.

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 only 17%, so the description must add meaning; it does clarify q, limit, sector/country for companies, and the type enum for assets. Other params and entity types such as funds, banks, and markets remain unaddressed, and 'type' is only explained in the asset context.

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 clear operation — 'List entities of one type' — and specifies filterable fields for companies and assets. It does not explicitly distinguish itself from sibling tools like search or lookup, but the entity-type scoping makes the purpose reasonably distinct.

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?

No guidance is given on when to use list versus alternatives such as search, lookup, or graph. It explains filtering mechanics but not selection criteria, exclusions, or when another tool would be preferable.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states that data refreshes every 3 hours, includes its source and observation date, and explicitly warns that it is not real-time, preventing a common misunderstanding based on the tool name 'live_data'.

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 value proposition, followed by a precise list of supported data categories and a critical caveat. Every sentence earns its place, and there is no redundant or filler language.

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 no output schema, the description is largely self-sufficient: it names the assets, refresh interval, source/observation-date metadata, and the non-real-time caveat. It does not specify output format or units, but that 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?

The tool has zero parameters and the schema has 100% coverage, so the description does not need to explain parameter semantics. The listing of supported asset categories and symbols adds useful context beyond the empty 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 clearly identifies the tool as a provider of latest reference values across a specific set of crypto, FX, and macro assets. It is unambiguous about the resource, though it lacks an explicit verb and does not differentiate itself from sibling tools by name.

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 refresh cadence and the explicit 'NOT real-time ticks' statement imply when the tool should be used and when it should not, but no alternative tools or explicit selection criteria are mentioned. Usage guidance is present only implicitly.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this exceptionally: it states the data is approximate, versioned ('seed-0.7 · marketcap-1 · 2026-08-30'), not real-time, licensed under CC BY 4.0, and that live_data series refresh every 3 hours. This goes far beyond the structured schema and gives the agent critical context about data freshness and limitations.

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

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

The description is information-dense and front-loaded with the core purpose in the first sentence. Every clause adds meaningful context, though the data-version and license details make it slightly longer than necessary. It is structured well: purpose, behavior, then usage guidance.

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

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

Given the tool has no output schema and no annotations, the description provides strong contextual coverage: what it returns, data quality, license, appropriate use cases, and exclusions. The only minor gap is not fully describing the return structure beyond 'full structured record' and external identifiers, which would be useful at this level of simplicity.

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 50%, with id already documented as an entity slug with examples, and entity_type covered by an explicit enum. The description adds the phrase 'by type and id (slug)' and identifies the resource as a financial entity, but it does little to further explain parameter meaning beyond what the schema already provides. It is adequate but not a significant compensation for the entity_type parameter's missing description.

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

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

The description opens with a specific verb-resource pair: 'Get one financial entity by type and id (slug).' It immediately distinguishes lookup from list/search siblings by emphasizing singular retrieval, and it names the domain (financial entities). This is unambiguous and fully differentiates the tool's purpose.

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 lists correct uses: 'entity resolution, classification, relationships, jurisdiction/venue context.' It also provides a clear when-not: 'For live quotes or legal text go to the primary sources each entity links,' and explicitly notes this tool is 'NOT real-time' while referencing live_data. This gives an agent 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?

With no annotations, the description carries the behavioral burden and adds useful behavior: it returns entities with all identifiers and explicitly ranks matches as exact identifier > ticker > name. It does not cover edge cases like ambiguous names or empty/error responses, but the core behavior is disclosed.

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, front-loaded with the main purpose, followed by a concrete example and a ranking rule. Every sentence contributes information; there is no filler or schema 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?

For a one-parameter tool with no output schema, the description gives input coverage and a sense of the return shape ('Apple with all identifiers') plus match ranking. It is nearly complete, though a bit more about ambiguity handling or output structure would make it fully self-contained.

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 documents the single query parameter with concrete examples, and the description adds semantics by naming the accepted identifier types and the ranking behavior. This goes beyond the schema without merely repeating it.

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 the specific verb 'Resolve' and enumerates the resource types (ticker, LEI, ISIN, FIGI, MIC, name) plus a concrete example. It is clear, though it does not explicitly differentiate resolve_identifier from the sibling lookup/search 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 usage context is implied: pass an identifier or name when you need entity resolution. It does not state when to prefer this over lookup/search, nor does it give exclusions or prerequisites.

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?

With no annotations, the description carries the behavioral disclosure burden. It does state that results are 'grouped matches with links,' which adds useful output-format context, but it does not mention behavior limits, ranking, pagination, result count, or any read-only guarantees. Some behavior is disclosed, but not comprehensively.

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: the first sentence establishes the operation and scope, and the second states the return format. Every word earns its place, with no filler or redundant restatement of the tool name.

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 tool with no output schema and no annotations, the description covers the core operation and the general return shape. However, it lacks guidance on result boundaries, how matches are grouped, and how this differs from nearby tools like lookup or graph, leaving an agent with incomplete context for confident 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 coverage is 0%, so the description must compensate for the undocumented 'query' parameter. It says this is a free-text search, which clarifies that query is a natural-language search string, but it adds no format constraints, length guidance, or examples. The description provides minimal but non-trivial semantic value beyond the bare 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 names a specific verb ('Free-text search') and a clear resource scope ('all entity types') with concrete examples, making the purpose easy to grasp. However, it does not explicitly differentiate itself from sibling tools like lookup or resolve_identifier, aside from the implied breadth of 'all entity types.'

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 implies this is the tool to use for broad, free-text searching across multiple entity types, but it does not state when to prefer it over lookup, resolve_identifier, or list. No explicit exclusions or alternative routing are provided, so the agent must infer usage from the wording.

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