Fintel Discovery — Financial Intelligence for AI Agents

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

With readOnlyHint, idempotentHint, and destructiveHint already declared, the description correctly adds operational context beyond annotations: large filers can have 3,000+ positions, pagination is indicated by _has_more, and no API key is required. It does not contradict the annotations and adds useful scale and pagination behavior, though it could say more about rate limits or failure modes.

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 and well-structured, with purpose first, then workflow, then parameter guidance. However, it spends a long block enumerating return fields even though the tool has an output schema, making that section largely duplicative and reducing conciseness.

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 of a filing-parsing tool, the description covers the essential workflow, filters, sorting, pagination, and data source. Because an output schema exists, it does not need to fully explain return values, so the remaining omission is mainly that unrelated-looking parameters are left 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 description adds useful meaning for key parameters such as min_value_thousands, sort_by, limit, and offset. However, several schema parameters (mcp_prompt_id, question_asked, wholesaler_ids, exclude_fillers, source_resource_id, additional_display_fields, optional_additional_filters) are entirely unexplained in the description, which is a notable gap given the reported low schema description coverage.

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

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

The description states a specific verb-and-resource pair ('fetch and parse the complete equity holdings table') scoped to a specific SEC 13F-HR filing. It also distinguishes this tool from the sibling discovery tools by framing itself as 'Step 2' after SearchEdgar13F or GetEdgarCompanyFilings, which removes ambiguity about which tool retrieves filings versus positions.

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 workflow: obtain cik and accession_no from SearchEdgar13F or GetEdgarCompanyFilings, then call this tool. It also names concrete parameter usage rules (min_value_thousands to filter noise, sort_by='value_desc' to prioritize large positions, limit/offset with _has_more for pagination), which is more than enough for correct invocation.

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 only needed to add context, and it does: data is embedded curated static reference, no API key required, and it is sourced from the annual Kitces survey for 2023–2024. That vintage disclosure is genuinely useful for an agent judging freshness, though it doesn't say whether the data is aggregated medians only or also per-firm segments.

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 verb and scope, then a scannable bulleted category breakdown, then source and access notes. The category list is long for a single-parameter tool and restates the default ('all') that the schema already declares, but each bullet is informative rather than 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?

With an output schema present and rich annotations, the description needn't explain return values, and it covers source, vintage, and category coverage adequately. The remaining gap is that it never clarifies that the extra query-style parameters (wholesaler_ids, additional_display_fields, exclude_fillers) are likely irrelevant to this static reference dataset, which could mislead an agent into passing them.

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 to the `category` parameter by mapping each value to the metrics it contains (e.g., 'technology: software adoption rates and tech spend'), which the schema's option list alone does not convey. It does not address the other nested params (wholesaler_ids, source_resource_id, exclude_fillers), which appear to be generic plumbing inherited from a query schema and whose relevance to static benchmark data is left 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 enumerates the five content categories, so an agent knows exactly what comes back. Nothing in the sibling list (13F holdings, fund profiles, IAPD/LEI/BrokerCheck lookups) overlaps with this resource, making the tool trivially distinguishable.

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?

Usage is only implied: it notes that category='all' (default) retrieves everything, which hints at a broad-vs-narrow choice. There is no explicit statement of when to reach for this tool versus another, nor any when-not guidance or prerequisite (e.g., that it is unsuitable for firm-specific rather than industry-wide comparisons).

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, so the safety profile is covered. The description adds genuinely useful context beyond that: the data source (Yahoo Finance via yfinance) and that no API key/auth is required, which tells the agent about provenance and failure modes in this deployment. It does not mention rate-limit behavior or data latency, which keeps it below 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 output summary, followed by a scannable when-to-use bullet list and a one-line source/auth note. No filler sentences; each block adds distinct 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 return-value explanation is not required, and the description lists key fields anyway. However, for a tool whose only meaningful input is a ticker, the description never states that a symbol is required or how the noisy unrelated parameters should be left alone - a gap an agent may stumble on.

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 description does not compensate - it never mentions that a ticker symbol must be supplied, nor how the many unrelated-looking parameters (wholesaler_ids, source_resource_id, exclude_fillers) relate to an analyst-ratings call. The one sentence that touches inputs ('on a stock') leaves the agent to infer the symbol argument entirely from 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?

States a specific verb (fetch) and precisely enumerates the resource: consensus ratings, price targets (low/high/mean/median), and upgrade/downgrade history with firm, fromGrade, toGrade, action. This is clearly distinguishable from siblings like GetPriceHistory, GetTickerInfo, or GetEarningsHistory without opening a 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?

An explicit 'Use this tool when' block gives three concrete triggers (consensus view, target upside/downside, tracking rating changes). It lacks the negative side - no named alternative or when-not-to-use - but the positive framing is clear enough to route an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the description's added value is the sourcing and auth context: 'FINRA BrokerCheck public API. No API key required.' That is genuinely useful operational detail. It stops short of disclosing latency, rate limits, or what a missing/unknown CRD returns, so it lands at 4 rather than 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 in the first sentence, then a scannable bulleted usage block, with provenance last. Efficient and well ordered; the indentation/blank-line formatting is slightly noisy but no sentence is wasted.

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

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

For a single-record retrieval tool with a full annotation set and a declared output schema, the description supplies everything needed to select and call it: the key input, where to get that input, and the scope of the response. Return-value detail is correctly deferred to the output schema.

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 covers only the CRD parameter and reinforces 'Obtain from SearchBrokerCheck', which is helpful cross-tool routing. The remaining parameters (wholesaler_ids, source_resource_id, exclude_fillers, etc.) are left entirely to the schema, and the reported schema description coverage signal is 0%, so the description does not compensate for 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 (Retrieve) and resource (full FINRA BrokerCheck profile for one individual) with explicit scope (by CRD number). It also enumerates what the profile contains (employment history, exams, licenses, disclosures), which separates it from SearchBrokerCheck, the lookup sibling.

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

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

Provides a 'Use this tool when' block with three concrete trigger conditions, including the prerequisite 'You have a CRD (from SearchBrokerCheck)', which explicitly routes the agent to the sibling that produces the required input. No alternatives or exclusions are 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 non-destructive, so safety is covered. The description adds real value with the data source (Yahoo Finance via yfinance, no API key), but omits important behavior: that the ticker symbol is optional in the schema yet obviously mandatory in practice, and what happens when no symbol is supplied.

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 is front-loaded in the first sentence, event fields are stated in the second, and usage is scoped with a short bullet list. The bullets are slightly redundant with one another ('dividend history' vs 'dividend growth over time') but nothing is bloated.

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 the source/purpose are covered. What is missing is the operational minimum: which parameter identifies the company, what the period options mean for recency, and why an internal-fin filter like wholesaler_ids appears on a yfinance-backed tool — leaving the agent to guess at call shape.

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%, so the description is expected to carry parameter meaning, and it contributes nothing: neither 'symbol' nor 'period' (1y/5y/10y/max) is mentioned, despite 'full history' implying the max default. The schema also exposes unrelated parameters (wholesaler_ids, exclude_fillers, mcp_prompt_id) that the description never reconciles with a simple public corporate-actions fetch.

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 opening sentence names a specific verb (Fetch) and resource (cash dividends, stock splits, combined corporate actions) scoped to a ticker, which is clearly distinct from every sibling such as GetPriceHistory or GetFinancials. It stops short of an explicit sibling differentiation or stating that history is returned as a time series of events, so it is strong but not maximal.

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 three 'Use this tool when' bullets give concrete research contexts (yield inputs, dividend growth, split-adjusted returns), which is better than nothing. However, there are no exclusions and no named alternatives — for example, whether to use GetPriceHistory vs this tool for split-adjusted price work is never resolved.

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/destructiveHint:false, so the safety profile is covered. The description earns credit for adding non-obvious context beyond that: the upstream source (Yahoo Finance via yfinance), that no API key is needed, and the exact shape of the response (earnings_history, earnings_dates, earnings_estimate). It does not explain caching or how the inherited fin-style filters affect 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 purpose sentence, scannable when-to-use bullets, then return structure and source in two short lines. Every sentence carries information and there is no repetition of the title or annotations.

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

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

The presence of an output schema means return values need not be detailed, and the description still helpfully names the three sections. However, for a tool whose only parameter is a schema with zero description coverage at the top level and contains unrelated fin-specific filters plus an optional ticker, the description leaves key invocation questions (is symbol required? what scope do the extra filters have?) unanswered.

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 says nothing about the single `params` object — no mention of `symbol`, `limit`, or that symbol is optional and defaults to null (what happens then is unstated). Worse, the schema carries fin-domain plumbing parameters (wholesaler_ids, exclude_fillers, mcp_prompt_id, source_resource_id) that are unexplained by the description and unrelated to earnings data, leaving the agent guessing which of these actually matter.

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

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

The description states a specific verb+resource (fetch earnings history: EPS actual vs estimate, surprise %, upcoming earnings dates, forward estimates) and enumerates the three returned sections. It is distinguishable from neighboring tools in practice, but it never explicitly contrasts itself with GetAnalystRatings or GetFinancials, which an agent could plausibly confuse with 'consensus estimates'.

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?

Three explicit 'Use this tool when' bullets give clear triggering contexts (performance vs expectations, next earnings date, surprise trends). There are no exclusions or named alternatives for the near-miss cases, 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 readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context (SEC EDGAR data API, no API key required) but omits behavior that matters for EDGAR: rate limits, whether "every filing on record" is truncated or paginated, and what happens if no CIK is supplied (cik defaults to null).

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 scope, then a short scannable bullet list of use cases, then source/provenance notes. No sentence is filler, and the CIK-lookup URL is placed where the agent will need it.

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 described, and the source/no-key note is helpful. But with zero required parameters (cik defaults to null) and six undocumented optional parameters, an agent cannot tell whether the tool is callable with no arguments or how the filter parameters alter the query — a meaningful completeness 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?

Only cik is addressed, and even that duplicates the schema (zero-padding, where to find a CIK). The remaining parameters — wholesaler_ids, source_resource_id, exclude_fillers, additional_display_fields, optional_additional_filters, mcp_prompt_id — are unexplained in the description, and several are unrelated internal-fintech plumbing whose interaction with an EDGAR filings query an agent cannot infer. With the supplied coverage signal at 0%, the description needed to compensate and 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 and resource ("Retrieve all SEC filings for a company or institution using its CIK") and enumerates the returned fields (form type, date, accession number, description). It is clearly distinguishable from lookup-type siblings like LookupTicker or SearchEdgar13F because it declares the scope as "every filing on record" for one CIK.

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 explicit "Use this tool when:" block gives three concrete situations (have a CIK, track 13F/ADV/ownership history, need accession numbers), which is stronger than implied usage. However, it never names the alternatives or states when NOT to use it — notably SearchEdgar13F for 13F-specific searches, a sibling an agent could easily confuse with the "track 13F" bullet.

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, so the safety profile is covered. The description adds real behavioral value beyond that: the 4-year annual / 4-quarter quarterly data window, that results are transposed so each row is a reporting period, the Yahoo Finance/yfinance source, and that no API key is needed. It omits error/missing-symbol behavior, which keeps it from 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 purpose, then trigger bullets, then option values, then provenance — a sensible order. The bullets are somewhat redundant with the opening sentence and the statement/freq options largely restate schema descriptions, but nothing is genuinely wasteful.

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-format explanation is unnecessary; the description covers what remains: data windows, row orientation, source, and option semantics. An agent has enough to call it correctly without opening the schema.

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 spells out the meaningful enum values ('income', 'cashflow', 'balance'; 'yearly', 'quarterly', 'trailing') and adds the notable constraint that TTM is income-only. It says nothing about 'symbol' (which the description never explicitly instructs the agent to supply) nor about the unrelated internal-fin parameters (wholesaler_ids, source_resource_id, etc.) present in the schema, leaving a gap given the reported 0% schema description 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 ('Fetch income statement, cash flow statement, or balance sheet for a stock') and enumerates the three statement variants. Clearly distinguishable from siblings like GetEarningsHistory and GetPriceHistory, which cover 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?

The 'Use this tool when' bullets give concrete trigger conditions (revenue, net income, EPS, operating margins, CapEx, FCF, assets/debt/equity, fundamental analysis). However, it never states when NOT to use it or names an alternative sibling (e.g., GetEarningsHistory for EPS surprises or GetTickerInfo for quote data), so the routing guidance is one-sided.

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, destructiveHint: false, and openWorldHint: false. The description adds valuable context beyond annotations: it requires a FRED_API_KEY environment variable and describes the return format (date + value pairs with metadata). It does not cover rate limits or error behavior, but the added auth and return info make it more than adequate.

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 well-structured with a clear front-loaded purpose, a bulleted usage list, and parameter hints. It is appropriately sized for a tool with many optional parameters, though slightly verbose in the usage bullet list.

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 detailed return value documentation is not strictly needed, yet the description still summarizes the return format. It covers core usage, authentication, and source, but the unexplained optional parameters (e.g., wholesaler_ids, mcp_prompt_id) reduce completeness for an agent that might need to supply them.

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 carry parameter meaning. It mentions observation_start/observation_end, frequency, and implies series_id, but omits limit, source_resource_id, mcp_prompt_id, question_asked, wholesaler_ids, exclude_fillers, additional_display_fields, and optional_additional_filters. The majority of nested parameters are left unexplained, leaving an agent without guidance on how to use 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 ('Fetch') and resource ('time-series observation data from FRED for a specific economic series'), and explicitly distinguishes itself from the sibling SearchFredSeries by saying to use that first if the series ID is unknown.

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 four clear scenarios, and names the alternative tool (SearchFredSeries) for when the series ID is not known. This fully covers when to use this tool versus alternatives.

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

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

Annotations already cover read-only/idempotent, and the description adds substantive context beyond them: the SEC EDGAR source, no API key required, the error condition for funds that don't file rr: data, and the include_all_classes row-granularity tradeoff. It does not discuss pagination or how many funds can be batched, which is the remaining gap.

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, then a compact bullet breakdown, then workflow guidance — easy to scan. The enumeration of return fields is largely redundant given an output schema exists, costing some space.

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, single-resource retrieval tool with an output schema, the description covers source, prerequisites (CIK), failure mode and fallback. The redundancy of restating output fields is the main weakness rather than a missing critical detail.

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?

Cik semantics are reinforced (zero-padding handled automatically, example CIK) and include_all_classes is explained behaviorally in both description and schema. The description does not touch the many auxiliary params the schema carries (wholesaler_ids, source_resource_id, exclude_fillers), but those have rich schema text of their own.

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

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 workflow placement ('Step 2 of fee comparison'), tells the agent to run it across multiple CIKs and rank by net_expense_ratio ascending, and names an alternative (GetFundProfile) for the case where XBRL data is missing. When/when-not/alternative routing is all present.

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 behavior, so the safety profile is covered. The description adds useful context: the source is Yahoo Finance via yfinance and no API key is required, plus it reiterates that the tool only works for ETFs and mutual funds.

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 then structured into useful bullets. It is slightly longer than strictly necessary, but every block contributes to selection or invocation.

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

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

An output schema exists, so return-value explanation is not required. The description covers the tool's scope, section choices, data source, and stock alternative; remaining gaps are mostly auxiliary filtering parameters that the schema documents.

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 clarifies the section options and gives practical examples for holdings, sectors, and bond ratings, which helps with the primary fund-profile parameters. However, it does not add meaning beyond the schema for the many auxiliary parameters such as wholesaler_ids, source_resource_id, exclude_fillers, or optional_additional_filters; the schema itself carries that detail.

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 ETF or mutual fund specific data') and enumerates the exact data categories returned. It also explicitly distinguishes the tool from GetTickerInfo by limiting scope to ETFs and mutual funds.

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 holdings, sector allocation, bond ratings, and fund-profile comparisons. It also names the alternative for stocks ('For stocks, use GetTickerInfo'), leaving little ambiguity about when to select 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, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds useful behavioral context by naming the data source (Yahoo Finance via yfinance) and stating no API key is required, but it does not discuss caching, rate limits, or output freshness.

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

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

The description is front-loaded with the core purpose, then efficiently organized into use cases and holder_type options. It is short, readable, and every sentence contributes useful information.

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

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

An output schema exists, so return-value explanation is not required. However, the underlying parameter object is complex and the description only covers the primary stock ownership use case, leaving advanced filtering and caching parameters undocumented for the 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?

Schema description coverage is reported as 0%, so the description must compensate, but it only explains holder_type options and only implicitly covers symbol. It does not explain the many other nested parameters such as wholesaler_ids, source_resource_id, exclude_fillers, or 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?

The description gives a clear verb and resource: fetch ownership data for a stock, covering institutional holders, mutual fund holders, and insider transactions. It does not explicitly differentiate itself from the related sibling Get13FHoldings, but the scope is otherwise specific and understandable.

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 includes an explicit 'Use this tool when' list that gives concrete scenarios: checking institutional/fund ownership and insider buying or selling. It lacks when-not guidance and does not name alternatives such as Get13FHoldings for SEC 13F filings, so it is clear but not exhaustive.

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, so safety is covered. The description adds two useful facts beyond that — the source is the SEC IAPD public API and no API key is required — but says nothing about behavior on an unknown CRD, rate limits, or completeness/timeliness of the filing data.

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

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

Front-loaded with the purpose sentence, then a tight bulleted when-to-use block, then a one-line source note — well organized and easy to scan. The enumeration of returned field groups is mildly redundant with the output schema that already exists, but it aids selection speed.

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, the description needn't explain return values, and annotations carry the safety profile; what remains — purpose, trigger conditions, prerequisite CRD source, data provenance and auth — is all present. Only failure modes on an invalid or missing CRD are 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 description identifies the operative parameter (CRD) and tells the agent where to get it, matching the schema's own note. However, the seven other parameters exposed in the nested schema (source_resource_id caching, wholesaler_ids scoping, exclude_fillers, additional_display_fields, etc.) are never mentioned, so the description adds little over 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?

States a specific verb+resource+identifier: "Retrieve the full Form ADV filing detail for one RIA firm by its CRD number." It also enumerates the payload (client types, advisory activities, fees, custody, offices, affiliates), which distinguishes it from SearchIAPDFirm and from GetIAPDIndividualDetail without the agent 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?

The "Use this tool when" block gives three concrete triggers and names the prerequisite path (obtain CRD from SearchIAPDFirm), which is real routing guidance. It stops short of an explicit negative case such as "use GetIAPDIndividualDetail for a person CRD instead," so it is clear but not fully exclusionary.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful context beyond annotations, including the public SEC IAPD source and that no API key is required, though it does not mention rate limits or response size.

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 scope, followed by concrete use cases and source details. The bullets are purposeful and no sentence is wasted.

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?

Because an output schema exists, the description does not need to enumerate return fields, and the annotations cover safety behavior. It is complete for the main lookup flow, though it could better address the optional filtering and caching parameters exposed by the schema.

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 core CRD parameter and where to obtain it, which adds some routing context. However, with schema description coverage reported at 0%, it does not compensate for the other optional parameters exposed in the schema, such as wholesaler filters or cached resource IDs.

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 SEC IAPD profile for one individual investment advisor representative by CRD. It clearly distinguishes this from SearchIAPDIndividual and GetIAPDFirmDetail by focusing on the full profile for a single individual.

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 explicit when-to-use conditions, including having a CRD from SearchIAPDIndividual and needing Form ADV Part 2B-equivalent data. The agent can determine the correct tool and prerequisite without 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 the tool read-only, idempotent, non-destructive, and not open-world, so the safety profile is covered. The description adds useful context by naming the GLEIF API source and stating no API key is required, plus what fields are returned, though it does not discuss error or rate-limit behavior.

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

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

The description is front-loaded with the core action and return fields, followed by a compact when-to-use list. Every sentence supports selection or invocation, 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?

The tool is a read-only detail lookup with rich annotations and an output schema, and the description covers the key input and returned fields well. Completeness is slightly reduced because the unrelated optional schema parameters are left unexplained, which could confuse an agent inspecting the full input schema.

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 identifies the core input as a 20-character LEI code and points to SearchLEI as the source, which matches the key schema field. However, the schema exposes several internal/optional parameters such as mcp_prompt_id, wholesaler_ids, and source_resource_id that the description does not address, so it only partially compensates for low schema coverage.

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

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

The description starts with a specific verb and resource: retrieve the full GLEIF LEI record for one legal entity using a 20-character LEI code. It lists the returned fields and clearly distinguishes this from SearchLEI by requiring an already-known LEI for full details.

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 an explicit 'Use this tool when' section with concrete conditions: you already have an LEI from SearchLEI, need registration status, or need the exact legal address and jurisdiction. This gives the agent clear routing guidance against the sibling lookup 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 and non-destructive, so the bar is lower; the description still adds real value by naming the data source (Yahoo Finance via yfinance), stating no API key is needed, and describing the flattened column-naming convention. It omits failure behavior for bad tickers, alignment of differing trading calendars, and 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-loaded with the core action and output shape before the scenario bullets, with no filler sentences. The three 'use when' bullets partially overlap (relative performance / correlation matrices are near-synonyms), so it is slightly longer than strictly needed.

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 and annotations cover the safety profile, so the description needn't explain returns. However, the schema exposes several confusing fields irrelevant to price history (wholesaler_ids, exclude_fillers, mcp_prompt_id, question_asked) that the description never addresses, and there is no guidance on symbol limits or invalid-ticker 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 at 0% (the top-level 'params' ref has no description), so the description should carry more of the parameter burden. It only explains the 'symbols' delimiter format, which the nested schema already states verbatim, and says nothing about start/end vs. period precedence or interval choices — despite this being a one-argument wrapper over a large nested object containing several unrelated-looking 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 opening sentence gives a specific verb and resource ('Fetch OHLCV price history') plus the distinguishing scope ('for multiple tickers in a single call'), and even sketches the flattened output shape ('AAPL_Close', 'SPY_Volume'). It never names the obvious sibling GetPriceHistory, so the agent must infer the single-vs-multi split from the scope wording alone.

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?

A dedicated 'Use this tool when' block gives three concrete scenarios (cross-security comparison, portfolio correlation, relative performance), which is clear positive guidance. It stops short of when-not guidance and never routes the agent to GetPriceHistory for a single ticker or notes any ticker-count limits.

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, but the description adds real context beyond them: the data source (Yahoo Finance via yfinance), that no API key is needed, the default-to-nearest-expiry behavior when expiry_date is omitted, and the exact field set returned. It does not cover error behavior for invalid symbols or rate 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?

Lead sentence gives purpose and payload, followed by a short scannable use-case list, the prerequisite, the default, and provenance. Every line earns its place; only the blank-line-heavy formatting is slightly loose.

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 no explanation, and the description covers source, default behavior, and prerequisite adequately for a read-only tool. The one gap is the cluster of generic prompt/filter parameters in the schema that 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?

Schema description coverage is reported at 0%, so the description must carry the burden. It usefully documents expiry_date's YYYY-MM-DD semantics and the default behavior, and implies symbol is the underlying ticker, but it says nothing about the seven other parameters (wholesaler_ids, source_resource_id, exclude_fillers, etc.), some of which look irrelevant to an options chain and could confuse an agent.

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, so an agent knows exactly what it gets. It is clearly distinguishable from the sibling GetOptionsExpirations, which returns only dates.

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 concrete when-to-use cases (options strategy research, IV across strikes, open interest for sentiment) plus a prerequisite ('Call GetOptionsExpirations first'). It does not name an alternative for cases where this tool is the wrong choice, but the exclusions are implicit in the narrow 'one expiry date' scope.

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 non-destructive, so the safety profile is covered. The description adds value beyond them by naming the data source (Yahoo Finance via yfinance) and noting no API key is required, which tells the agent there's no auth setup and the data is third-party. It could go one step further on behavior for an invalid or non-optionable ticker, hence a 4 rather than 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 core instruction and the sequencing dependency are front-loaded in the first two sentences, with bullets used for scannable secondary conditions. Slightly padded by the two when-to-use bullets that largely restate the opening sentence, but nothing is confusing.

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 the read-only annotations plus the stated data source make the tool's behavior predictable. The only meaningful gap is which parameter to supply, which the description leaves implicit.

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 parameter, so the description must carry weight; it does signal the one meaningful input ('for a ticker') but never names the symbol field or gives format guidance. The bundled plumbing parameters (mcp_prompt_id, wholesaler_ids, source_resource_id, etc.) are not addressed at all, so the description does not 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?

A specific verb (list) plus a precise resource (options expiry dates) and scope (for a ticker). It also explicitly distinguishes itself from the sibling GetOptionsChain, so an agent can route between the two 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?

It states the sequencing rule directly ('Use this before calling GetOptionsChain to find a valid expiry date') and reinforces it with two concrete when-to-use bullets. No condition 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, non-destructive behavior, and the description is consistent with that. It adds useful behavioral context: Yahoo Finance source, no API key, and interval-specific maximum lookbacks. Return shape is not described, but an output schema exists.

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

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

Front-loads the action and result, then uses short bullets for usage and compact option lists. Every section contributes directly to selecting or configuring the 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?

Given the output schema and read-only annotations, the description is complete enough for an agent to call the tool for standard price-history requests. Minor gaps remain around date-range parameters and adjustment behavior, but they do not block correct core use.

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 interval and period options, including intraday and hourly max ranges, which is useful for the core query parameters. However, it does not explain start/end override behavior, auto_adjust, actions, or the additional internal filter parameters, so it only partially compensates for the reported low schema description 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: 'Fetch OHLCV price history for one ticker.' The 'one ticker' scope also distinguishes it from sibling GetMultiTickerHistory, so the agent can select it without opening the schema.

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

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

Includes explicit 'Use this tool when' bullets covering historical price/volume data, time-range analysis, and returns/volatility/trend computation. It does not name when-not-to-use or an explicit alternative, so it is clear 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 readOnly/idempotent/non-destructive/openWorld=false. The description adds meaningful context beyond that: it requires the cenpy package, accepts an optional free Census API key, falls back to rate-limited unauthenticated access, and cites the ACS 5-Year source. It does not address the numerous extraneous filter params, but the core behavioral profile is well disclosed.

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

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

Front-loaded with purpose, then structured with 'Key metrics returned' and 'Use this tool when' sections. Slightly verbose in the metrics/dependency prose, but every section is scannable and largely 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-value explanation is technically redundant but harmless. The description covers the data source, dependencies, and use cases; the only gap is that the many administrative/overlay params (wholesaler_ids, source_resource_id) aren't addressed, though the schema handles them.

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 itself documents each parameter thoroughly (state, zip_code, api key, caching, etc.), so the description doesn't need to re-explain them. The description reinforces the state-vs-ZIP targeting and lists return metrics, but adds little parameter syntax beyond what the schema provides — baseline 3 for schema-covered params.

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 US Census ACS income/wealth proxy data for a ZIP code or state, and lists the exact metrics returned. An agent can immediately tell this apart from data/stock siblings like GetFinancials or GetPriceHistory.

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 operational context (scoring territory wealth, comparing income distributions, pre-overlay proxy). No explicit when-not or alternative routing is given, which keeps it below a 5, but the usage guidance is concrete.

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 behavior, so the description's job is lighter. It adds real context beyond that: the upstream source (Yahoo Finance via yfinance), that no API key is needed, and the breadth of coverage across asset classes. It does not say how invalid/unknown symbols behave or whether results are cached or rate-limited.

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 payload, then use-cases, then supported symbol formats — a sensible ordering for an agent scanning it. The symbol-format list slightly duplicates the schema's symbol description, but the overall length is proportionate.

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 description need not explain return values, and what it does say about coverage is adequate. However, the input schema exposes a set of unrelated filter/context parameters that the description neither explains nor dismisses, leaving ambiguity about what actually must be supplied.

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 effectively 0% at the top level (a single 'params' object), and the nested schema carries unrelated fin-domain parameters (wholesaler_ids, exclude_fillers, source_resource_id, mcp_prompt_id) that the description never mentions. The description does compensate for the main 'symbol' argument by enumerating accepted formats for stocks, ETFs, funds, crypto, indices and forex, but it leaves the rest of the parameter surface 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 ('Fetch the full Yahoo Finance profile') and enumerates the returned fields (sector, market cap, P/E, 52-week range, beta), so the agent knows exactly what this returns versus a price-history or holdings tool. It does not explicitly differentiate from nearby siblings like LookupTicker or GetFundProfile, which keeps it from 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 triggers (company/fund summary, sector/industry classification, market cap/float/short ratio metadata), which is clear positive guidance. It offers no exclusions or pointer to alternatives (e.g. when to use LookupTicker for symbol resolution 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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context beyond that: the data source is Yahoo Finance via yfinance and no API key is required. It does not disclose result ordering or ranking behavior, which would be the next useful detail.

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 value are front-loaded in the first two sentences, and the when-to-use list is scannable. The asset_type option list is wasted space since the schema already enumerates the same values, keeping it short of a 5.

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 and read-only annotations, the description does not need to explain returns, and it still summarizes them as symbols with exchange and asset type. The one gap is that the schema exposes several unrelated infrastructure/wholesaler parameters that the description never addresses, leaving an agent to guess whether they matter for a simple 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 nested schema documents query, asset_type, max_results and the infra fields in detail, so the schema is doing the heavy lifting. The description's enumeration of asset_type values merely repeats what the schema already lists verbatim, adding no new meaning, and it says nothing about how query strings are matched or how max_results affects ranking.

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 ('search for a Yahoo Finance ticker symbol') and a clear scope ('by company name, fund name, or keyword'), plus the return content. It implicitly separates itself from symbol-first siblings like GetTickerInfo by saying 'Use this when you have a name but need the ticker symbol', though it never names a sibling explicitly.

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?

Three explicit 'Use this tool when' bullets cover the main scenarios (name without symbol, ETF/mutual fund lookup, disambiguation). This gives clear positive context, but there are no exclusions or named alternatives for cases where the agent already has an identifier.

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 operational context — no API key required, an optional key raises rate limits, and the data source is Bloomberg OpenFIGI — but it labels an external third-party API call while annotations set openWorldHint=false, a tension worth noting even if not a hard 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 the core purpose, then usage bullets, then idType reference, then a practical exchCode tip and source note. Every block is scannable and none is wasted, though the idType bullet list partially duplicates the schema's mappings description.

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 purpose, when-to-use, accepted ID systems, exchange targeting, and rate-limit/auth expectations; an output schema exists so return values need not be described. The notable omission is that the description never mentions batching semantics of the 'mappings' list or acknowledges the unrelated-looking extra parameters bundled in the schema.

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 idType enumeration and ISIN/CUSIP examples largely restate the 'mappings' field's own schema description, but the 'Include exchCode: US to target US exchanges for ticker lookups' tip adds real meaning the schema lacks. The remaining nested fields (wholesaler_ids, exclude_fillers, source_resource_id, mcp_prompt_id, question_asked) are never mentioned despite appearing in the schema and looking unrelated to ID mapping.

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 ('Map financial instrument identifiers ... Converts between ticker symbols, ISINs, CUSIPs, and FIGIs') and names the underlying service, so the agent can distinguish it from lookup/search siblings. It does not explicitly contrast itself with siblings like SearchFigiInstruments or LookupTicker, 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?

Provides a concrete 'Use this tool when:' list with three real scenarios (ticker→ISIN/CUSIP, normalizing IDs across EDGAR/Yahoo sources, finding the exchange). That is clear positive guidance, but there is no when-not condition and no named alternative tool to route to.

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 non-destructive, so safety is covered. The description adds context the annotations cannot: 'Source: FINRA BrokerCheck public API. No API key required,' which tells the agent no auth setup is needed. It stops short of stating rate limits or the 12-row page cap, which sits only 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 with the one-sentence purpose, then organized into scannable use-case bullets and a clearly labeled workflow paragraph. Every block contributes routing information; nothing is repeated 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?

With annotations, an output schema, and a well-documented nested parameter schema, the description covers what an agent needs to select and route correctly. Minor gaps: it does not say what happens when 'name' is omitted, nor mention the cached-result workflow (source_resource_id) that matters for follow-up queries.

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 calls out 'name' and the optional 2-letter 'state' narrowing, but both are already documented in the nested schema, and it says nothing about rows/start pagination, include_previous, source_resource_id, or the internal wholesaler_ids filter. With the nested schema carrying rich per-field descriptions, the description adds only marginal parameter value; ignoring source_resource_id's cache-reuse behavior in the prose is the biggest miss.

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') and scopes it to individuals, distinguishing it from SearchBrokerCheckFirm which handles firms. The description of returned fields (CRD, current firm, registration status, disclosures) confirms the scope 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' list covering CRD lookup, status verification, and record enrichment, plus a named alternative (GetBrokerCheckDetail) for full profiles. It even supplies a multi-step geographic workflow routing through SearchBrokersByPlace and SearchBrokerCheckFirm when the name is unknown.

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, destructiveHint=false, idempotentHint=true, so the safety profile is covered; the description adds useful context beyond that — public FINRA source, no API key required, and the shape of what comes back. It does not mention the 12-row cap or pagination implications, which is the main remaining behavioral gap.

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 scannable bulleted when-to-use list, then a one-line provenance note. No filler, no repetition of the title, and the size matches a simple lookup 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?

Annotations cover read safety and an output schema exists, so the description need not explain returns (though it helpfully summarizes them). Missing pieces are pagination behavior (rows/start) for iterating results and any hint that search may return zero or ambiguous matches, which matters for a name-based 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 nested schema documents every parameter thoroughly (name examples, rows max 12, 0-based start, two-letter state, wholesaler_ids resolution rules), so the schema carries the load. The description only adds indirect hints — 'by name', 'distinguish by location' (state), 'territory map' (state/wholesaler scope) — and says nothing about pagination via rows/start or the cache/source_resource_id workflow.

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 broker-dealer firms by name') and enumerates return fields (CRD, registration status, city, state, disclosure flag). The 'employer/firm' framing implicitly separates it from the individual-oriented SearchBrokerCheck and SearchIAPDIndividual siblings, but no sibling is named explicitly.

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?

'Use this tool when' followed by three concrete scenarios (getting a CRD number, disambiguating same-named firms by location, mapping BD firms in a state) gives an agent clear selection context. It stops short of stating when NOT to use it or naming SearchBrokerCheck/GetBrokerCheckDetail as the alternative for the detail/individual case.

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 covered. The description adds useful operational context ('SEC EDGAR full-text search API. No API key required'), but says nothing about result caps, pagination, or what an empty/no-match response looks like.

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 verb, resource and return fields, then a scannable bullet list of use cases. The sentence about the $100M filing threshold is domain color rather than tool guidance, and is the only sentence that does not directly earn 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 do not need explaining, and annotations cover safety. The description covers purpose, use cases, date format, source and auth, leaving only minor gaps (behavior when query is omitted, result limits) for what is a simple search 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?

The description restates the start_date/end_date YYYY-MM-DD format and implies the query is an institution name, both of which are already fully documented in the schema. The many internal parameters (wholesaler_ids, source_resource_id, exclude_fillers, mcp_prompt_id) are never mentioned in the description, so this section is useful but partial.

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 SEC EDGAR') and resource ('13F-HR institutional holdings filings') and further specifies the search key ('by institution name') plus the returned fields (filing date, entity name, period of report, accession number). This implicitly separates it from the sibling Get13FHoldings (which returns positions, not filings), but no sibling is named explicitly.

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?

Three explicit 'Use this tool when:' bullets cover the core scenarios (portfolio lookups, strategy research, date-ranged filing lists), which is well above implied usage. It stops short of saying when not to use it or naming Get13FHoldings as the alternative for position-level 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 readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds useful behavioral context: the external Bloomberg source, that no API key is required, and that an optional key raises rate limits. It does not contradict the annotations.

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

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

The description is front-loaded with the core purpose, followed by concise usage bullets, an alternative for disambiguation, and a brief note on authentication. Every sentence adds value.

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

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

Since an output schema exists, return-value details are not required. Annotations cover the safety profile, and the description covers purpose, usage, alternatives, and rate-limit behavior. It is only slightly incomplete in not explaining the optional filter parameters, which are partly covered in the nested schema.

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 or keyword, which maps to the query parameter. It does not explain the other available filters such as exchange_code, security_type, limit, or the caching/source_resource_id parameter. With schema description coverage reported at 0% for the top-level parameter, the description does not compensate for the gap.

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

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

The description states a specific verb and resource: search Bloomberg OpenFIGI for financial instruments by name or keyword. It also names the returned fields and distinguishes the tool from MapInstrumentIds, so an agent can identify its role without inspecting 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?

It provides explicit 'use this tool when' bullets and names the alternative MapInstrumentIds with the condition that selects it. This gives clear routing guidance between siblings.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value on top: the FRED_API_KEY environment requirement with where to obtain it, the upstream data source, and the specific return fields. It does not mention pagination/limit behaviour or result caps, which leaves a small gap.

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 one-sentence purpose, then uses labelled bullets for usage, examples, and prerequisites, which is scannable and well ordered. The six-item series ID list is helpful but the longest discretionary element; overall length is justified for a discovery 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?

An output schema exists, so the description need not explain return structure, yet it still summarizes the fields. Auth requirements, sibling routing, and use cases are all covered. The one omission is that the schema carries unrelated wholesaler/CRM-style parameters (wholesaler_ids, exclude_fillers, source_resource_id) that the description neither explains nor disclaims, 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?

Reported schema description coverage is 0% at the top level, and the description itself never explains query syntax, limit, or order_by semantics. The 'Common series IDs' block only implicitly teaches the agent what query strings look like (e.g. 'DGS10', 'CPIAUCSL'), and several schema parameters (wholesaler_ids, exclude_fillers, additional_display_fields) are never addressed at all.

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 the ... FRED database for economic data series by keyword') and enumerates what comes back (series ID, title, frequency, units, seasonal adjustment, date range). It is cleanly separable from the sibling GetFredSeriesData, which the description explicitly names as the follow-up step.

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 the three real triggers (finding a series ID, discovering available macro data, sourcing rates/inflation/GDP context). It also routes onward: 'use GetFredSeriesData after finding one', so the handoff between the search and fetch tools is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavior: results are de-duplicated by CIK (one record per filer), date filters restrict to recently updated prospectuses, and no API key is required. It also names the underlying source API. The only unexploited gap is that openWorldHint=false sits oddly against a live external EDGAR call, but the description does not actually contradict the annotation.

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 use case, then examples, then behavioral notes — a clean hierarchy. The four example queries occupy real space but each maps a distinct keyword/type combination, so they earn their place; the only redundancy is restating return fields that the output schema already covers.

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 an output schema, the essentials are present: what is searched, which forms, what comes back, how results are de-duplicated, and what to do with the CIKs next. The remaining shortfall is the unexplained auxiliary parameters (max_results, source_resource_id, wholesaler_ids) that an agent would have to guess at from the schema alone.

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%, so the description carries the burden and it only partially discharges it: it demonstrates keywords, fund_type, and date-range filtering through examples and prose. It says nothing about max_results (though the workflow implies one may need many results), source_resource_id caching, wholesaler_ids, or the miscellaneous filler/filter params, leaving several inputs unexplained in both places.

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 and resource ('Search SEC EDGAR for mutual fund and ETF filers by investment category or keyword') and then enumerates the exact form types scoped (N-1A, 485BPOS, N-2 for closed-end). That precision separates it from generic sibling searchers like GetEdgarCompanyFilings or SearchEdgar13F without the agent needing to open a 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?

It states a PRIMARY USE ('Step 1 of fee comparison') and explicitly routes the output to a named sibling, 'Feed the returned CIKs directly into GetFundFees'. Four worked example queries show how keywords and fund_type combine in practice. What is missing is any exclusion guidance — nothing says when to prefer GetFundProfile or GetEdgarCompanyFilings instead — so it stops short of a full when/when-not treatment.

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, and the description adds operational context the annotations cannot: public SEC API, no API key required, and a coverage boundary ('IAPD covers RIAs registered with the SEC'). It stops short of noting pagination/result caps or latency for a search endpoint, which is the remaining behavioral gap.

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 scannable bullets and a workflow paragraph — good structure. The 'Geographic workflow' paragraph partially restates the bullets and the final Source/API-key line could fold into the note, so it is slightly longer than it needs to be.

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 and full annotations present, the description covers what an agent needs to select the tool: purpose, scope, alternatives, and auth-free access. Minor omissions (result limits, whether state-registered advisers are included) are not fatal but leave some ambiguity for a firm-search 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?

The description confirms name-based lookup, but the schema exposes much more than a name — wholesaler_ids, source_resource_id (cache reuse), exclude_fillers, optional_additional_filters — and none of that semantics is echoed or prioritized in the description. Those auxiliary filters do carry their own $defs descriptions, so the description is not required to compensate fully, but it adds no meaning beyond the primary parameter.

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 enumerates what comes back (CRD, registration status, AUM, employee count, state, office city). It explicitly separates itself from the BD lookup path (BrokerCheck) and points to GetIAPDFirmDetail for depth, so an agent can place it among siblings 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?

Three explicit 'Use this tool when' bullets plus a named exclusion: 'For broker-dealers, use SearchBrokerCheckFirm instead.' It also spells out a handoff workflow (SearchBrokersByPlace → SearchIAPDFirm → GetIAPDFirmDetail), leaving essentially nothing 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 no destruction, so the description does not need to restate safety. It adds value beyond them by naming the upstream source (api.adviserinfo.sec.gov), confirming no API key is needed, and enumerating the returned fields (CRD, employer, registration states, exam history). It does not disclose what happens when 'name' is left null or whether result sets are capped/paginated, which is the remaining gap.

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 scannable when-to-use list, then sibling routing, then provenance. Each block earns its place, though the bullets partially restate the opening sentence and could be tightened.

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 and full annotations present, the description need not explain return values or safety, and it correctly focuses on routing, source/auth context, and result content. It is nearly complete; only the optional-name behavior and result-set sizing are 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?

Reported schema description coverage is 0% at the top level, so the description must carry weight; it does establish that name-based lookup is the primary axis and lists the output fields available. However, it never mentions state filtering, row limits, or the cache-passing/resource-id pattern that the nested schema exposes, so an agent reading only the description would miss meaningful invocation options.

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') and immediately scopes it to individuals rather than firms. The title, description, and named siblings (SearchIAPDFirm, SearchBrokerCheck) make the object of the search unambiguous.

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

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

Provides an explicit 'Use this tool when' list covering the three canonical intents (individual lookup, IA registration verification, due diligence) and explicitly routes firm lookups and broker/dealer individuals to named alternative tools. Nothing is left to inference about when not to use it.

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, so the safety profile is covered. The description adds real value beyond that: the return payload shape (20-character code, legal name, status, legal address, jurisdiction), the lack of an API key requirement, and the data source domain and coverage scale.

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 action sentence, then scannable trigger bullets. The regulatory/coverage lines ('MiFID II, EMIR, Dodd-Frank', '2M+ legal entities') are contextual flavor rather than invocation guidance, but they are brief and do not obstruct selection.

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, an output schema covering return values, and the description naming the source and returned fields, an agent has enough to call this correctly. The remaining gap is that the description says nothing about the odd internal parameters present in the schema, leaving ambiguity about whether they should be populated.

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 the 'by entity name' input; the schema's own property descriptions (name examples, limit default 10, ISO country codes) already carry the operational detail, so a baseline 3 is warranted. It does not clarify the extraneous plumbing parameters in the schema (mcp_prompt_id, wholesaler_ids, source_resource_id, exclude_fillers), which are unrelated to LEI search and could confuse an agent about whether they are required.

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 the GLEIF database for Legal Entity Identifiers by entity name, and names the exact fields returned. It also explicitly differentiates from the sibling GetLEIDetail by assigning parent/subsidiary lookups there.

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?

A dedicated 'Use this tool when' block lists four concrete triggering scenarios (need an LEI for an institution/fund, verify legal registration, cross-reference EDGAR entities, parent/subsidiary via GetLEIDetail). The alternative tool is named with the condition that selects it.

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