Fintel Discovery — Financial Intelligence for AI Agents

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety burden is covered. The description adds genuine context: SEC EDGAR source, no API key required, one record per position, and the _has_more pagination signal. It doesn't discuss rate limits or caching, but it goes meaningfully 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?

Front-loaded with purpose, then a labeled field list, then usage notes in short imperative sentences. The per-field return list is somewhat long and partly redundant with the output schema, but the structure keeps it scannable.

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 parsed-filing tool with an output schema and annotations, the description covers prerequisites, pagination, filtering, and source. The only substantive gap is the undocumented secondary parameters, which the description never acknowledges.

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 description explains min_value_thousands, sort_by, limit/offset, and the cik/accession_no inputs well. However, it is silent on several schema fields bundled into the params object (wholesaler_ids, exclude_fillers, source_resource_id, optional_additional_filters, mcp_prompt_id), leaving their relevance to this EDGAR tool unexplained.

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+resource+scope: 'Fetch and parse the complete equity holdings table from a specific SEC 13F-HR filing.' It also positions itself relative to siblings by naming SearchEdgar13F and GetEdgarCompanyFilings as the discovery step that feeds this 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?

Explicit routing is given: 'PRIMARY USE: Step 2 of institutional holdings workflow... Obtain cik and accession_no from SearchEdgar13F or GetEdgarCompanyFilings, then call this tool.' It also tells the agent when to filter (min_value_thousands), how to sort, and how to paginate with limit/offset and _has_more.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely useful non-obvious context: no API key is required and the data is embedded curated static reference material (2023–2024), which tells the agent results are fixed rather than live-queried.

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?

Front-loaded with the purpose, then a scannable bulleted category list, then source and access notes. It is somewhat long for a single meaningful parameter, and the 'all' default is stated twice (in prose and within the category list), but nothing is wasted enough to hurt readability.

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 an output schema present, return values need not be described, and the description covers source, vintage, category granularity, and access requirements. The only material gap is that the pass-through plumbing parameters are never mentioned, which an agent relying on the description alone would not know about.

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 reported as 0% at the parameter level, so the description must carry the burden. It explains the primary `category` parameter's options and default, but that same enum list already appears in the nested schema, and the remaining nested params (wholesaler_ids, source_resource_id, question_asked, exclude_fillers, additional_display_fields) are entirely unexplained.

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 ('Return Kitces Research advisor practice benchmark data') and scopes it precisely to independent and RIA-affiliated advisors. The enumerated categories make it unmistakably distinct from siblings like GetFundFees or GetTerritoryWealthProfile, which return entirely different data.

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

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

Gives clear usage context: it is a static reference lookup sourced from the 2023–2024 Kitces survey, and it tells the agent that category='all' (the default) retrieves everything. It does not name alternatives or state when not to use the tool, but no sibling covers this data, so the missing exclusion is minor.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, so the safety profile is covered. The description usefully adds the data source (Yahoo Finance via yfinance) and that no API key is required, which is real operational context. Beyond that it discloses little new behavior, and the elaborate wholesaler_ids / source_resource_id caching semantics in the schema are not echoed here.

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?

Front-loads the core output (consensus, targets, history) then the usage bullets, then the source. Well-structured and mostly tight, though the bullet list repeats capabilities already stated in the opening sentence.

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

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

An output schema exists, so return values need not be explained. However for a tool with a symbol defaulting to null, the description never says what happens if symbol is omitted, and the odd wholesaler/caching parameters (clearly from a different domain) are left unexplained relative to an analyst-ratings 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?

Reported coverage is 0% but the nested schema actually carries rich descriptions for symbol, wholesaler_ids, source_resource_id, include_upgrades_downgrades, etc. The description adds only the upgrade/downgrade content semantics, duplicating the include_upgrades_downgrades field. Baseline 3 for a schema that does the heavy lifting.

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: fetching analyst consensus ratings, price targets, and upgrade/downgrade history with named fields (firm, fromGrade, toGrade, action). This clearly distinguishes it from siblings like GetFinancials or GetTickerInfo. It lacks an explicit 'unlike X tool' contrast, so it stops short of 5.

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 three explicit 'Use this tool when' scenarios that map to the consensus, price-target, and rating-change use cases. It defines when to use but does not name an alternative tool or an exclusion case (e.g., distinguishing from a general ticker-info 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 readOnly/idempotent/non-destructive/openWorld=false. The description adds useful non-annotation context: the data source (FINRA BrokerCheck public API) and that no API key is required. It omits rate limits and result-size/pagination behavior, so not quite full marks.

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?

Front-loaded purpose sentence followed by tightly scoped bullets and a source note; every line carries information. Slightly long for a single-parameter tool but no wasted prose.

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 an output schema present, return values needn't be detailed, and the description still previews the payload (employment history, exams, licenses, disclosures). Missing only failure modes and behavior when the CRD is invalid.

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 reported at 0% for the top-level params object, so the description carries some burden; it explains the key 'crd' parameter's origin (from SearchBrokerCheck) and example format is left to the schema. It says nothing about the other exposed fields (wholesaler_ids, source_resource_id, exclude_fillers, mcp_prompt_id), which are unrelated-looking and unexplained at the description level.

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 ('Retrieve the full FINRA BrokerCheck profile for one individual using their CRD number') and enumerates the returned content. It is clearly distinguishable from the sibling SearchBrokerCheck, which only searches rather than returns full profiles.

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 'Use this tool when' bullets give clear context (you have a CRD from SearchBrokerCheck, need employment/qualm data, doing due diligence). It routes the agent from the sibling search tool but never states an explicit when-not or a case where IAPD detail tools would be preferred.

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 carry readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile needs no restatement. The description adds genuinely useful non-structured context: the data source (Yahoo Finance via yfinance) and that no API key is required, which tells the agent about auth and data provenance.

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?

Front-loaded with purpose, then return shape, then a scannable bulleted usage block, then source. Slightly padded by leading/trailing whitespace and line breaks, but every sentence carries 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?

An output schema exists, so the brief return-field note is sufficient and no return-value detail is owed. Purpose, usage triggers and data source are all covered; only per-parameter guidance is absent, and the nested schema largely fills that gap.

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

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

The report flags 0% schema description coverage at the top level, and the description mentions no parameter names, formats or defaults. However, the nested DividendsAndSplitsParams $defs do describe period, symbol and the other fields in detail, so the agent is not left blind; the description itself simply adds nothing here.

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 ('Fetch the full history of cash dividends, stock splits, and combined corporate actions for a ticker') and names the returned fields. This distinguishes it cleanly from siblings like GetPriceHistory and GetEarningsHistory.

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 'Use this tool when' block gives three concrete scenarios (dividend history/yield inputs, dividend growth research, split verification for returns). It gives clear positive context but never names an alternative tool or a when-not-to-use condition.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful context beyond those annotations: the data source (Yahoo Finance via yfinance), that no API key is required, and the three return sections.

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 capability, then use cases, then return structure and source. It is appropriately sized with no redundant filler.

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

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

An output schema exists, so explaining return values is not strictly required, but the description helpfully names the three returned sections. It is complete enough for the core earnings-history use case, though it does not address the broader set of schema parameters.

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 0% according to the context signals, and the description does not mention any parameter such as symbol, limit, wholesaler_ids, or source_resource_id. It therefore fails to compensate for undocumented parameters and leaves the agent with no description-level guidance on invocation arguments.

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 set: fetch earnings history (EPS actual vs estimate, surprise %), upcoming earnings dates with consensus estimates, and forward EPS estimates. It is clear about what the tool does, though it does not explicitly name sibling alternatives such as GetFinancials or GetAnalystRatings.

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 this tool when' list covering performance vs expectations, next earnings date, and surprise trend analysis. It does not state when not to use this tool or name alternative tools for overlapping needs.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint=false. The description adds useful context: it returns every filing on record with specific fields, notes the data source (SEC EDGAR API), and confirms no API key is required. It does not cover rate limits or pagination, but the annotation coverage lowers the burden.

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 action and return details, followed by a clean bulleted list of use cases and a helpful CIK lookup link. It is slightly repetitive in stating 'all filings' twice, but overall it is well-structured and each element serves a purpose.

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

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

An output schema exists, so return values need not be fully explained, yet the description still summarizes them helpfully. It covers when to use the tool and how to find a CIK. It omits pagination and rate-limit details, but for a read-only SEC EDGAR lookup with annotations and an output schema, it is largely 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?

Schema description coverage is reported as 0% for the top-level parameter, so the description should compensate. It explains the primary CIK parameter and provides a lookup URL, which adds value. However, it does not address the nested optional parameters (e.g., wholesaler_ids, source_resource_id, additional_display_fields), leaving some semantic gaps.

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 ('Retrieve all SEC filings') and resource ('for a company or institution using its CIK'), and it clearly distinguishes itself from siblings like Get13FHoldings or SearchEdgar13F by covering all filing types rather than a specific form.

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 explicit 'Use this tool when' conditions, including having a CIK, tracking filing activity, and needing accession numbers. It does not explicitly name alternatives or when-not-to-use cases, but the context 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the data provenance (Yahoo Finance via yfinance, no API key), the volume/shape of results (up to 4 years annual or 4 quarters, transposed by reporting period), and the 'trailing is income-only' constraint. These are genuine additions, though the transposition detail partially overlaps an existing 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?

Front-loaded with the core action, then a scannable bullet list, then option/format quirks, then source attribution. Every block earns its place, though the option lists in the body duplicate the schema's field descriptions and could be trimmed.

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

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

An output schema exists, so return-value explanation is not strictly required, yet the description still characterizes result volume and orientation. Combined with provenance and the frequency caveats, an agent has enough to call this correctly; the unexplained auxiliary filter params are the remaining gap.

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

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

Schema description coverage is reported at 0%, but the description compensates only for the two user-facing params, restating the 'statement' and 'freq' option sets that the schema's own field descriptions already enumerate. The many auxiliary params (mcp_prompt_id, wholesaler_ids, source_resource_id, exclude_fillers, etc.) are neither explained nor hinted at, and the trailing/TTM income-only caveat is the single piece of real added meaning.

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 first sentence names a specific verb (Fetch) and resource (income statement, cash flow statement, balance sheet for a stock), which is unambiguous. It does not explicitly name or contrast with siblings such as GetEarningsHistory or GetDividendsAndSplits, so differentiation is left to the agent.

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 'Use this tool when:' block gives four concrete triggers (revenue/EPS, cash flow/CapEx, assets/debt/equity, fundamental analysis), which is strong positive guidance. It provides no when-not conditions and names no alternative tool, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful non-annotation context: the return shape (date + value pairs with title/units/frequency metadata) and an auth prerequisite (FRED_API_KEY, with where to get it). It does not cover rate limits or pagination behavior.

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

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

Front-loads the core action, then routes to the prerequisite tool, then lists trigger scenarios, then parameter usage, then environment requirement. Every sentence carries information; the only mild redundancy is restating the FRED source.

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 an output schema present, return values needn't be explained, yet the description still summarizes them. Auth requirement, prerequisite tool, scoping params, and trigger scenarios are all covered — 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 description adds operational meaning for the key FRED parameters — observation_start/observation_end to bound the range and frequency to aggregate (with 'm'/'q' examples) — which the top-level schema does not surface. It does not address the boilerplate-looking params (source_resource_id, wholesaler_ids, exclude_fillers), though those appear unrelated to FRED fetching.

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

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

States a specific verb (Fetch) and resource (time-series observation data from FRED) and immediately disambiguates from the sibling SearchFredSeries. An agent can distinguish this from the other ~30 lookup/fetch tools without opening the schema.

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

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

Provides an explicit 'Use this tool when' list of scenarios (macro data, advisor/fund context, cross-period comparison, current indicator values) and names the alternative with its condition: 'Use SearchFredSeries first if you don't know the series ID.' Nothing is left to inference.

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 readOnly/idempotent/non-destructive annotations already covering the safety profile, the description adds real behavioral context: the data source and API-key-free access, the enumeration of returned fields, the include_all_classes row-multiplication behavior, and the error condition when no XBRL rr: data is filed. It stops short of stating latency, caching, or CIK-not-found behavior, so not a full 5.

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?

Front-loaded with the core action and a clean bulleted field list, then use-case and notes. Most sentences earn their place, though the return-field enumeration overlaps with the existing output schema and adds length the agent may not need.

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, output-schema-backed tool the description is near-complete: workflow position, data source, defaults, and fallback are all covered. The main gap is that the ancillary session/filter parameters bundled in the schema go unmentioned, leaving the agent to infer their role.

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 description explains the semantics of cik (zero-padding handled) and include_all_classes (all share classes vs. single latest value) in prose beyond the schema. However, several declared parameters (wholesaler_ids, exclude_fillers, source_resource_id, additional_display_fields, optional_additional_filters) are never addressed, and the reported schema coverage is low, so the description does not fully compensate.

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 (retrieve expense ratios and fee breakdown for a mutual fund/ETF) and identifies the exact data source (SEC XBRL rr: taxonomy via CIK). It clearly distinguishes itself from siblings by naming GetFundProfile as the fallback and SearchFundsByCategory as the feeder.

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 frames the tool as 'Step 2 of fee comparison', tells the agent to accept CIKs from SearchFundsByCategory, run across multiple funds, and rank by net_expense_ratio ascending. It also names the when-to-switch condition: if XBRL rr: data is missing, use GetFundProfile (yfinance) instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds useful provenance ('Source: Yahoo Finance via yfinance. No API key required.'), but it is silent on the internal scoping behavior implied by wholesaler_ids and the caching behavior of source_resource_id, which materially change what data comes back.

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?

Front-loaded with what the tool returns, then when to use it, then the section enum, then the scope restriction and source. Every block is scannable. Minor waste: the section list is restated in the schema, and the source/no-API-key line is a trailing note.

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 an output schema present, return-value detail is correctly omitted, and the description covers scope, alternatives, and section selection adequately for a read-only fetch. The gap is the unexplained internal scoping/caching parameters, which an agent may otherwise ignore or misuse.

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 description enumerates the section values ('overview', 'holdings', 'sectors', 'bond_ratings', 'equity_holdings', 'all'), which is the single most decision-relevant parameter, and that is real added value. However, it says nothing about symbol, and says nothing about the fin-internal parameters (wholesaler_ids, source_resource_id, additional_display_fields) that the schema surfaces; with reported coverage at 0% the description only partially compensates.

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

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

Specific verb+resource ('Fetch ETF or mutual fund specific data') with an enumerated payload (holdings, sector allocations, expense ratio, credit quality, style). It explicitly carves itself out from the sibling GetTickerInfo by stating 'Only works for ETFs and mutual funds. For stocks, use GetTickerInfo.' An agent can disambiguate without opening the schema.

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

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

Contains an explicit 'Use this tool when:' block with four concrete trigger conditions (top-10 holdings, sector breakdown, bond rating distribution, fund comparison) plus an explicit exclusion routing to GetTickerInfo for stocks. This is the when-to-use / when-not-to-use pattern done fully.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so safety and idempotency are covered structurally. The description adds genuinely useful provenance (Yahoo Finance via yfinance, no API key required) but says nothing about latency, caching, or coverage limits, which matters for an external-source fetch.

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?

Front-loaded purpose sentence followed by a tight bulleted usage block and a one-line enum listing plus source note. Every element is relevant to invocation; the only waste is restating holder_type values already in 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?

An output schema exists, so return-value explanation is not required, and annotations carry the safety profile. However, the schema exposes a set of fin-internal filtering parameters (wholesaler_ids role semantics, source_resource_id cache reuse) that the description never acknowledges, leaving the agent to infer how they interact with a simple stock-ownership lookup.

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 description repeats the holder_type enum ('institutional', 'mutualfund', 'insider', 'all') that the schema already defines, and mentions no other parameter. Coverage for the many unrelated-looking fields (wholesaler_ids, exclude_fillers, source_resource_id, mcp_prompt_id, question_asked) is zero in the description, leaving complex behavior undocumented in prose.

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+resource ('Fetch ownership data for a stock') and enumerates the three data categories returned: institutional holders, mutual fund holders, and insider transactions. It does not explicitly distinguish itself from the closely related sibling Get13FHoldings, so it stops short of a 5.

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 'Use this tool when' block gives three concrete triggering scenarios (institutional/fund ownership, insider buying/selling, ownership concentration). That is clear usage context, but no when-not guidance or explicit routing away from siblings like Get13FHoldings or SearchEdgar13F.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: the data source (SEC IAPD public API) and the fact that no API key is required, plus a summary of what the response contains.

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?

Front-loaded with the core action in the first sentence, then a bulleted usage block and a one-line source note; nothing is padded. The bullets are slightly repetitive with the opening sentence but earn their place as routing cues.

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

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

An output schema exists, so return values need not be spelled out, and the description nevertheless summarizes the ADV Part 1 sections returned. Source, key requirement, and prerequisites are all present; only the auxiliary request parameters are left unexplained.

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 description only speaks to the CRD ('by its CRD number'), which the schema already documents with an example and provenance. The remaining nested parameters (wholesaler_ids, source_resource_id, exclude_fillers, etc.) are not addressed in the description at all; the $defs entries do describe them, so the description adds little beyond the structured fields.

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 ('Retrieve the full Form ADV filing detail for one RIA firm by its CRD number') and enumerates the payload (client types, advisory activities, fee arrangements, custody, offices, affiliates). This cleanly separates it from the sibling SearchIAPDFirm search tool, which is named as the upstream source of the CRD.

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?

An explicit 'Use this tool when:' block gives three concrete conditions (you have a CRD, you need offices/custodians/affiliates, you're building a prospect profile), and it names SearchIAPDFirm as the prerequisite source. It stops short of stating when NOT to use it (e.g., individual reps belong in GetIAPDIndividualDetail), so it is strong but not fully routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds real context beyond them: the data source (api.adviserinfo.sec.gov) and that no API key is required, which helps the agent understand availability and provenance.

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?

Front-loads the core action in the first sentence, then uses a compact bulleted when-to-use block and a one-line source note. Every sentence earns its place and the scanning order is optimal.

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

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

An output schema exists, so return values need not be documented, and the annotations fully cover the read-only/idempotent safety profile. With the key input and its source explained, nothing an agent needs to invoke this 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?

Schema coverage registers as 0% and the nested params object carries several fields, but the description names the one operationally significant input (the CRD number) and its origin. The remaining parameters are generic MCP/session plumbing, so the description compensates adequately for the single meaningful argument, though it does not cover the filter/cache fields.

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?

Names a specific verb (Retrieve) plus resource (full SEC IAPD profile for one individual advisor representative) and the exact identifier (CRD number). It also enumerates the returned content (registration history, exam qualifications, employment history, disclosures), making it clearly distinguishable from SearchIAPDIndividual and nearby firm/entity 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 an explicit 'Use this tool when' list including the precondition (you already have a CRD from SearchIAPDIndividual) and the use case (deep due diligence on an IAR). It routes the agent to the sibling that produces the required input, though it stops short of stating when not to use it (e.g., for searching).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds useful behavioral context beyond annotations: the source is the GLEIF API, no API key is required, and the response includes legal name, status, addresses, LOU, and renewal dates.

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 purpose, then a return-field summary, then clear usage bullets, then source details. Every section is brief and useful for selecting and invoking the tool, with no filler.

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

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

For a simple single-entity lookup with rich annotations and an output schema, the description provides enough context to call the tool correctly. It covers source, usage, and the LEI parameter, though it omits edge cases such as invalid or missing LEI handling.

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 reported as 0%, so the description must compensate. It specifies that the key input is a 20-character LEI code and directs the agent to obtain it from SearchLEI, which is sufficient for the primary lookup parameter, though it does not explain the optional wrapper/filter fields in the schema.

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

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

The description states a specific verb and resource: retrieve the full GLEIF LEI record for one legal entity using a 20-character LEI code. It also distinguishes the tool from SearchLEI by noting that a LEI is already required and that SearchLEI is the source for obtaining one.

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 concrete usage triggers in a bullet list: having a LEI from SearchLEI, verifying registration status, and needing legal address or jurisdiction. It does not explicitly state when not to use the tool or name a direct alternative for full detail, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine context beyond them: data source (Yahoo Finance via yfinance), that no API key is required, and the flattened multi-ticker output layout.

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?

Front-loads the core capability, then uses a compact bulleted 'when to use' block and a symbol-format example. Every element earns its place; the only minor slack is the example duplicating 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?

With an output schema present, return values need not be explained, and the description still supplies source, format, and selection guidance. Coverage is solid for a read-only lookup tool, though it ignores the auxiliary filtering params entirely.

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 description restates the symbols format ('AAPL MSFT GOOGL' / 'SPY,QQQ,IWM'), which the schema already documents verbatim, adding no new meaning. The many other params (period, interval, wholesaler_ids, source_resource_id) are documented in the schema but not addressed in the description, so it neither compensates for nor extends them.

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+resource (fetch OHLCV price history) and scopes it explicitly to multiple tickers 'in a single call,' which cleanly distinguishes it from the sibling GetPriceHistory for a single symbol. It also names the return shape (flattened table with 'AAPL_Close', 'SPY_Volume' columns).

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 an explicit 'Use this tool when:' list covering cross-security comparison, correlated portfolio data, and correlation matrices. It gives clear positive selection criteria but never names the single-ticker sibling (GetPriceHistory) as the alternative, so the boundary is implied rather than stated.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered; the description adds the data source (Yahoo Finance via yfinance, no API key) and the fallback behavior for a missing expiry. It does not mention rate limits, data freshness, or chain size, which keeps it short of a 5.

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?

Front-loaded with the core action, then a tight bulleted usage list, prerequisites, and default behavior. No sentence is filler and the structure makes scanning trivial.

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

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

An output schema exists, so return-value detail is not strictly required, and the description still names the key fields. The remaining gap is the unexplained extraneous schema parameters, which an agent could stumble over; otherwise the definition 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?

The description adds real meaning for expiry_date (format expectation via the prerequisite call, nearest-expiry default), but the schema surfaces several additional parameters (wholesaler_ids, exclude_fillers, source_resource_id, additional_display_fields) that the description never mentions or reconciles. With schema coverage reported at 0% and unaddressed parameters, this is adequate but incomplete.

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 ('Fetch the full options chain (calls and puts) for one expiry date') and enumerates the returned fields (strike, bid, ask, IV, open interest, volume). It is clearly distinguishable from the sibling GetOptionsExpirations, which it explicitly routes to.

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 an explicit 'Use this tool when' list covering three concrete scenarios (options strategy research, IV across strikes, open interest sentiment), states the prerequisite ('Call GetOptionsExpirations first'), and documents the default case when expiry_date is omitted.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorldHint=false, so the safety profile is covered. The description usefully adds the data source (Yahoo Finance, no API key required), but says nothing about output shape, ordering, or empty-ticker behavior. Adds some value on top of annotations, but not rich behavioral context.

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?

Front-loaded purpose sentence, then a tight bulleted usage block, then a one-line source note. Every sentence earns its place and the ordering constraint appears early.

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?

Output schema exists so return values need no explanation, and annotations cover the safety profile. The boilerplate params (mcp_prompt_id, wholesaler_ids, source_resource_id) are undocumented in the description, but they are generic plumbing rather than tool-specific semantics.

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 reported as 0%, but the nested parameter schema in fact carries extensive descriptions; the description itself only implies a ticker input ('for a ticker') without naming or constraining the symbol parameter. Baseline 3 is appropriate since the structured schema does the heavy lifting.

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 all available options expiry dates for a ticker') and explicitly distinguishes itself from the sibling it feeds into, GetOptionsChain. An agent can identify the tool's role without opening any schema.

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

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

Gives explicit when-to-use conditions (discovering which contracts exist, needing an expiry to pass downstream) and names the dependent tool and the ordering ('Use this before calling GetOptionsChain'). Nothing is left to inference.

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 the safe read-only, idempotent, non-destructive profile, and the description adds useful context: the data source (Yahoo Finance via yfinance), the fact that no API key is required, and the lookback ceilings for intraday and hourly intervals. It stops short of describing what the returned bars look like in edge cases (e.g. empty ranges for delisted tickers).

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?

Front-loaded with the core purpose, then a scannable bulleted when-to-use list and a compact interval/period reference. No sentence is wasted and the structure matches how an agent consumes the definition.

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

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

An output schema exists, so return-value detail is not required, and the description covers the interactive essentials (source, constraints, use cases). The only meaningful gap is the absence of an explicit pointer to GetMultiTickerHistory for multi-ticker requests.

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 description restates the interval and period option sets and adds the intraday (60-day) and hourly (730-day) caps, but it does not cover symbol, actions, or auto_adjust, and the option lists largely duplicate the schema descriptions. It adds marginal value beyond the schema rather than compensating for the reported 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?

States a precise verb and resource ('Fetch OHLCV price history for one ticker') and immediately scopes it to a single ticker, which implicitly distinguishes it from the sibling GetMultiTickerHistory. An agent can identify the tool's job without opening the schema.

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

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

Provides a clear 'Use this tool when' block listing three concrete scenarios (historical price/volume, performance over a range, returns/volatility/trend analysis). It never explicitly names GetMultiTickerHistory as the alternative for multi-ticker requests, so the routing condition is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds useful context: the required cenpy package, the optional free API key, and rate-limited fallback behavior when unauthenticated. That's real operational context beyond annotations, but the 'wholesaler_ids' and 'exclude_fillers' parameters hint at a completely different (fin/wholesaler) data model that the description never reconciles.

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?

Well-structured: metric list, then usage prompts, then requirements. Slightly verbose with the full Census variable code list, but every section is front-loaded and scannable. Minor bloat from repeating 'median_hh_income' style field names and prompt documentation.

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?

Has an output schema so return value explanation is not strictly needed, and the target audience (financial advisors scoring territory wealth) is clear. However, with a 0% schema coverage on a weirdly mixed parameter set, the description leaves an agent unable to know whether wholesaler_ids/exclude_fillers apply here or are inherited cruft.

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 0% across a parameter set that includes confusing fields (wholesaler_ids, exclude_fillers, source_resource_id) seemingly unrelated to Census data. The description names only state and zip_code implicitly and never explains how to use the fin-internal params or even whether they apply to this Census tool. With a 0% coverage gap, the description should compensate but does not.

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 (Retrieve) and resource (US Census ACS income and wealth proxy data) with the exact entity scoped (ZIP code or state). No sibling tool touches Census ACS wealth data, so it's clearly differentiated. The enumerated key metrics reinforce the 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?

Provides an explicit 'Use this tool when' block with three concrete scenarios (scoring a territory, comparing income distribution, demographic proxy before AUM overlay). Strong context, though it names no alternative tool and gives no when-not-to-use 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing the data source ('Yahoo Finance via yfinance'), that no API key is required, and the shape of the return (60+ metadata fields), though it omits rate limits or caching behavior.

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

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

Front-loaded with the core action, then organized into scannable 'Use this tool when' and 'Works for' sections plus a source note. Every line is relevant, with only minor redundancy between the return-field sentence and 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 metadata fetch with an output schema present and safety fully covered by annotations, the description supplies everything an agent needs: purpose, target asset classes, symbols, source, and auth expectation. The only residual gap, the extraneous schema parameters, does not affect correct invocation for a ticker lookup.

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 description's ticker-format guidance matches the symbol parameter but duplicates what the schema already documents, and it says nothing about the many other nested params (wholesaler_ids, source_resource_id, exclude_fillers, etc.) that appear unrelated to a Yahoo Finance lookup. With coverage reported at 0%, the description only partially compensates for the undocumented 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 verb and resource ('Fetch the full Yahoo Finance profile') and enumerates the asset classes and the fields returned (sector, industry, market cap, P/E, etc.). It clearly conveys what the tool produces, but never names or contrasts against siblings like GetFundProfile, LookupTicker, or GetFinancials, so an agent must infer differentiation.

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 an explicit 'Use this tool when:' list covering three concrete scenarios (quick summary, sector/industry classification, price metadata). This gives clear context for use, but offers no when-not guidance and points to no alternative sibling for cases like detailed financials or fund-specific data.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description meaningfully adds the data source ('Yahoo Finance via yfinance'), that no API key is required, and the shape of the return (symbols with exchange and asset type). It does not discuss rate limits or result ordering, but the added context is genuinely useful.

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?

Core purpose and usage guidance are front-loaded, followed by a scannable bullet list and a source note. The bullet list is slightly redundant with the leading sentence but each line adds routing value; no significant filler.

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

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

An output schema exists, so return values needn't be explained, and annotations cover the safety profile. Purpose, usage, and the key query/asset_type semantics are present, making it complete enough for a read-only lookup tool; the unexplained boilerplate parameters are the only gap.

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

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

The description restates the asset_type options and implies the query semantics, but this largely duplicates what the schema's $defs already document for query, asset_type, and max_results. It adds nothing about the many boilerplate parameters in the schema (wholesaler_ids, source_resource_id, mcp_prompt_id, etc.) that appear irrelevant to a ticker lookup, so the description does not compensate for the reported low top-level coverage.

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

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

The description names a specific verb and resource: 'Search for a Yahoo Finance ticker symbol by company name, fund name, or keyword.' An agent can immediately tell what it produces (matching symbols with exchange and asset type). It does not explicitly name or distinguish itself from close siblings such as GetTickerInfo, MapInstrumentIds, or SearchFigiInstruments, so it stops short of a 5.

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 this tool when' block with three concrete scenarios (name-but-not-symbol, ETF/mutual fund lookup, disambiguating similarly named securities), which is clear routing guidance. It stops short of naming alternatives (e.g., when to use GetTickerInfo instead) or giving explicit when-not conditions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds valuable context beyond that: it names the source (Bloomberg OpenFIGI API), states no API key is required, and notes an optional key raises rate limits. It omits error/batch behavior and limits, so not a full 5 given the API-backed nature of the tool.

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?

Front-loads purpose, then usage scenarios, then the idType value list and source note. Well-structured and largely waste-free, though the segmented bullet layout is slightly long for the core action.

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?

Covers what the tool does, when to use it, supported idType values, exchange targeting, and auth/rate-limit behavior. With an output schema present, return values need not be explained. The only gap is the unexplained fin-specific parameters that appear inconsistent with the tool's declared purpose.

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 reported as 0% at the top level, but the description documents the key semantic parameters: idType enum values with examples, idValue, and exchCode usage. It compensates well for the schema, though it doesn't cover the many fin-specific params (wholesaler_ids, source_resource_id, etc.) which appear irrelevant/copied and undocumented.

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+resource: mapping financial instrument identifiers between ID systems via OpenFIGI, naming the exact ID conversions (ticker, ISIN, CUSIP, FIGI). Distinguishes from the sibling SearchFigiInstruments by being the conversion tool rather than a search 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 an explicit 'Use this tool when' list with three concrete scenarios (ticker→ISIN/CUSIP, normalizing IDs across EDGAR/Yahoo, identifying exchange). This clearly routes the agent against alternatives like LookupTicker and SearchFigiInstruments.

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

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

Annotations already declare readOnly, idempotent, closed-world behavior, so the safety profile is covered. The description still adds useful non-annotation context: it is a public FINRA API requiring no key, and it returns disclosure flags. It does not mention rate limits or result caps (those live in the schema).

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

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

Front-loaded purpose followed by a clean when-to-use bullet list and a workflow paragraph. Slightly long, and the geographic-workflow detour is arguably more than this tool needs, but every block is scannable and 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?

An output schema exists so return values need not be spelled out, and the description covers intent, alternatives, workflow chaining, and the data source. An agent has everything needed to select and invoke this tool correctly.

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

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

Description surfaces two inputs (name and optional two-letter 'state' narrowing), but the tool exposes far more parameters (rows/start pagination, wholesaler_ids scoping, include_previous, source_resource_id cache reuse) that the description never touches. With reported schema coverage at 0%, the description compensates only partially.

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 ('Search FINRA BrokerCheck for registered individual brokers'), names the key returned fields (CRD number, firm, registration status, disclosures), and is clearly distinguishable from sibling SearchBrokerCheckFirm and SearchIAPDIndividual.

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 an explicit 'Use this tool when' list, a fallback workflow that names sibling tools (SearchBrokersByPlace, SearchBrokerCheckFirm), and routes profile follow-ups to GetBrokerCheckDetail. Alternatives and their selecting conditions are all spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and non-open-world behavior. The description adds useful context beyond those annotations: it is sourced from FINRA BrokerCheck's public API and requires no API key. It does not discuss rate limits, pagination behavior, or caching follow-ups, so it is strong but not exhaustive.

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 purpose and returns, then structured with clear usage bullets and source/auth information. Every sentence adds useful context, and there is no filler.

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

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

For a read-only search tool with a rich nested input schema and an output schema, the description covers purpose, triggers, source, and returned fields adequately. It could better route agents away from sibling tools such as SearchBrokerCheck or GetBrokerCheckDetail, but the definition is otherwise complete enough to invoke correctly.

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

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

The description only maps to the name and location concepts ('by name', distinguishing by location), while the nested schema documents the individual parameters in detail. Because the structured schema carries most parameter meaning, the description meets the baseline for high schema coverage without substantially enriching parameter semantics.

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

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

The description gives a specific verb and resource: searching FINRA BrokerCheck for broker-dealer firms by name. It also scopes the result fields (CRD, registration status, city, state, disclosure flag), which clearly differentiates it from broader or detail-oriented siblings like SearchBrokerCheck and GetBrokerCheckDetail.

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 'Use this tool when' bullets give clear positive triggers: finding a firm CRD, disambiguating similarly named firms by location, and building a state-level territory map. It does not name alternatives or say when not to use this tool, so it stops short of the top score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the underlying source (SEC EDGAR full-text search API), the no-API-key requirement, and the $100M filing threshold that explains the data's scope. It does not, however, disclose pagination or result-size limits.

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?

Front-loads purpose, then a scannable bulleted when-to-use list, then a short capabilities/source footer. Efficient and well-organized, with only minor redundancy (the date-format note restating 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?

An output schema exists, so return-value explanation is not strictly required. The description covers purpose, scenarios, date filtering and source, which is sufficient to invoke the tool. The remaining gap is the absence of sibling differentiation and any mention of the internal fin-specific parameters.

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 description only adds semantics for three of the schema's parameters (query, start_date, end_date), and even the YYYY-MM-DD format note duplicates what the schema already says. The remaining parameters (wholesaler_ids, source_resource_id, exclude_fillers, optional_additional_filters, mcp_prompt_id) are never mentioned, so the description does not compensate for the low measured schema coverage.

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

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

States a specific verb and resource ('Search SEC EDGAR for 13F-HR institutional holdings filings by institution name') and enumerates the returned fields (filing date, entity name, period of report, accession number). This clearly distinguishes it from the nearby sibling Get13FHoldings, which retrieves holdings rather than filing metadata.

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 an explicit 'Use this tool when' block with three concrete scenarios (fund/ETF holdings, investment strategy research, filing list over a date range). It is clear about when to use it, but never names an alternative sibling such as Get13FHoldings or GetEdgarCompanyFilings, so the boundary between this and the other EDGAR tools is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real context beyond that: the upstream data source (Bloomberg OpenFIGI), and the rate-limit tradeoff ('No API key required (optional key raises rate limits)'). One caveat -- the description describes reaching an external public API while openWorldHint is false, a mild tension worth noting, though not a direct behavioral 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?

Front-loaded with purpose, then bulleted usage conditions, then the alternative, then source/rate-limit notes -- a clean scannable hierarchy with almost no filler. Minor waste in restating the return fields, which the output schema already supplies.

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

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

For an external-instrument lookup with an output schema, the description supplies everything needed to select and invoke it: trigger conditions, the sibling to use otherwise, data source, and rate-limit behavior. The remaining gap is parameter-level guidance for a schema with many optional fields, which the description never addresses.

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?

Reported schema description coverage is 0% at the interface level, so the description is expected to carry parameter meaning and it largely does not. It implies a free-text search ('by name or keyword') and alludes to security types ('ETFs, options, futures'), but says nothing about limit, exchange_code, security_type filtering, or the fin-specific wrapper params (wholesaler_ids, source_resource_id, additional_display_fields).

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 ('Search Bloomberg OpenFIGI for financial instruments by name or keyword') and enumerates what comes back (FIGI, ticker, exchange, security type, composite FIGI). It is unmistakably distinct from the get_*/search_* siblings because it is scoped to instrument discovery, not holdings, filings, or pricing.

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 'Use this tool when:' bullets cover the exact triggering conditions (company name but no ticker/FIGI, wanting all instrument types for a name, discovering associated securities) and it names the alternative -- MapInstrumentIds -- with the condition that selects it ('if you already have a specific ID to convert'). This is the textbook when/when-not/alternative pattern.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered structurally. The description adds meaningful behavioral context beyond that: the required FRED_API_KEY environment variable, the exact return fields (series ID, title, frequency, units, seasonal adjustment, date range), and the upstream source. It does not discuss rate limits or result caps beyond the schema's max.

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?

Front-loaded with the core action and return shape, then structured with a when-to-use list and a scannable series-ID table. Slightly longer than strictly necessary given the annotations already signal a safe read, but every section carries usable content.

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

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

With an output schema present, return values need not be explained, and the description still summarizes them plus the auth prerequisite. The one gap is that the schema exposes several unrelated parameters (wholesaler_ids, exclude_fillers, source_resource_id, mcp_prompt_id, question_asked) that the description never mentions or reconciles, which could confuse an agent.

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 description adds no direct parameter documentation, but the schema's nested properties already describe query, limit, and order_by well, so the baseline is 3. The 'Common series IDs' list indirectly illustrates the kind of keyword the query parameter accepts, which is a modest supplement rather than a substitute for parameter docs.

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 (Search) and resource (FRED economic data series by keyword), and explicitly distinguishes itself from the sibling GetFredSeriesData by naming it as the follow-up step. An agent can tell what this tool does and how it differs from the fetch tool without opening either schema.

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

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

Contains an explicit 'Use this tool when:' block listing three concrete scenarios (finding a series ID before fetching, discovering available macro data, gathering macro context for financial analysis), plus a direct pointer to GetFredSeriesData for the next step. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: results are de-duplicated by CIK, the returned fields (entity name, CIK, form type, filing date), and the source API with no key requirement. It omits pagination/rate-limit behavior but the annotations lower the bar.

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?

Front-loaded with purpose, then primary use, then a compact example block — every section earns its place. The vertical whitespace is cosmetic and the example list, while longer than strictly necessary, supplies directly actionable query patterns.

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

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

An output schema exists so return values needn't be spelled out (they are described anyway), and the read-only annotations cover the mutation profile. Combined with the workflow guidance, an agent has essentially everything needed to call it correctly; only the unexplained inherited boilerplate parameters remain unaddressed.

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 carries rich per-field descriptions, but the reported coverage of 0% at the params wrapper means the description must help, and it does: four worked examples show concrete keyword/fund_type combinations and the description notes date filtering and de-duplication semantics. It adds real usage value over the raw schema, though it does not address the boilerplate-looking fields (wholesaler_ids, mcp_prompt_id, source_resource_id).

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+resource (search SEC EDGAR for mutual fund and ETF filers) and even names the exact form types queried (N-1A, 485BPOS, N-2), which cleanly separates it from siblings like SearchEdgar13F and GetEdgarCompanyFilings. An agent can identify the tool's function without opening the schema.

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

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

Explicitly frames the tool as 'Step 1 of fee comparison' and instructs feeding returned CIKs into GetFundFees, which is strong forward-routing. It lacks an explicit when-not-to-use statement (e.g., use GetEdgarCompanyFilings for non-fund entities), so it stops just short of the top score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it states the source is the SEC IAPD public API and that no API key is required. It does not mention rate limits or error behavior, so it falls short of a 5.

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 purpose and uses a clean bullet list for usage guidance. It is slightly repetitive: the note at the end about RIAs vs BDs restates a point already made in the third bullet, which is a minor waste.

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 complexity, annotations, output schema, and sibling tools, the description is complete. It covers purpose, usage, alternatives, source, and authentication requirements. The output schema handles return values, so the brief mention of returned fields is a helpful summary rather than a gap.

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

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

The description only mentions searching by name, adding no meaning beyond what the schema already provides. The schema itself contains rich, detailed descriptions for all nested parameters (name, wholesaler_ids, source_resource_id, etc.), so the schema does the heavy lifting. Baseline 3 is appropriate when the schema is self-sufficient.

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 (Search) and resource (SEC IAPD database for RIA firms) and explicitly distinguishes RIAs (IAPD) from broker-dealers (BrokerCheck). An agent can tell it apart from siblings like SearchBrokerCheckFirm or SearchIAPDIndividual 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?

Provides explicit when-to-use bullets (need CRD/AUM, looking up Form ADV data, distinguishing RIA vs BD) and names alternatives (SearchBrokerCheckFirm for BDs, GetIAPDFirmDetail for full ADV data). It also gives a geographic workflow linking SearchBrokersByPlace to this 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds real context beyond that: the returned fields (CRD number, employer, registration states, exam history), the upstream source (SEC IAPD public API) and that no API key is required. It does not mention rate limits or pagination behavior, which keeps it short of a 5.

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

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

Purpose and return summary are front-loaded, the when-to-use list is scannable, and sibling routing comes before the source citation. Slightly longer than strictly necessary, but every block serves a distinct purpose.

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

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

An output schema exists, so return values need not be detailed, and the description does cover what it returns anyway. However, for a tool with a large set of optional filters and a caching parameter, the description gives an agent no guidance on the non-obvious inputs, leaving a meaningful gap for anything beyond a plain name search.

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 reported at 0% and the wrapper exposes roughly ten sub-parameters (rows, state, wholesaler_ids, source_resource_id, exclude_fillers, additional_display_fields, etc.). The description only conveys name-based lookup and says nothing about state narrowing, row limits, or the cache-reuse semantics of source_resource_id, so it fails to compensate for the 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?

States a specific verb and resource ('Search SEC IAPD ... for individual investment advisor representatives (IARs) by name') and immediately distinguishes itself from SearchIAPDFirm and SearchBrokerCheck. An agent can pick this over its near-identical siblings without opening any schema.

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

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

Explicit 'Use this tool when' bullets cover the three concrete scenarios (individual not firm, verifying IA registration, named-rep due diligence), and the following lines name the two alternatives with the condition that selects each. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds source (GLEIF API), no API key required, coverage size, and regulatory context, but omits search fuzziness, pagination, rate limits, or result-ordering behavior. With annotations covering safety, this is adequate but not rich.

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?

Well-structured and front-loaded, with the core purpose first and bulleted usage guidance. The regulatory and coverage sentences add context but are slightly marketing-oriented for a simple search tool.

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 annotations covering safety and an output schema covering return values, the description supplies usage, source, and domain context. It omits filter and limit behavior, but the input schema covers those, so it is complete enough 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 description only mentions searching by entity name and lists return fields. Other schema parameters such as limit, country, wholesaler_ids, and source_resource_id are not addressed, and the reported schema description coverage is 0%, so the description fails to compensate for input semantics.

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

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

States a specific verb ('Search') and resource ('GLEIF database for LEIs by entity name'), and lists return fields. It explicitly distinguishes itself from GetLEIDetail for parent/subsidiary lookups, helping route between 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 'Use this tool when' bullets covering LEI lookup, registration verification, EDGAR cross-referencing, and notes the alternative GetLEIDetail for relationship queries. Clear when-to-use context and a named alternative.

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