Oxford Ledge

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

Annotations only declare readOnlyHint, so the description carries the rest and delivers: no ticker field, cusip stripped on every channel, position_type must not be summed, SEC EDGAR source with ~45-day delay, heavy operation capped at 2 concurrent, and caveats surfaced via tool_notes. This is rich disclosure beyond 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 core purpose and dense with distinguishing constraints; nearly every clause earns its place. It is long and packs several concerns into one paragraph, which slightly hurts scannability, but there is little waste.

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

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

With no output schema, the description fully specifies the return shape ({cik, fundName, ... holdings} with row fields), plus the behavioral constraints. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% (baseline 3), and the description still adds value on the fund parameter's resolution semantics (name-prefix match, resolved_from, ambiguous refusal) and on the returned row fields. It says nothing extra about max_holdings, but the schema covers it.

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

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

States a specific verb+resource ('what one institutional filer owns ... latest SEC 13F-HR') with scope (largest positions plus QoQ changes) and filing form. An agent can distinguish it from siblings like get_institutional_holders, get_institutional_consensus, or ol_13f_filer_analytics.

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 input routing (CIK preferred, ticker, or name) and an exclusion/fallback: an ambiguous name is refused with candidates and points to ol_13f_filer_search. It does not, however, state when to prefer this over get_institutional_holders or get_institutional_consensus.

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 only declare readOnlyHint=true, so the description carries the weight and does so richly: keyless callers get stored rows and never trigger the EDGAR refresh, users must read stale/stale_basis, and caveats ride in tool_notes. It also disambiguates is_activist (a form-type label, not a judgement) and reports_zero (an exit OR reporting realignment).

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 and facts dense with no filler, but the single long em-dash-chained sentence makes the freshness and reports_zero caveats harder to scan than they need to be. Nothing is wasted, though structure could be slightly lighter.

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?

No output schema exists, yet the description enumerates the return shape ({ticker, count, filings}) and the row fields, and covers freshness, ordering, and interpretation caveats. For a two-parameter read tool this is complete enough to call correctly.

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

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

Schema coverage is 100% (baseline 3), but the description still adds the newest-first ordering, which is required to interpret what limit actually truncates, plus a restatement of the default 50 and hard cap 200. It is a modest but real addition beyond the schema.

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

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

States a specific verb and resource (Schedule 13D/13G >5% beneficial-owner filings for a ticker) and immediately distinguishes it from the sibling concept of quarterly 13F filings. An agent can tell exactly what this returns without opening any schema.

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

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

Names alternatives explicitly with the condition that selects them: cross-check get_institutional_holders before reading reports_zero as a sale, and it cites get_institutional_consensus as a complement. It also frames the tool's niche (event-driven stake-building) against 13F, so the agent knows when to reach for 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 only mark it read-only, but the description adds substantial behavioral detail: the exact return shape ({ticker, flags, count}), flag structure, that severity is only 'red' or 'amber' and sorted red-first, that 'absence is not an all-clear', and that caveats arrive in tool_notes. This is far beyond what the annotation provides.

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

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

Front-loaded with the core action, then progressively discloses screens, return shape, and interpretive caveats. The parenthetical list of screens is long but earns its place by telling the agent what signals matter; overall dense but not 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?

There is no output schema, yet the description fully describes the return contract and interpretation semantics, which is exactly what an agent needs here. Nothing critical is missing for correct invocation and result 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?

Only one parameter (ticker) and schema description coverage is 100%, so the schema already documents it fully with an example. The description adds nothing about the ticker beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Run 15 red-flag screens on a ticker') and enumerates the actual screens, so the agent knows precisely what this computes. It also names the sibling tools it pairs with (get_fundamentals, ol_intrinsic_value), distinguishing it from generic data fetchers.

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?

Says to pair it with get_fundamentals and ol_intrinsic_value and explains how to read an empty result ('absence is not an all-clear') and warns it is not a sell signal. There is clear context, but no explicit when-not-to-use or which alternative to pick if the agent only wants raw fundamentals.

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 only declare readOnlyHint=true, and the description adds substantial context: coverage-limited scope, exclusion of wound-down issuers, that holdingCount/totalFairValue are Oxford Ledge's parse rather than filer-published, and a warning to read fairValueBasis and fairValueGap before trusting totalFairValue because an under-counting parse understates the book. This is exactly the behavioral context annotations cannot carry.

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 and scope before the field list and caveats. The enumerated return fields are dense but each carries real information; slightly long, though little is expendable given the warning content.

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

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

There is no output schema, so the description carries the full burden of explaining the return shape — {bdcs, count} with per-BDC fields — and it does, plus points to tool_notes for caveats. Nothing an agent needs to interpret the response is missing.

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

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

Zero parameters, so the baseline is 4. The description reinforces this with 'No arguments,' leaving no ambiguity about invocation.

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 ('Roster of the ACTIVE BDCs tracked by Oxford Ledge'), gives the ordering ('sorted by portfolio size'), and explicitly scopes it as 'our coverage, not the whole BDC universe.' An agent can immediately tell this apart from sibling tools like search_bdc_borrower.

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

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

Explicitly says wound-down issuers are 'excluded by design' and names the borrower-keyed counterpart search_bdc_borrower, which routes the agent to the alternative. It stops short of a full when/when-not statement, so it is clear rather than 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?

Far exceeds the readOnlyHint annotation: it discloses no network call, sub-millisecond fixed-key envelope, all price fields null, the retired status object, and nuanced error semantics distinguishing malformed input ('CUSIP must be at least 6 characters') from the retirement note. This is unusually rich behavioral disclosure.

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

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

Front-loads the most critical fact (RETIRED) and the actionable alternative. It is dense and lists all 23 envelope keys, which is verbose but justified as a stable-contract guarantee. Slightly heavy but no padding.

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 no output schema, the description fully specifies the return shape (fixed-key envelope, null prices, status object) and error behavior, so an agent knows exactly what calling it yields. Complete for a retired tool.

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

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

Schema coverage is 100% and the single cusip param is documented there (9-char, e.g. 037833AK6). The description adds meaning beyond the schema by explaining the minimum-length validation error path. Baseline 3 with a small increment for the validation 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 retired verb+resource (single-bond trade detail by CUSIP over FINRA TRACE), notes it is RETIRED with a date, and explicitly names the two sibling replacements. An agent can immediately tell this tool is defunct and where to go instead.

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

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

Explicitly routes the caller: 'Use ol_bond_directory_screen ... or get_debt_maturities for one issuer's own maturity schedule,' and clarifies that no CUSIP can be priced here. The when-not-to-use condition is stated outright.

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

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

With only readOnlyHint in annotations, the description carries the behavioral burden and does so richly: available=false means no verified row with provenance keys ABSENT, an unreachable store is REFUSED (DATA_UNAVAILABLE), prose is truncated at ~2400 chars, legacy rows before 2026-09-13 mislabel source_form and blank source_period, and caveats ride tool_notes. These are non-obvious failure modes an agent must know before calling.

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 and return shape, and nearly every clause is actionable. It is dense and the backfill/restamp operational detail is somewhat niche, but no sentence is filler given the absent output schema.

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

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

No output schema exists, so the description enumerates the returned keys (summary, available, business_summary, short_summary, provenance fields) and warns that `summary` is NOT the content. Failure-state, truncation, and freshness caveats are all covered; nothing needed to call it correctly is missing.

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

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

One parameter at 100% schema coverage, so the schema already documents ticker format. The description adds only indirect meaning (ticker is resolved against SEC annual reports, with 20-F handling for foreign private issuers); baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('First-party business summary for a ticker') and pins the source to SEC 10-K Item 1 / 20-F Item 4, plus characterizes content as a 'curated, verifier-gated overview of what the company does.' It is clearly separable from sibling data tools like get_fundamentals and ol_filing_search.

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

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

Explicitly routes passage-level retrieval elsewhere ('For semantic passage retrieval over the full filing corpus use ol_filing_search'), which is genuine when-to-use guidance. It doesn't address the other nearby siblings (search_company, get_fundamentals), so differentiation is partial rather than 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 only carry readOnlyHint=true, but the description discloses substantial behavior beyond that: the parallel-array return shape, that netBuybacks is a derived dilution proxy rather than a filed figure, that pre-split share-count cells are withheld rather than shown as phantom buybacks, that IFRS reporters are refused rather than zero-filled, plus 24h cache and Plus tier. This is genuinely informative for correct interpretation.

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 purpose before the dense return-field enumeration, and every clause carries signal (refusal, derivation caveat, cache, tier). It is long and reads as a wall of text, but the density is justified by the absence of an output schema.

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

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

With no output schema, the description takes on the burden of describing the return shape, the derivation semantics of key fields, refusal behavior, cache freshness, tier requirement, and where caveats live (tool_notes). Nothing essential for calling or interpreting the tool is missing.

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

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

Only one parameter (ticker) with 100% schema description coverage, so the schema already does the work. Baseline 3 applies since the description adds no syntax or constraint beyond what the schema states.

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 resource and scope: 'Where a company sent its cash, up to 30 annual labels.' It explicitly distinguishes itself from siblings with 'Complements get_fundamentals and get_debt_maturities,' so an agent can place it in the retrieval set 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?

Names adjacent tools (get_fundamentals, get_debt_maturities) and a tier prerequisite, which implies where it fits, but gives no explicit when-to-use/when-not guidance or condition for choosing this over those 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 declare only readOnlyHint=true, so the description carries the rest and it does: hard cap of 20 with no caller-settable limit, refusal semantics (DATA_UNAVAILABLE rather than empty events), ~7-day re-index cadence, dual-class union behavior, and caveats surfacing via tool_notes.

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 and scope, and nearly every sentence carries operational detail. It is dense and somewhat run-on, packing return shape, caveats and cadence into long clauses, but little 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?

Although there is no output schema, the description fully specifies the return envelope and per-event fields, plus coverage, cadence and failure behavior — everything an agent needs to call and interpret this correctly.

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

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

Schema coverage is 100% and the event_type schema already enumerates all 17 categories and even says 'for M&A use acquisition_disposition'. The description reinforces stored-category-only matching and the invalid-value outcomes, adding some value but largely restating 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, resource, scope and ordering in the first clause: 'The 20 most recent 8-K item events for a ticker ... NEWEST FIRST'. It also explicitly differentiates itself from siblings by naming get_insider_activity and acquisition_disposition routing.

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

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

Explicit when-to-use is woven throughout: 'a recent-events feed, not a history' sets expectations, 'for M&A use acquisition_disposition' and 'For Form 4 insider transactions use get_insider_activity' name the alternatives and the conditions that select them.

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

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

With only readOnlyHint available, the description carries real behavioral burden and delivers: unit convention (millions USD, 400 = $400M), as-of-filing-date staleness caveat, balance-sheet cross-check, refusal fields on empty results, Plus-tier requirement, and tool_notes. This is exactly the context annotations cannot supply.

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

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

Front-loaded with what the tool is and its most error-prone trap (units), then caveats, then the sibling route. Dense but every sentence carries a distinct operational fact; nothing is 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?

No output schema exists, so the description must describe returns — and it does, enumerating the returned fields including refusal_reason/refusal_note. Combined with units, provenance, tier gating, and validation guidance, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% for the single ticker parameter, so the schema already documents it fully. The description adds no syntax or format nuance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (forward debt maturity ladder) plus its exact provenance (latest 10-K/20-F footnote) and the response shape. It also names a sibling (get_capital_allocation) as the route for a different need, letting an agent distinguish it without opening schemas.

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

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

Gives clear conditions: forward maturities as of the filing date, with get_capital_allocation named for historical issuance/repayment, and an instruction to check `validation` before quoting a total. It does not address the closely related sibling ol_maturity_wall, leaving that routing 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 only carry readOnlyHint=true, yet the description discloses the response envelope, the fact that events carry no numeric values, the 6h cache, the hard 180-day refusal, the FRED source, and the critical source_status failure mode where errors return events=[] indistinguishably from a quiet calendar. This is exactly the beyond-annotation context an agent needs.

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?

Dense but every sentence carries decision-relevant information, with the most important caveats (no values, check source_status) front-loaded and the operational limits (days cap, cache) following. 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?

With no output schema, the description compensates by fully specifying the return shape ({days, events, count, source_status, error} and per-event fields), the error contract, and the source. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100% and the single param is documented, so baseline is 3; the description adds real value by explaining the semantic consequence of the bound (above 180 is REFUSED) and restating the default look-ahead of 90, which the schema already implies via maximum/minimum.

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 (upcoming US macro data-release dates), enumerates the 9 tracked releases, and explicitly delimits scope by excluding estimates, prior/consensus/actual values, and FOMC meeting dates. An agent can distinguish this from ol_earnings_calendar and other calendar siblings without opening any schema.

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

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

Gives clear context (a forward-looking release schedule with a default 90-day look-ahead) and explicit boundaries (above 180 REFUSED, FOMC excluded). It does not name a specific alternative tool or spell out when-not-to-use beyond the FOMC exclusion, so it falls short of a full 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?

Adds rich behavioral context beyond readOnlyHint: returns structure, oldest-first ordering, anchoring of `days` to latest loaded settlement date (not today), coverage caveats, unadjusted prices, and an explicit refusal mode (DATA_UNAVAILABLE). This is exactly the kind of detail annotations cannot provide.

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?

Dense but front-loaded: purpose appears first, followed by return shape, then parameter behavior, then caveats. Every sentence carries useful information, though the single-paragraph format is slightly heavy.

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?

Without an output schema, the description fully covers return fields, row semantics, coverage caveats, and tool_notes placement. An agent has everything needed to interpret results and avoid misreading gaps.

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

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

Schema coverage is 100%, but the description adds meaningful nuance: `days` is anchored to the latest loaded settlement date rather than today, `end_date` can extend the window, and row values are in SHARES not dollars. This goes beyond the schema's parameter descriptions.

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 ('returns history') and resource ('SEC fails-to-deliver'), plus distinguishing scope ('settlement-failure side of short pressure'). An agent can immediately tell this apart from siblings like get_13f_holdings or ol_short_interest_trend.

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?

Names the complementary sibling ('Pair with ol_short_interest_trend for the other half') and gives clear context for when the tool is useful. It does not explicitly state when not to use it, so it falls short of the full 'when/when-not' bar.

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 only supply readOnlyHint=true, but the description adds the full response contract (field names, observation: 'latest_only'), the failure/refusal shape with refusal_reason and licensor, the enumeration of refused third-party series, the restricted keyed-posture note, and that caveats ride in tool_notes. This is unusually rich behavioral disclosure.

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

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

Front-loaded with the core purpose and return shape before detailing refusals. The enumerated list of seven licensed series is long but each entry is functional, and there is little filler prose.

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

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

There is no output schema, yet the description fully specifies both the success payload and the two error/refusal payloads, plus licensing and posture constraints. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by naming concrete FRED ids that are accepted (GDP, UNRATE style) and, more usefully, ids that will be rejected, which tells the agent how to interpret the series argument beyond the schema.

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

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

States a specific verb and resource: fetch ONE latest observation for a single FRED series from Oxford Ledge's ~41-series macro snapshot, keyed by FRED id. It explicitly scopes itself against siblings like get_bond_data and get_yield_curve by limiting to the snapshot and to 'latest_only, never a history'.

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

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

The description tells the agent the operating conditions clearly: only snapshot series work, out-of-snapshot ids error, and a named set of licensed series are refused with a reason. It does not explicitly route to an alternative tool for history or full FRED access, 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 only declare readOnlyHint=true, but the description adds rich behavioral context: return shape, parallel-array alignment, null-vs-zero semantics, withheld pre-split per-share cells, IFRS/no-annual-fact error behavior, SEC EDGAR source, post-quarter lag, and 24h cache.

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

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

Front-loads the core purpose, then efficiently packs only actionable details about output shape, units, null handling, basis, errors, alternatives, and source. The density is justified by the tool's complexity and lack of an output schema.

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

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

Given no output schema, the description fully explains the return object, key subfields, array alignment, error responses, data source, lag, and caching. An agent has enough context to call and interpret the tool correctly.

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

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

Schema description coverage is 100% and the sole parameter is already documented as a stock ticker symbol. The description reinforces that it takes one ticker but adds no syntax or format details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: full XBRL financial history for one ticker. It clearly distinguishes the tool from siblings by naming related alternatives for cash deployment, per-share fair value, and industry operating metrics.

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

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

Explicitly routes agents to get_capital_allocation, ol_intrinsic_value, and ol_operating_kpis for specific alternative needs. This makes when-to-use-this-versus-siblings clear without requiring schema inspection.

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?

Goes well beyond the readOnlyHint annotation: it discloses the hard LIMIT of 20 most recent rows, that `days` is a NO-OP, 4/A dedup behavior, isDerivative caveats, Plus-tier requirement, SEC EDGAR source with ~2-day filing deadline, and that caveats live in the response's tool_notes. This is rich operational context an agent needs.

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 and the critical '20 MOST RECENT TRANSACTION ROWS ONLY' constraint in caps. Dense and information-rich, but the field-by-field enumeration of the response is long for a description; every clause is useful though, so no real waste.

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

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

No output schema exists, yet the description fully describes the return shape ({ticker, transactions}), each row field, and how totals should be computed. Combined with the sibling routing and tier/caveat notes, an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema by warning that the `days` parameter is currently a NO-OP — which directly overrides the schema's own 'Number of days of history (default 365)' claim. It doesn't add syntax for `ticker`, keeping it from a 5.

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 ('Recent Form 4 insider transactions for one ticker') and immediately scopes it against siblings, explicitly naming ol_insider_recent_buys, ol_insider_cluster_scan, and get_activist_stakes as the tools for adjacent use cases. An agent can distinguish this from the other insider tools without opening any schema.

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

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

Provides explicit routing: 'Market-wide buys: ol_insider_recent_buys; clusters: ol_insider_cluster_scan; >5% stakes: get_activist_stakes', plus an instruction to filter on transType yourself and to exclude issuerSelfFiled rows from totals. When-to-use alternatives and in-tool handling rules are both 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?

With only readOnlyHint in annotations, the description carries the behavioral burden and does so richly: return shape, truncation semantics (consensus truncated, tickers_found full count), common-stock-only scope, per-fund latest-quarter variance, SEC EDGAR source with ~45-day delay, and caveats location.

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 purpose and scope are front-loaded in the first sentence, followed by compact return structure, parameter effects, caveats, and sourcing. Every sentence adds information; none is 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?

There is no output schema, but the description fully explains the return object and row fields, truncation rules, source, and timing caveats. An agent has everything needed to call and interpret the tool correctly.

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

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

Schema coverage is 100% and the schema already documents defaults and caps. The description adds meaningful relational semantics: that top_n truncates the consensus list while tickers_found remains the full count meeting min_funds, which is not obvious from the schema alone.

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 states a specific verb-resource-scope: which tickers tracked 13F filers most widely hold in common. It clearly distinguishes itself from sibling get_13f_holdings by naming that tool and its different question.

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

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

Explicitly maps the tool to 'who is buying X?' and contrasts it with get_13f_holdings ('what does fund X own?'), giving an agent a clear routing rule. It also states source and delay, which are relevant usage context.

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 only declare readOnlyHint=true, but the description carries substantial behavioral burden: the 100-by-row display cap vs the true filer count, the coverage.basis caveat, common-stock-only scope, off-cadence quarters, CUSIP resolution failures that can drop or mis-attribute rows, and the ~45-day EDGAR delay with tool_notes caveats. This is rich, non-obvious disclosure well beyond structured fields.

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

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

The description is dense but nearly every clause earns its place: return shape, cap caveat, per-holder fields, coverage caveat, scope limits, sibling routing, and source cadence. The core purpose is front-loaded before the caveats. Slightly crowded, but the length is justified by the caveat burden for a data source with real attribution traps.

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?

No output schema exists, so the description must carry the return-value burden, and it does: it enumerates the top-level keys, the per-holder field list with units (value_usd in whole USD, pct_change vs prior quarter), the display-cap limitation, and the coverage.basis field to check before quoting aggregates. Nothing an agent needs to interpret the response is missing.

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

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

The single ticker parameter is fully documented in the schema ('Stock ticker symbol (e.g. AAPL)'), and the description adds no syntax, constraint, or format detail beyond it. Baseline 3 applies when the schema already does the heavy lifting for a single 100%-covered 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+resource ('Which institutions hold one ticker, and which way they moved') and immediately enumerates the return shape. It distinguishes itself from siblings by explicitly labeling ol_ownership_changes as the 'direction-only view' and get_13f_holdings as the 'fund-keyed inverse', so an agent can place it precisely in the tool family.

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 names two alternatives with their distinguishing characteristics, which functions as routing guidance towards the correct sibling. However, it does not explicitly state the condition under which a caller should prefer this ticker-keyed view over them, leaving the 'when-to-use-this' inference to the 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?

Goes well beyond readOnlyHint: it discloses that the response shape changes based on arguments (ticker-only vs free-text), that sentiment is a label not a number, that matching is prefix-word rather than semantic, the limit defaults and hard cap, absence of pagination, the cron-populated multi-provider source, and that caveats ride in tool_notes. This is exactly the extra behavioral context annotations do not provide.

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 layered with constraints in diminishing priority. Dense but each clause carries information; the all-caps emphasis is stylized but signals the important conditional. Slightly packed.

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 no output schema and no annotations beyond readOnlyHint, the description carries the burden and does so well, covering response shape, matching, limits, and where caveats live. Minor gap: it doesn't clarify when to prefer this over search_news_archive.

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

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

Schema coverage is 100% (baseline 3), and the description still adds real meaning: it explains that the choice of parameters changes the response shape, clarifies query is prefix-word not semantic, and reiterates the limit cap. That raises it above the schema-only baseline.

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

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

States a specific verb and resource ('Read the Oxford Ledge news archive'), its filter axes (ticker and/or keyword), and its ordering (newest first). Clear on its own, but it never names or distinguishes itself from the very similar sibling search_news_archive, leaving the agent to infer the split.

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 is implied by 'by ticker and/or keyword' and the note about handling both response shapes, but there is no explicit when-to-use, when-not, or alternative (e.g. search_news_archive). Guidance is present but must be inferred.

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

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

With only readOnlyHint from annotations, the description carries substantial extra detail: the exact return envelope {portfolio_id, positions, error} on every path, that error is null/string and positions [] either way, no price/market-value/gain-loss/weight fields, and unknown-id behavior. This is richer than the annotations and prevents misfires.

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 key fact (positions of one saved portfolio) and then the return contract and the no-price-leg warning. Dense but each sentence carries meaning; slightly long, with some parenthetical repetition of the empty-list caveat.

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?

No output schema exists, so the description assumes the burden of explaining returns and does so completely: field set, error semantics, ordering, nullability of costBasis, and the empty-vs-nonexistent ambiguity. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% (single portfolio_id with a documented default of 'default'), so the schema fully documents the parameter. The description adds only that it identifies 'one saved portfolio' and the unknown-id semantics, which is helpful but not substantial syntax/format detail beyond the schema.

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

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

States a specific resource ('Stored positions of one saved portfolio') and explicitly frames what the tool does and does not return. It names a sibling (get_sector_breakdown) for the adjacent need, but the core verb is implicit rather than a crisp 'returns the positions held...'.

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

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

Gives clear usage context: use this for a saved portfolio's positions, use get_sector_breakdown for catalog-wide sector mix. It also warns that an empty list doesn't prove existence, steering the agent's interpretation. No explicit when-not exclusion beyond the sector-mix alternative, so 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?

Goes well beyond readOnlyHint=true: discloses the row granularity (one row per sector+industry pair requiring aggregation), that totalMarketCap is always NULL and therefore cannot answer market-share questions, that blank-sector rows are dropped, that an {error} dict is returned when Postgres is unavailable, and the underlying source and 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-loads the scope and the portfolio exclusion, and nearly every sentence carries operational information. The all-caps emphasis and the 'how much of the market is tech' aside add length but do convey a real capability limit.

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 no output schema, the description fully compensates by specifying the exact return shape, the aggregation requirement, the always-NULL field, and the error case — everything an agent needs to interpret the response correctly.

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

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

Zero-parameter tool, so the baseline is 4; the schema is empty and the description correctly confirms 'No arguments.' There is nothing further to document.

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 ('how the covered universe splits across sectors and industries') and immediately scopes it as 'the whole catalog, NOT a portfolio,' which separates it from get_portfolio_positions 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?

Explicitly names the alternative ('For a named portfolio use get_portfolio_positions') and the condition that selects it, plus states 'No arguments' so the agent knows no filter setup is needed.

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

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

With only readOnlyHint available, the description carries real behavioral weight: it warns the wording is not verified, ties verbatim status to a flag, mandates attribution, discloses 24h per-argument caching, and points caveats to the response's tool_notes. That is exactly the kind of context annotations cannot supply.

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?

Dense but front-loaded: identity first, then the critical 'not verified' warning, then the response-shape contract. Every clause carries information, though the run-on structure with heavy emphasis makes it slightly hard to scan.

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 no output schema, the description correctly takes on the return-value burden, describing both response shapes, the 10-fact cap, the error shape, and where caveats live. An agent has everything needed to call it correctly and present results honestly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds genuine meaning: it explains that a query caps results at 10 while a bare category or empty call returns a single random pick, and it clarifies the category-or-error retry behavior. This goes beyond the schema's per-parameter field docs.

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

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

States a specific verb+resource ('curated value-investing principle, historical fact or attributed paraphrase') and its source corpus, explicitly naming the authors covered. It also declares what the tool is NOT ('never a market signal'), which cleanly separates it from the market-data siblings like get_fundamentals or get_news.

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

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

Gives clear context ('Pedagogical content only -- never a market signal') and implicitly routes by argument mode (query vs bare category vs no arguments). It does not name an alternative sibling tool or spell out when-not to call it, but the usage context is unambiguous for 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?

Goes well beyond readOnlyHint=true by disclosing units ('4.25 means 4.25%'), the 2026-07-21 removal of OAS/UMCSENT series, the 4h cache, the source chain (Treasury.gov with FRED fallback), and that caveats arrive in the response's tool_notes. This is exactly the extra context annotations cannot carry.

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 two-shape contrast and keeps every sentence informative (units, removals, source, cache). It is dense to the point of being hard to scan, with multiple ALL-CAPS fragments, but nothing is truly 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?

With no output schema and only one parameter, the description fully carries the return-shape burden: it specifies both response forms, tenor count, comparison dates, units, and where caveats surface. An agent can consume the result correctly without further schema 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?

Schema coverage is 100%, but the schema's own description ('Include yield curve from 1 year ago') is misleadingly narrow; the tool description corrects it by spelling out that true yields PARALLEL ARRAYS over 11 tenors at three points in time, and false returns a flat {data: [...]} list. That is a substantial semantic addition, not a restatement.

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?

Starts with a specific resource ('US Treasury yield curve') and immediately names the wider macro content returned by default. It is clearly distinguishable from siblings like get_fred_data or get_bond_data because it names Treasury.gov par yields and FRED fallback as the source.

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

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

Explicitly frames the two modes and the purpose of each: include_history=true is for 'steepening/inversion work' while false returns the macro dashboard. It does not name an alternative sibling tool or state when NOT to use this one, so it falls short of 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?

With only readOnlyHint available, the description carries the burden well: it discloses the denominator semantics (reported 13F long-equity value, explicitly not AUM), the single-quarter no-fabricated-turnover rule, the refusal path (DATA_UNAVAILABLE on unreachable store), data provenance/licensing, and that caveats arrive in tool_notes. This is a genuine edge-case map.

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 routing, then semantics, then caveats — good ordering and no filler sentences. It is dense with parenthetical asides and ALL-CAPS emphasis, which costs a little readability but every clause adds 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?

No output schema exists, and the description compensates by naming the return shape ({summary, fund, quarter, n_positions, reported_long_equity_value, analytics}) plus where caveats land. For a one-parameter analytics tool with only a readOnlyHint annotation, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single param is self-documenting, so the baseline is 3. The description adds real meaning beyond the schema: the CIK must be NUMERIC and a ticker 'will not resolve here', which the schema's 'e.g. 1067983' does not state.

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: computes institutional-filer behavior analytics from 13F holdings, naming the exact metrics (concentration/top-N %, normalized HHI, turnover, persistence). It explicitly distinguishes itself from the two nearest siblings, get_13f_holdings (position lists) and ol_13f_filer_search (CIK resolution).

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

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

Explicit routing: use ol_13f_filer_search when you only have a ticker, and use get_13f_holdings if you need a position list ('NO position list'). The 'when-not' cases are stated as clearly as the 'when'.

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 only give readOnlyHint=true, so the description carries real weight and delivers: curated universe rather than live EDGAR full-text, prefix-match ranking, the meaning of an empty filers array (store answered, nothing matched) versus a REFUSED DATA_UNAVAILABLE error on an unreachable store, and that caveats ride in tool_notes.

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 and routing before the caveats; dense with caps and parentheticals but nearly every clause carries information an agent needs. Slightly cramped punctuation keeps it from 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?

No output schema exists, yet the description specifies the return shape ({summary, query, filers:[{cik, name, last_filing, page_url}], count}), the empty-result semantics, the failure mode, and where caveats live — nothing needed to call or interpret it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic value beyond the schema by disclosing that 'name-PREFIX matches rank first' and repeating the 3-80 char and default-5/hard-cap-10 bounds in context.

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

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

States a specific verb+resource ('Resolve a 13F FILER name to its CIK') and explicitly distinguishes itself from search_company ('search_company resolves ISSUERS'), so an agent can pick it apart from the closest sibling without opening schemas.

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

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

Explicitly frames itself as 'the front door to get_13f_holdings and ol_13f_filer_analytics when you know the manager and not its CIK', naming the downstream tools and the exact condition that selects it, plus the contrast with search_company.

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 only declare readOnlyHint=true, so the description carries the rest and does so well: unreachable FDIC store surfaces as DATA_UNAVAILABLE rather than an empty list, ambiguous names return a candidate list instead of guessing, and caveats are delivered via the response's tool_notes. Ambiguity and failure semantics are exactly the behavioral traits an agent needs before trusting an empty result.

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 resource and event taxonomy, then the resolution/error semantics. Dense and clause-heavy (em-dashes, backticks, parentheticals) but nearly every clause carries operational information; the only mild slack is the redundant 'FREE'/'Source' pairing at the end.

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?

No output schema exists, so the description must describe returns — and it does: is_failure from the CHANGECODE taxonomy, resolved_from, ambiguous candidate lists, tool_notes. Combined with the resolution and unavailable-store behavior, an agent has everything needed to call this correctly and interpret the response.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real semantics beyond the schema: name resolution spans active AND closed charters, resolved_from reports which charter matched, and ambiguous resolution returns candidates. It doesn't cover `limit` behavior beyond the schema's own default/cap note, keeping it just short of a 5.

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: FDIC structural events for one bank, enumerating the event types (failures, assisted resolutions, mergers, acquisitions, charter changes) and the sort order. It explicitly distinguishes itself from the sibling ol_fdic_bank by noting that tool covers 'active institutions only', so an agent can route 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?

Gives explicit invocation guidance: pass `cert` or `name`, call again with `cert` when a name is ambiguous, and use ol_fdic_bank instead for active-institution data. It also pre-empts the most likely user mistake (assuming a failed/merged bank can't be found).

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

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

With only readOnlyHint available, the description carries substantial extra behavioral burden: the units trap (raw `spread` mixes percent and bps; use `spread_bps`), stale-position exclusion by default, the 25 default / 100 hard cap, the source (SEC EDGAR schedules of investments), and that caveats ride the response's tool_notes. That is rich disclosure beyond 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 inputs, then return shape, then the units trap, then defaults and provenance. The parenthetical example and the dense field list all earn their place; no filler sentences.

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?

No output schema exists, yet the description enumerates the return keys ({summary, borrower_norm, count, lender_count, tranche_count, lenders, ...}), the row granularity per BDC lender, the sort order, and where caveats live. Combined with defaults, caps, and the unit warning, an agent has everything needed to call and interpret it.

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 already 100%, so baseline is 3, but the description adds real meaning: `limit` counts LENDERS not rows (with tranches nested), `include_stale` is tied to whether a lender's newest filing still names the borrower, and the spread/spread_bps distinction warns against using the raw field.

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 — cross-lender loan-pricing dispersion for one private-credit borrower — and concretizes it with an example (one BDC marks S+550 @ 98, another S+575 @ 99). It is clearly distinguishable from siblings like ol_bdc_top_borrowers (which supplies the borrower_norm input) and ol_bdc_loan_pricing_trend.

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

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

Explicitly tells the agent where to get the required borrower_norm (ol_bdc_top_borrowers or search_bdc_borrower) and describes the default vs. include_stale behaviour. It stops short of stating when NOT to use it versus closely related siblings such as ol_bdc_common_borrowers or ol_bdc_credit_quality.

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 only declare readOnlyHint=true, but the description adds substantial behavioral context: matcher-verified only at >=0.9 confidence, headline+link only with NO provider summary so false attribution cannot surface, empty-result semantics, REFUSED/DATA_UNAVAILABLE on unreachable store, and free/source provenance. This is genuinely beyond what structured fields convey.

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 the framing question are front-loaded, and virtually every clause carries load-bearing information (confidence threshold, caps, absence semantics). It is dense with em dashes and caps, bordering on run-on, but there is little true filler to cut.

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?

Although there is no output schema, the description fully specifies the return envelope {summary, count, items} and each item's fields {borrower, headline, source, url, date}. Combined with the caps and failure-mode notes, an agent has everything needed to call and interpret the tool.

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

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

Schema description coverage is 100% and each parameter already documents its default and hard cap. The description merely restates the same defaults/caps (limit 25/100, since_days 7/90, min_holders 2/50), adding no syntax or interpretation beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource+scope: recent VERIFIED news for private-credit borrowers held across MULTIPLE BDCs. It even supplies the natural-language question it answers ('what broke recently for the cross-BDC borrowers I should watch?'), which cleanly separates it from generic siblings like get_news, search_news_archive and search_bdc_borrower.

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

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

Gives clear context for when to use it (cross-BDC borrower pulse) and an important exclusion-style note that empty results are 'absence, not a signal'. It does not, however, name an explicit alternative (e.g. get_news or search_news_archive) or state when NOT to use this tool, so it stops short of a 5.

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

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

Annotations only declare readOnlyHint, so the description carries the burden and delivers: it warns that each BDC is read at its most recent filing so rows MIX dates and as_of_range must be read before treating marks as contemporaneous, notes debt positions only, names the source (SEC EDGAR schedules of investments, ol-derived), flags FREE, and states caveats ride in tool_notes.

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?

Dense but front-loaded: the core question comes first, then return fields, then the critical as_of caveat, then caps, cross-tool pointer, source and provenance. Every clause carries operational 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?

With no output schema, the description enumerates the returned fields (borrower, borrower_norm, holder_count, holder_tickers, holders, total_fair_value, total_par_amount, as_of_oldest/as_of_newest), discloses caps and data-source caveats — everything an agent needs to call and interpret it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds behavioral meaning by stating the caps as truncation rules (bdc_tickers truncated at 25, limit 50/200, min_holders max 50) and by explaining what min_holders semantically answers ('what is SHARED').

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 with scope: the cross-portfolio borrower intersection across a given set of BDCs, illustrated with a concrete question. It implicitly distinguishes itself from ol_bdc_top_borrowers (single BDC's book) and points to ol_bdc_borrower_dispersion as the follow-on.

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?

Clear when-to-use framing ('common to a GIVEN SET of BDCs') and the schema's min_holders text routes single-BDC lookups to ol_bdc_top_borrowers, with a pointer to ol_bdc_borrower_dispersion for pricing. No explicit when-not-to-use statement beyond that, so not a full 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?

Despite annotations covering only readOnlyHint, the description discloses rich behavior beyond structured fields: flagged_pct is a percentage over the determinate-flag denominator (never total_debt_fv), is deliberately NULL when determinate coverage is under 90% or a parse misread is suspected, trend ordering is oldest-first, quarters is capped at 24, and caveats ride tool_notes. This is exactly the withheld-vs-zero distinction an agent needs.

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?

Dense but front-loaded: the purpose leads, then return shape, then the critical null semantics, then defaults, pairings, and source. Nearly every clause earns its place, though the single long sentence carrying the null/denominator logic is somewhat hard to parse at 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 no output schema, the description carries the full burden and does so: it names the return keys ({summary, ticker, latest, trend}), explains the trend ordering, defines the null-vs-zero behavior of flagged_pct, and points to where caveats live. Nothing an agent needs to interpret the response correctly is missing.

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

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

Schema description coverage is 100%, so the two parameters (ticker, quarters) are already documented with examples and default/cap. The description restates the quarters default and cap but adds no new parameter-level syntax or format detail, so baseline 3 applies.

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

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

States a specific resource and measurement ('share of debt fair value on non-accrual in the latest filing, plus the trailing-quarter trend'), and explicitly names the sibling tools it pairs with. An agent can distinguish this credit-deterioration signal from ol_bdc_top_borrowers or ol_bdc_mark_changes without opening the schema.

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

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

Provides clear usage context: it names the paired tools (ol_bdc_borrower_dispersion, ol_bdc_top_borrowers) and instructs the agent to 'read coverage_state before reading flagged_pct'. It stops short of an explicit when-to-use/when-not statement versus alternatives, so it is clear context without hard exclusions.

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?

Exceptional disclosure beyond the readOnlyHint annotation: missing inputs are returned as named nulls (never zero), unreachable stores are refused with DATA_UNAVAILABLE, internally-managed BDCs carry no fee lines by construction, and the data source (SEC EDGAR 10-K/10-Q XBRL, not a vendor feed) plus free/caveat behavior are all stated. Consistent with readOnlyHint=true.

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 and return shape, then caveats. It is dense and semi-colon packed, but nearly every clause conveys a distinct fact an agent needs (units, ratio interpretation, null/refusal semantics, source). Minor cost in readability, not waste.

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

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

No output schema exists, and the description fully carries that burden: it enumerates the return keys, states units (whole USD), explains the dividend_coverage ratio interpretation (<1.0 means capital-funded), and flags what is NOT returned (fee rates, dividend amount). Nothing needed to call or interpret it is missing.

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

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

Only one parameter and schema coverage is 100%, so the schema already fully documents 'ticker'. The description adds no syntax or format detail beyond confirming it is a BDC ticker, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('BDC fee load + NII-based dividend coverage') and explicitly scopes it to ONE fiscal year rather than a series, which distinguishes it from the sibling time-series tools like ol_bdc_credit_quality or ol_bdc_mark_changes. The return field list confirms exactly what it produces.

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 clarifies scope constraints (single fiscal year, not a series) and notes the internally-managed BDC edge case, but never names an alternative tool or states the conditions under which an agent should prefer this over other BDC tools in the sibling set. Usage is implied rather than routed.

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 only declare readOnlyHint=true, yet the description adds substantial behavioral context: the as-filed column mixes percent and bps so raw spreads must never be averaged (normalized at the store), position counts are parser-grain-dependent, unparsed BDCs return an honest-empty trend=[] rather than erroring, and caveats ride the response's tool_notes. This is well beyond what the annotation provides.

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 dense operational caveats; nearly every clause carries distinct information (units, grain caution, default/max, empty behavior, source). It is information-dense rather than padded, though the packing of many parenthetical asides slightly tests readability.

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

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

Although no output schema exists, the description explicitly names the return shape {summary, ticker, count, spread_unit, trend} and the units, covers the empty-case behavior, the default/max for the only optional param, and the data provenance (SEC EDGAR BDC 10-Q/10-K, Oxford Ledge parse, FREE). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents `ticker` and `quarters` (including the default 16 and max 24), and the description largely restates these. It adds no syntax or format detail beyond the schema, so the baseline 3 applies. Field-level semantics it adds (spread_unit in bps, priced_borrowers vs debt_positions) concern outputs, not inputs.

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

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

States a specific verb+resource+scope: a per-quarter loan-pricing trend for ONE BDC built from the parsed schedule of investments, with the exact metrics (fair-value-weighted average credit spread, average mark, position counts) and ordering (oldest-first). It names the sibling it pairs with (ol_bdc_borrower_dispersion), so an agent can distinguish it from other BDC tools 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?

Gives clear actionable guidance: prefer `priced_borrowers` over `debt_positions` across quarters because position counts are parser-grain-dependent, and it pairs with ol_bdc_borrower_dispersion. It stops short of explicit when-not-to-use or routing among the broader BDC sibling set (e.g. credit_quality, mark_changes), so it's clear context without full exclusions.

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 provide only readOnlyHint=true, but the description adds rich behavioral context beyond that: the exact return shape {increases, decreases}, row fields, the fact that marks are fair-value-weighted percent of par, an inclusion threshold, that implausible moves are diverted to `suspect_moves`, and that `coverage` itemizes unread BDCs. This is far more than the annotation conveys.

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?

Dense but front-loaded: the purpose and quoted question come first, followed by return shape, thresholds, and coverage semantics. Every sentence carries operational value, though the prose is long enough that trimming a clause or two would not lose 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?

With no output schema, the description fully carries the return contract (increases/decreases rankings, row fields, suspect_moves, coverage, tool_notes caveats) plus the call's caps and data source. An agent has everything needed to invoke and interpret the result.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (including the max 25 tickers, default 10/hard 50 limit, and global-vs-per-BDC ranking). The description largely restates these caps rather than adding new parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb+resource with scope: the largest quarter-over-quarter mark moves across a set of BDC portfolios, and even quotes the user question it answers ('which borrowers got marked up or down the most last quarter, and by whom'). This differentiates it from siblings like ol_bdc_borrower_dispersion, ol_bdc_credit_quality, and ol_bdc_top_borrowers, which cover different facets of BDC credit 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 framed question and 'in ONE deterministic call' establish clear usage context, and the eligibility rules (|mark_delta| >= 1.0 point, fair value >= $500k) tell the agent what qualifies. However, it never explicitly names an alternative sibling tool or states when NOT to use it (e.g. vs borrower_dispersion or credit_quality), so exclusions are absent.

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?

Beyond the readOnlyHint annotation, it discloses the ranking tiebreak order, the limit/min_holders caps, that parser mis-ingests are filtered when the filter is available and that `borrower_filters` reports whether it ran, and that caveats ride in tool_notes. That is materially useful behavioral context for a no-annotation-rich tool.

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

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

Front-loaded with the purpose and ranking logic, then output shape, then caps and provenance – good ordering. It is dense with domain jargon and parentheticals, but nearly every clause carries operational information 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?

No output schema exists, yet the description specifies the response envelope {summary, count, borrowers} and the row fields {borrower, borrower_norm, holder_count, total_fair_value, industry}, plus data source, freshness, and cost. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: what min_holders actually gates (minimum BDC lenders a borrower must appear in) and the distinction between holder_count_active and holder_count used for ranking. That meaningfully reinforces the schema's bounds.

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

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

States a precise verb+resource: private-credit borrowers syndicated across the most BDCs, ranked by holder_count_active then holder_count then exposure. It also positions itself as 'the entrypoint for the BDC/private-credit category', distinguishing it from siblings like ol_bdc_common_borrowers and search_bdc_borrower.

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

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

Explicitly routes the agent forward: 'Feed a borrower_norm into ol_bdc_borrower_dispersion for cross-lender pricing', and names itself as the category entrypoint. It does not say when NOT to use it versus the other ol_bdc_* siblings (e.g., ol_bdc_common_borrowers), so it stops short of full when/when-not guidance.

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

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

Far exceeds the readOnlyHint annotation: discloses that only reference data is returned (no price/yield/spread/trade activity, no security identifier), that 'grade' is a source bucket not a credit rating, the limit default/cap, and an explicit provenance/redistribution restriction with caveats surfaced in tool_notes.

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?

Opens with the core purpose and remains information-dense, though the provenance/counsel-memo passage is long. Nearly every sentence carries operational value (formats, caps, restrictions), so the length is mostly justified.

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 no output schema, the description explicitly enumerates the return shape (summary, count, total_matching, bonds) and each bond's fields, and covers limits, grade semantics, and provenance for an 8-parameter tool. Nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters. The description reinforces the grade semantic and limit default/cap, but adds little beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb (Screen) and resource (corporate-bond browse directory) plus the exact filter fields (issuer, grade, coupon, maturity bands). Scope clarifications ('REFERENCE DATA ONLY', 'no security identifier') let an agent distinguish it from search_bonds and get_bond_data without opening schemas.

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

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

Conveys implied context (free, first-party only, screen-by-attributes) and a constraint on offset ('used only when no coupon/maturity band is set'), but never explicitly states when to choose this over siblings like search_bonds. Usage is inferable rather than stated.

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

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

Beyond the readOnlyHint annotation, the description discloses substantial behavior: acquisitions are VERIFIED-only and 'unaudited or refuted events never surface,' results are 'honest-empty when the key is unknown,' same-name footprint matches are 'never a guaranteed identity,' an empty footprint is normal, the source is free, and caveats ride in tool_notes. This is exactly the kind of context annotations cannot provide.

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

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

The description is dense but front-loaded with the purpose and the key-passing instruction first, then the return shape, then caveats. Every sentence carries information — especially the enumerated return fields, which substitute for the missing output schema. It borders on long, but nothing is padding.

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 no output schema, the description appropriately documents the return envelope (summary, borrower_norm, borrower, profile, acquisitions, count, public_footprint) and each sub-field. It also covers edge cases (honest-empty, empty footprint, name-match uncertainty) and tells the agent where caveats live. Complete for an agent to call and interpret correctly.

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

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

Schema description coverage is 100%, so both borrower_norm (canonical key from ol_bdc_top_borrowers) and limit (default 20, cap 100) are already documented in the schema. The description's note that borrower_norm must be the canonical key matches what the schema already says, adding little new syntactic or semantic detail. Baseline 3 for a fully covered 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+resource+scope: 'Profile + verified M&A/ownership history for one private-credit borrower.' It explicitly distinguishes itself from siblings by naming ol_bdc_top_borrowers as the key source and enumerating exactly what it returns (acquisitions, public_footprint), so an agent can tell it apart from ol_bdc_borrower_dispersion, ol_bdc_borrower_news_today, or ol_bdc_common_borrowers.

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 the essential prerequisite — 'Pass the canonical borrower_norm (from ol_bdc_top_borrowers)' — which tells the agent how to obtain a valid key. However it never states when NOT to use this tool or which sibling to prefer for related needs (e.g., dispersion or news on the same borrower), so the routing guidance 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 only declare readOnlyHint=true, so the description carries the rest: mm_* and open_interest are contract counts not dollars, mm_* covers one category per family (Managed Money vs Leveraged Funds), an unreachable store is REFUSED (DATA_UNAVAILABLE), plus source/attribution and computed-field disclosure (mm_net). This is unusually rich behavioral context.

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

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

Dense but front-loaded: the core purpose and the market/omit branch come first, with caveats, limits, and attribution following. Every sentence carries load, though the all-caps emphasis and stacked details make it slightly heavier than 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?

With no output schema, the description still names the response keys, explains field units and which speculative category applies, discloses truncation caps and the failure mode, and points to tool_notes for caveats. An agent has everything required to call and interpret it.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds value beyond it: name normalization examples ('wti', 'GOLD', 'e-mini s&p' resolve), the series-only scope of `limit`, and its default/cap in prose. Minor gaps remain (no note on what an unmatched market returns), keeping it from a 5.

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: CFTC Commitments-of-Traders positioning for three named curated markets, with return shape {summary, market, matched_market, rows}. No sibling tool covers COT positioning, and the description makes the scope 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?

Explicitly says to pass `market` for a weekly history or omit it for the latest all-market snapshot, and notes the series-only restriction on `limit`. Clear within-tool usage guidance, though it doesn't route to alternative sibling tools (none exist for this 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 only declare readOnlyHint=true, so the description carries the behavioral burden and does so richly: it explains the two non-merged data sources, the confidence field, the published_events_degraded pre-check ordering, the data source (issuer IR pages + SEC filing cadence), cost (FREE), and that caveats ride tool_notes.

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?

Dense but front-loaded – the core purpose and the critical 'NOT merged / never present estimate as announcement' warning come early. The response-shape enumeration and sourcing tail are useful but make it longer than strictly necessary; still, every clause adds routing or safety 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?

No output schema exists, yet the description enumerates the return fields (ticker, published_events, published_events_degraded, estimate, provenance_rule, note) and explains the semantics of the ambiguous ones. Combined with the scope caveat, an agent has everything needed to call and interpret it.

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 one parameter, fully documented in the schema ('Issuer symbol.', 100% coverage), so the schema does the work. The description adds no ticker format, exchange, or resolution rules beyond what the schema states. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Upcoming EARNINGS DATES for one issuer') with a clear scope qualifier, and explicitly distinguishes itself from get_economic_calendar (macro releases). An agent can tell it apart from the ~60 sibling tools without opening the schema.

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

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

Gives explicit when-to-use guidance ('prefer a published date yourself'), when-not-to ('never present the estimate as a company announcement'), and a hard scope boundary ('US domestic 8-K filers only'). The alternative tool is named by condition.

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

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

Despite only a readOnlyHint annotation, the description discloses substantial behavior beyond structured data: opaque=true with a `reason` for ETFs with no filed holdings, the rule that a store outage returns DATA_UNAVAILABLE and is never opaque, the ~60-day SEC EDGAR lag, and that caveats ride in tool_notes. This is exactly the behavioral context an agent needs.

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?

Dense but front-loaded with the core purpose before the return-shape detail; nearly every clause earns its place (return keys, opaque handling, source, cost). It is on the long side but not padded or repetitive.

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 no output schema, the description carries the full burden of describing returns and does so thoroughly: it names the top-level keys ({summary, count, etfs, units}), the per-ETF fields, and the per-holding fields including the derived-vs-filed distinction for weight_pct/pct_of_nav. Nothing material is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters (baseline 3). The description adds meaning beyond the schema by stating that top_holdings is 'value-ranked' and confirming the default/hard-cap and per-ETF ticker cap, which usefully characterizes the selection order of the returned rows.

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?

Opens with a specific verb+resource ('ETF look-through: expand ... ETF tickers into the underlying holdings') and immediately scopes the source (fund's own Form N-PORT filings), which distinguishes it from siblings like get_13f_holdings and get_institutional_holders. An agent can tell what this does 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?

The scope note 'HOLDINGS-ONLY: no yield, NAV or premium' usefully tells the agent what this tool is NOT for, and the ~60-day lag + FREE notes help set expectations. However, no sibling alternative is named and there is no explicit 'use X when Y' routing, so usage guidance is only implied.

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?

Reads like a data contract: states units (`asset`/`dep` in thousands), that the store is ACTIVE-ONLY so merged/failed banks are absent by construction, that the store can be REFUSED with DATA_UNAVAILABLE, the `limit` cap behavior, and the critical caveat that `ticker` is an Oxford Ledge mapping not FDIC-published. These go well beyond the readOnlyHint 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 the core purpose, then labeled blocks (UNITS, ATTRIBUTION) make dense content scannable. It is long but nearly every sentence carries operational information; the only minor cost is density.

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?

Despite having no output schema, the description names the return shape ({summary, query?, found?, institutions}), explains units, the active-only constraint, the refusal mode, and attribution limits. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `query` is a prefix (not substring) match restricted to active institutions with largest-asset-first ordering, and `limit` defaults to 25 with a hard cap of 100. This supplements the schema rather than repeating it.

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

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

States a specific resource (FDIC-insured banks and thrifts) and a precise operation: prefix search on `query` against ACTIVE institutions, or the largest active institutions when omitted. The distinction from sibling tools like ol_bank_structure_events is implied via the structure_event explanation, so an agent can select it correctly.

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

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

Explicitly tells the agent when to pass `query` (name prefix) versus omit it (top-by-assets list) and explains the ordering. It also describes the failure mode (DATA_UNAVAILABLE) and the name-miss resolution path (structure_event), but does not name a sibling tool as a direct alternative.

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 only declare readOnlyHint=true, so the description carries the behavioral load and does so richly: partial/in-progress fiscal years with period_complete false and never-compare-to-full-year guidance, DATA_UNAVAILABLE refusal for an unreachable store, crosswalk attribution caveat, public-domain source, and free access. This is well beyond what the annotation provides.

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?

Dense but deliberately front-loaded around 'TWO SHAPES', with each sentence carrying operational content (precedence, partial-FY caveat, units, source, cost). It is long for a 3-param tool and could be tightened, but almost nothing is 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?

Despite no output schema, the description discloses return-shape facets an agent needs (per-FY obligations, ten largest recipients, dropped_unresolved, newest FY first, leaderboard ordering, period_complete flag, tool_notes caveats). Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% (baseline 3), but the description adds real meaning: the ticker-wins precedence rule, `limit` default 20 with hard cap 100, and that fiscal_year alone triggers the leaderboard shape. It stops short of describing the USD units per row beyond naming them, so 4 rather than 5.

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 the specific resource (federal-contract obligation history) and the two distinct output shapes (per-ticker FY series vs fiscal-year leaderboard), using a domain verb ('obligations', 'leaderboard'). An agent can immediately distinguish this from siblings like get_fundamentals or ol_filing_search.

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

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

It explicitly defines the selection rule: one of `ticker` or `fiscal_year` is REQUIRED, and if both are supplied `ticker` wins. It also names the use case (government-revenue-dependence diligence) and warns that the leaderboard covers only the OL crosswalk, not all federal contractors.

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 only declare readOnlyHint=true, but the description adds substantial behavioral context: the daily AI quota (25/day, UTC reset, burst limiter), required auth env vars and the AUTH_REQUIRED failure mode, the metered nature of the call, and the meaning of the fused score. This is exactly the value-add beyond structured fields that earns 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-loads purpose and the metered warning, then packs quota, auth, return shape, and score caveat efficiently. It is dense and repeats k's default/cap from the schema, which costs a point, but nearly every sentence carries needed 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?

There is no output schema, so the description must document returns, and it fully does so: top-level {summary, ticker, count, chunks, quota_remaining_today} and per-chunk {section, text, accession, url, score}, plus the critical caveat that score is a fused rank, not similarity. Nothing needed to call or interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates k's default and cap already in the schema and adds usage context for query, but it does not extend parameter semantics beyond what the schema provides.

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 ('semantic retrieval over EMBEDDED SEC filings for a ticker') with a concrete example question. It also distinguishes itself from all siblings by flagging that it is 'the ONE metered tool', so an agent can place it without opening any other 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?

Clearly conveys when to use it (natural-language questions over filing text) and emphasizes the cost/quota dimension that selects it or not. It does not explicitly name a non-metered alternative sibling to use instead, so the routing guidance is strong but not fully closed.

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 only declare readOnlyHint=true, so the description carries the real burden and delivers: whole-USD disclosed amounts, the crucial semantic that total_offering_amount is a ceiling rather than money raised, the ~1-quarter posting lag that makes short windows empty by construction, the limit default/cap, public-domain FREE source, and that caveats travel in tool_notes. This is materially more than the annotations supply.

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, scope, and return shape before the caveats, and nearly every sentence earns its place. Minor redundancy: the limit default/cap and the quarterly-lag caveat are restated from the schema descriptions.

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 no output schema, the description compensates by naming the return shape ({summary, count, days, industry, offerings}) and flagging that caveats ride in tool_notes. Nothing an agent needs to invoke the tool correctly or interpret the empty-window case is missing.

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

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

Schema coverage is 100%, and the description largely echoes what the schema already states for `days` (quarterly lag) and `limit` (default 50, cap 200). The `industry` filter is named but not embellished. Baseline 3 is appropriate when the schema does the parameter documentation.

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 resource (SEC Form D private-placement filings) with its exact source data set, ordering ('newest first'), and optional scoping axes (industry group, trailing filing-date window). An agent can distinguish this from generic filing search siblings like ol_filing_search 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?

It establishes usage context (recent filings from the quarterly data set, optional N-day window) and warns that a short window is empty by construction, which guides correct invocation. However, it never names alternatives (e.g., ol_filing_search for older or non-Form-D filings) or states when NOT to use this tool, leaving sibling routing to inference.

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

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

With only readOnlyHint=true in annotations, the description carries real behavioral load: it discloses the silent truncation to the first 10 unique tickers, the counterintuitive rule that a missing metric FAILS its criterion, the returned shape, and that caveats ride tool_notes. These are non-obvious traits an agent could not infer from the schema or 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?

Dense but front-loaded: the core mechanics (scope, cap, missing-metric rule, return shape) come first, with the disclaimers trailing. It is slightly packed with caveats, but for a screener with 8 params and non-obvious semantics, each clause 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?

No output schema exists, but the description compensates by enumerating the return envelope (summary, count, passing_count, criteria, results, as_of) and per-result fields, plus the data source and caveat location. Complete enough to call correctly, though it does not explain how empty/invalid tickers are surfaced.

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

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

Schema coverage is 100%, so the schema already documents each parameter, giving a baseline of 3. The description adds units semantics beyond the schema ('whole USD; *_pct as percentage numbers'), clarifying that percent params are passed as plain numbers rather than fractions.

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 (threshold screen) and resource (latest-year SEC EDGAR XBRL fundamentals) with explicit scope (caller-supplied ticker set). It also distinguishes itself from siblings by stating 'It never sweeps a universe and is not a discovery screen,' separating it from get_fundamentals-style lookups and discovery tools.

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

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

Gives clear when-not guidance: not a discovery screen, not a universe sweep, and explicitly not a buy signal. However, it never names the sibling an agent should use instead for discovery or single-name lookups, so the alternative routing is left implicit.

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, so safety is covered; the description adds genuinely useful context beyond that: FREE, Oxford Ledge editorial provenance, and PROFESSOR review status, which matter for trust in a reference tool. It does not add rate-limit or failure-mode details, keeping it short of a 5.

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

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

Front-loaded with the corpus size and content, followed by the lookup form and the reason to prefer it. The provenance/FREE tail is useful but the sentence is dense; a slightly tighter package would read better, though nothing 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?

With no output schema, the description compensates by enumerating what an entry contains (definition, worked example, etymology, pronunciation, related terms, learning paths), so an agent knows exactly what it will get back. For a one-parameter reference tool, nothing material is left unstated.

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

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

Schema coverage is 100% and there is a single documented parameter, so the baseline is 3. The description goes further by stating the matching is case- and punctuation-tolerant and by giving worked lookup strings ('first lien', 'convexity', 'duration'), which is real value about match behavior that the schema does not state.

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 ('Look up one term by name') and characterizes the corpus precisely (~1,500 finance/investing terms). Nothing in the sibling list does glossary lookup, so it is trivially distinguished, and the term examples disambiguate the lookup granularity.

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 an explicit when-to-use rule with rationale: ground explanations in the platform's own definitions 'instead of improvising one.' It lacks explicit when-not-to-use guidance or named alternatives, but no sibling overlaps on this function, so the gap is minor.

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

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

Annotations only declare readOnlyHint, so the description carries the real behavioral load: empty-result semantics, refusal on unreachable store, look-ahead-safe filing-date windowing, that caveats ride in tool_notes, and that the source is free SEC EDGAR Form 4 data. None of this is derivable from the annotations or schema.

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

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

Front-loaded with the value proposition and grain routing, then the return shape, then caveats. Dense with capitalized emphasis, which is slightly noisy, but nearly every clause carries information the agent needs.

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?

No output schema exists, yet the description fully specifies the return envelope ({summary, count, events, grain, since_days, limit}), the per-event fields, and the empty/error cases. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is already 100%, but the description adds semantic routing that the schema does not: which grain each parameter selects, that omitting both triggers the market-wide scan, and how defaults shift per grain (one row per ticker and direction for market-wide). This goes beyond the structured field text.

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 ('scan for ACTIVE multi-insider cluster-buy/sell signals') and immediately scopes it as distinct-actor Form 4 clusters with statistical strength. It is clearly differentiated from siblings like ol_insider_recent_buys and get_insider_activity by emphasizing multi-actor clusters rather than individual trades.

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

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

Explicitly enumerates the three invocation modes (pass `tickers` for a watchlist, a single `ticker`, or neither for market-wide) and states the alternative relationship between `ticker` and `tickers`. It also tells the agent how to read an empty result ('absence is not a signal') and what happens on failure (store unreachable is REFUSED).

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

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

With readOnlyHint already declaring safety, the description adds substantial context: the SAMPLING TRAP (newest N filings, not the whole window) with an explicit warning against totaling rows, hard caps on since_days/limit, which fields are derived, the SEC Form 4 source, and that caveats ride tool_notes.

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?

Dense but front-loaded: purpose first, then return shape, then caps, then the trap, then provenance and siblings. Nearly every sentence earns its place, though the since_days/limit default-and-cap restatements duplicate the schema and cost some 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?

No output schema exists, yet the description spells out the return keys {summary, since_days, count, buys} and per-row fields, covers the sampling caveat, provenance, and where notes live. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including the min_value null-drop and common_only filtering rules. The description largely restates defaults and caps already present in the schema, adding little beyond it, so baseline 3 applies.

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

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

States a specific verb+resource with scope: open-market insider PURCHASES (SEC code 'P') across the ~5.3k-ticker Oxford Ledge catalog, framed as a daily insider screen. It names the siblings it pairs with (ol_insider_cluster_scan, get_insider_activity), so an agent can place it 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?

Gives clear context ('a daily insider screen') and points to related tools it pairs with, plus a critical warning not to treat results as a period total. However it stops short of explicit when-to-use-vs-alternative routing (it never says when to prefer this over ol_insider_cluster_scan or get_insider_activity).

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

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

The readOnlyHint only covers the safety profile; the description goes well beyond it by enumerating every possible verdict value and stressing they are 'never coerced to neutral', listing the returned sub-objects, disclosing the source (SEC EDGAR 13F-HR + Form 4), stating there is no tier gate or AI metering, and noting caveats ride in tool_notes. This is unusually rich behavioral disclosure for a read-only tool.

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

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

Front-loaded with the core purpose and result shape, and nearly every clause contributes unique information (source, verdict semantics, return fields, metering). It is dense and somewhat long, but no sentence is redundant with the structured fields, so only mild trimming would be warranted.

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 no output schema available, the description carries the return-value burden and does so by enumerating the verdict enum and the institutional/insider/cluster/coverage/summary payload. Combined with the source attribution, metering, and caveat location, an agent has everything needed to call and interpret it.

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?

There is a single parameter and schema coverage is 100%, so the schema already documents the ticker argument; the description only reinforces that it takes one ticker and gives no additional syntax, format, or edge-case detail. Baseline correct when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Quarter-aligned institutional-confluence read for one ticker') and names the three data sources fused (13F accumulation, insider Form 4 net buying, buy-cluster confirmation). It explicitly positions itself against siblings by noting it is 'a DERIVED verdict, not raw data: no per-fund rows' and naming get_institutional_holders and ol_insider_cluster_scan as its pairs, so an agent can distinguish it from those 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?

The 'Pairs with get_institutional_holders and ol_insider_cluster_scan' line and the 'DERIVED verdict, not raw data' contrast give clear context for when to reach for this fused read over the raw-holder siblings. However, it never states an explicit when-not condition (e.g., cases where the underlying raw tools are preferable), so it stops short of full routing guidance.

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

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

With annotations only declaring readOnlyHint, the description carries the behavioral burden and does so richly: fixed model constants, FCFE-style DCF that is not EV-comparable, null-on-negative/missing-inputs semantics, and caveats surfaced in tool_notes. This is exactly the kind of beyond-schema disclosure that matters.

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 packed with high-value caveats; nearly every clause earns its place. It is dense and long-ish, but not padded.

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?

No output schema exists, yet the description enumerates the return keys, units (USD per share), null semantics, and explicitly warns that price/market cap/margin of safety are absent. An agent has everything needed to call and interpret the result.

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 one parameter (ticker) with 100% schema description coverage, so the schema already defines it fully. The description adds no ticker-specific syntax, format, or lookup behavior, so baseline 3 applies.

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

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

States a specific verb and resource (per-share intrinsic value from SEC EDGAR XBRL) and enumerates the three distinct models used, which clearly separates it from generic siblings like get_fundamentals or ol_value_investing_fact.

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 actionable usage context: fetch a price yourself to compare, retry on transient 'fetch_error', and interpret nulls via null_reasons. It does not, however, explicitly position itself against sibling valuation tools like ol_value_investing_fact or ol_peer_fundamentals.

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?

Goes well beyond the readOnlyHint annotation: it discloses absence semantics (value=null with is_absence=true is a valid answer, explained by metric_availability), confidence gating that EXCLUDES needs_review rows, provenance (issuer's own metric definitions, SEC 10-K/10-Q/8-K/6-K exhibits), and that caveats ride the response's tool_notes. These are non-obvious response behaviors an agent must know.

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

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

Front-loads purpose, then absence semantics, then filters, then the sibling routing, then source — every clause earns its place. The all-caps emphasis and dense telegraphic packing make it busy but not 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?

With no output schema, the description carries the return-value burden and does so well: row shape, null/is_absence rows, metric_availability, excluded needs_review rows, and tool_notes caveats. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so the parameters are already documented (the ticker description even explains the deliberate no-cross-issuer constraint). The description restates the optional filters (metric, period, industry) but adds no syntax, format, or interaction detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource+scope: a 'Tier-3 KPI PANEL for ONE issuer' returning curated per-issuer metric rows. It enumerates the metric family (ARR, RPO/cRPO, NRR, logo retention, DAU/MAU, capacity utilization) and names the sibling it is not, so an agent can distinguish it from ol_operating_kpis 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?

Gives an explicit alternative and the condition that selects it: 'For broad operating KPIs across 26 configured industries use ol_operating_kpis.' It also states the hard usage constraint ('Per-issuer by design') and that no cross-issuer read exists, leaving 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?

With only readOnlyHint=true provided, the description carries the behavioral burden and does so richly: live SEC EDGAR latency warning (seconds per issuer, minutes cold), coverage limits (parsed schedules only, unscheduled issuers named never estimated), data provenance, the leverage-heuristic caveat for by_rating, units, and that caveats ride tool_notes.

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?

It is dense but front-loaded: the resource and outputs lead, followed by units, caveats, coverage, and latency. Nearly every clause earns its place, though the run-on sentences and parenthetical emphases (NOT, only, FREE) are heavier than strictly necessary.

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

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

For a two-param, no-output-schema tool, the description is complete: it names the returned aggregations, units, data source, coverage edge cases, latency, and the vision into tool_notes, leaving nothing an agent needs to call it correctly unstated.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description reinforces the tickers scoping (market-wide vs max 50) but adds little beyond the schema and never mentions by_sector at all, so the baseline 3 applies.

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

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

States a very specific verb+resource: 'scheduled bond/loan maturities aggregated by year,' and enumerates the aggregation outputs (total_by_year, by_rating, top_issuers_by_year, peak_year, concentration). However, it never distinguishes itself from the close sibling get_debt_maturities, so an agent cannot disambiguate the two from the text 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?

It clarifies scoping behavior ('Market-wide when `tickers` is omitted, or scoped to up to 50 tickers'), which is useful context. But there is no explicit when-to-use guidance, no exclusions, and no routing to the sibling get_debt_maturities, so usage is only implied.

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 only carry readOnlyHint=true, so the description must carry the rest, and it does: anonymous vs keyed row limits, AS-REPORTED and confidence-gated values, the ambiguity of available=false (uncovered industry vs empty issuer vs outage), a no-retry directive, and provenance/caveat surfaced in tool_notes. This is exactly the operational context an agent needs before calling.

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 scope are front-loaded, and most sentences earn their place (auth tiers, retry prohibition, panel shape). It is dense and slightly meandering in places, but no sentence is 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 no output schema, the description still enumerates the returned panel fields {ticker, industry, metrics, available, partial, total_metrics, period, as_of, provenance, caveat, ...} and explains the semantics of available/partial. It covers sourcing, auth behavior, and caveat delivery well enough to call correctly.

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

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

There is a single parameter with 100% schema coverage, so the schema already documents ticker with examples and even the no-cross-issuer rule. The description adds only the 'per-issuer by design' framing, which is already echoed in the schema text. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description names a specific resource (industry OPERATING KPIs) and scope (ONE issuer) and illustrates it with concrete metrics (same-store sales, RevPAR, load factor, medical-loss ratio, net interest margin, TEU, rig count) sourced from SEC filings. That is far more than a restated name. It stops short of a 5 because the very close sibling ol_issuer_kpi_panel is never contrasted, leaving the agent to infer which per-issuer KPI tool to pick.

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 real usage context: anonymous callers cap at 3 rows while keyed callers get the full panel, and it explicitly warns not to retry with variations when available=false. It also states the per-issuer constraint. It lacks any named alternative tool for when a different KPI view is wanted, so it is clear context rather than full when/when-not 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 only declare readOnlyHint, so the description carries most of the burden and does so well: it discloses that split-suspect pairs are withheld with as-filed counts, that counts are complete while limit only bounds row lists, that share classes are never netted, and that CUSIP resolution makes figures approximate. These are exactly the behavioral traits an agent needs. Slight gap: no explicit note on auth or rate limiting, though a FREE public-domain SEC source implies none needed.

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?

Dense but front-loaded: the core purpose leads, followed by return shape, then limit semantics and caveats. It is long and parenthetical-heavy, but nearly every clause conveys a distinct behavioral fact 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?

No output schema exists, so the description enumerates the return keys ({summary, ticker, quarters_analyzed, counts, new_positions, ...}) and explains the tricky fields (counts vs limit, split_suspect). For a read-only analytics tool this leaves nothing an agent needs missing.

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

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

Schema coverage is 100% and the schema already documents the limit default/cap, so baseline would be 3. The description adds real value beyond the schema by clarifying the crucial limit-vs-counts interaction (counts complete regardless), which prevents misinterpretation of the returned tallies.

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

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

States a specific verb+resource+scope: 'Quarter-over-quarter institutional accumulation/distribution for one ticker' with the classification buckets spelled out. It explicitly frames itself as the 'who is moving on X?' flow read and names the sibling it complements, so an agent can distinguish it from get_institutional_holders (snapshot) 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?

Tells the agent when to reach for this vs the alternative: 'Complements get_institutional_holders (snapshot)' frames the delta-over-time use case against the point-in-time one. Combined with the explicit classification semantics (new/increased/decreased/exited), the selection criteria are clear.

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

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

Far beyond the readOnlyHint annotation: discloses never-cached behavior, delayed-quote marking at read time, auth requirements with the specific AUTH_REQUIRED failure mode for the stdio server, the honest-empty {has_portfolio:false, how_to_start} response instead of an error, and _meta.disclaimer / tool_notes caveats. This is exactly the behavioral context annotations cannot carry.

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 and response shape, then packs auth, caching, and empty-state facts efficiently. Dense and clause-heavy, but nearly every sentence conveys a distinct operational fact.

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 no output schema, the description enumerates the returned keys ({portfolio, positions, totals, position_theses, summary, has_portfolio}) plus the optional recent_trades shape and the empty-state payload, and covers auth, freshness, and cost. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100%, and both parameters already document defaults and the 1..50 range, so the description's mention of include_history and history_limit largely restates structured data. Baseline 3 is appropriate.

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

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

States a specific verb/resource with unusual precision: 'YOUR paper (practice) portfolio on Oxford Ledge', and pins it to the same snapshot as the /practice/ web sandbox. It is clearly distinguished from live-portfolio siblings by the repeated 'paper/practice' framing, though it never names a sibling like get_portfolio_positions to contrast against.

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 implies context (caller's own portfolio only, requires auth) and offers the include_history toggle, but gives no explicit when-to-use/when-not guidance or routing to an alternative tool. Usage is inferable rather than stated.

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

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

Annotations only declare readOnlyHint=false, so the description carries the burden and delivers richly: dry-run default, idempotency/ replay semantics ('without placing twice'), rejection being a normal non-error response, API-key/OAuth requirement (browser cookie refused), and a 20-fills-per-UTC-day cap. These are exactly the beyond-annotation traits an agent needs.

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 'WRITE (opt-in)' and organized around the operational flow. It is dense and long, but for a stateful two-step mutating tool nearly every sentence earns its place; only the restated share/side ranges are mildly redundant with the schema.

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

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

Despite no output schema, the description discloses the response shapes ({dry_run...}, {replay: true...}), auth needs, rate limits, and the practice-money disclaimer location (_meta.disclaimer). Nothing an agent needs to call and safely relay results is missing.

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

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

Schema coverage is 100% (baseline 3), but the description adds real meaning about the interaction between parameters: that the _idempotency_key returned by the dry run must be reused to execute, and framing thesis as the USER's own reason rather than the agent's. It largely restates the ranges (shares 1..1,000,000) already in the schema, so it stops short of a 5.

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 ('place a market order') and resource ('YOUR paper (practice) portfolio') with scope, and explicitly distinguishes itself from siblings by noting it is 'One of TWO mutating tools here (the other is reading_list_annotate).' An agent can identify it without opening any schema.

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

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

Gives explicit when-to-use (placing paper trades), the default-and-recall procedure for the dry run, the exact condition to execute (_dry_run: false plus the same _idempotency_key), and names the alternative mutating tool. Nothing is left to inference.

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

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

With only readOnlyHint=true as annotation coverage, the description carries the full burden and does so richly: it discloses the continuation-vs-grant TRAP, that an unreachable store is REFUSED with DATA_UNAVAILABLE (never a false count 0), that data freshness equals the last on-demand ingest, and the attribution boundary where `ticker` is not a USPTO field. This is exactly the extra behavioral context annotations don't provide.

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?

Dense but front-loaded: purpose first, then return shape, then limit semantics, then the trap, then provenance/attribution. Every sentence adds distinct information, though the heavy capitalization and length make it more of a wall of caveats than a lean definition.

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

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

For a 2-param tool with no output schema, the description spells out the return shape ({summary, ticker, count, filings}), ordering (NEWEST FIRST), the meaning of `count`, freshness, failure behavior, and licensing/attribution. Nothing an agent needs to call or interpret this is missing.

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

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

Schema coverage is 100%, so both `limit` and `ticker` are already documented in the schema. The description largely restates the limit default/cap and clarifies that `count` reflects filings returned rather than total hits, which is marginal added value. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Recent USPTO patent filings') plus the analytical intent ('innovation-intensity diligence'), and the resource (patent filings) is clearly distinct from every sibling, which cover 13F, bonds, BDC, insider, etc. An agent can tell instantly what this returns.

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?

Frames the use case (innovation-intensity diligence) and constrains scope ('recent slice, never a full portfolio') so the agent knows what question it answers. It doesn't name an explicit alternative tool or exclusion condition, but no sibling overlaps, so guidance is clear without being 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?

With only readOnlyHint available, the description carries the behavioral burden richly: silent truncation to the first 6 unique tickers, missing-XBRL tickers returned as {available:false} rather than dropped, one cold EDGAR fetch per ticker (latency hint), and the data source. This is well beyond what annotations provide.

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 constraints and return shape. Dense but every sentence earns its place -- truncation behavior, return keys, unit conventions, fiscal-year caveat, and edge case are all load-bearing.

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?

No output schema exists, but the description fully specifies the return envelope {summary, count, peers, as_of} and per-peer keys, plus unit conventions (whole USD, *_pct as numbers) and the non-aligned fiscal-year caveat. Nothing an agent needs to call and interpret it is missing.

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

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

Schema coverage is 100% and documents the 2-6 array, but the description adds critical semantics the schema omits: extras are dropped silently and it's the FIRST 6 unique tickers that are kept. That clarifies de-duplication and truncation order, which the schema alone does not convey.

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 ('side-by-side latest-fiscal-year fundamentals for a peer set') and immediately differentiates from the sibling get_fundamentals by declaring 'ONE YEAR ONLY -- no history (use get_fundamentals).' An agent can identify this tool's 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?

Names the alternative for historical data explicitly and clarifies what the tool cannot do ('no price leg, so no P/E or EV multiples'). It provides clear context for when to reach for it, though it doesn't spell out a full when-not-to-use matrix beyond the history 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?

With only readOnlyHint=true in annotations, the description carries the full behavioral burden and does so richly: oldest-first ordering, reporting lag, as_of being the settlement date not today, honest-empty for unpublished tickers, and DATA_UNAVAILABLE refusal on an unreachable store. It also declares source and that it is free.

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 identity and return shape before the caveats, and every clause (ordering, units, lag, empty/refusal behavior) carries information. Some phrasing is dense and slightly redundant, but there is little pure 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 no output schema, the description must describe returns itself, and it does: names the top-level fields and specifies each point as exactly {date, shortPct}, explicitly excluding share counts and days-to-cover. Edge-case behavior is also covered, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented. The description largely repeats the schema ('default 6, max 26') but adds interpretation by translating max 26 into 'about one year', which is marginal added meaning over the structured field.

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: the FINRA biweekly settlement-date short-percent series for one ticker. No sibling covers short interest (get_fails_to_deliver and ol_cftc_cot are adjacent but distinct datasets), and the description pins down the exact series, ordering and unit.

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 implied clearly (trend of short interest for one ticker), and it usefully warns this is a lagged fortnightly snapshot rather than a live short-float figure. However it never states when to reach for this tool vs an alternative, nor names a sibling, so routing guidance is only implicit.

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 only provide readOnlyHint=true, but the description adds real behavioral context: units (millions USD with a worked example), the component-plus-Total row trap that causes double-counting, the limit default/cap, and an explicit DATA_UNAVAILABLE refusal mode. These are exactly the traits annotations cannot convey, so this is well above baseline. Not a 5 only because return-format details (keys, ordering) remain thin, since no output schema exists to fill the 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 purpose, then the argument logic, then units and caveats in priority order; every sentence carries information. The all-caps emphasis on IGNORED, REFUSED, AMOUNTS, and FREE is slightly noisy, costing it the top mark, but nothing is padding.

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 3-param, zero-required read tool with no output schema, the description covers everything needed: the return shape ({summary, rows}), the double-count hazard, units, the limit cap, a failure mode, licensing, and where caveats live. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the per-parameter descriptions already define limit and the security fields, giving a baseline of 3. The description adds value beyond the schema by explaining the interaction rule between security_type and security_class and by clarifying the '_' sentinel for Total rows and that limit applies only to series mode.

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 resource and source: 'US Treasury debt composition from the Monthly Statement of the Public Debt.' It also distinguishes itself from the overlapping sibling by naming get_yield_curve, so an agent can separate the two without opening schemas.

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

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

Gives explicit branching rules: omit both args for the newest month's full breakdown, pass security_type AND security_class together for a single class's history, and warns that passing only one is IGNORED. This is when-to-use guidance tied directly to argument combinations, not just a vague context hint.

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 only declare readOnlyHint=false, so the description carries the real weight and delivers: default dry-run behavior with a described proposal payload, idempotency/replay semantics, the AUTH_REQUIRED failure mode, tier gating, and the guarantee that notes can never be published. This is a mutation tool whose side effects and failure modes are fully 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 the operation type and the dry-run default, then layered requirements and error behavior. Caps-for-emphasis keep it scannable, and every sentence (idempotency, auth, privacy, char cap) carries distinct operational 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?

No output schema exists, but the description compensates by sketching the return shapes ({dry_run: true, tool, args, idempotency_key, message} and {replay: true, ...}). With mutation semantics, auth, and tier requirements all covered, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: slug must already exist on /reading-list, the 500-char body cap, and that _idempotency_key can be reused to guarantee replay safety. It does not explain key auto-derivation beyond what the schema states, keeping it short of a 5.

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?

Opens with a specific verb+resource+scope: 'save or update YOUR private note on an Oxford Ledge reading-list entry,' and immediately distinguishes itself as one of TWO mutating tools, naming the other (ol_paper_trade). An agent can identify exactly what this does and how it differs from its write peer.

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

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

Gives explicit when-to-use (saving/updating a private reading-list note), names the alternative mutating sibling, and lays out the exact execution protocol: dry-run by default, then re-call with _dry_run: false and the same _idempotency_key. Prerequisites (Plus tier, authenticated caller) and the local-stdio limitation are spelled out.

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

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

Without needing annotations to carry the load, it discloses the 45-60 day EDGAR lag, fuzzy-match semantics, that `description` is a compiled public-source profile rather than filing text, the above-par mark trap, and that caveats ride in the response's tool_notes. These are behavioral traits the readOnlyHint annotation does not convey.

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?

Dense but front-loaded: the core function and the returned key lead, followed by return fields, then traps and caveats. Every clause carries information, though the telegraphic stacking of warnings is near the limit of compactness.

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 no output schema, the description carries the full return-value burden and does so: it enumerates borrowerName, borrowerNorm, description, descriptionSource, industry, the four aggregate fields, and the per-tranche `holders` rows. Combined with pagination and miss semantics, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond it: it clarifies that limit/offset page `holders` only while the aggregate fields stay over CURRENT holders, and restates the 3-character minimum. This scoping clarification is the kind of detail the schema doesn't spell out.

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

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

States a precise verb+resource: 'Which BDCs lend to one private-credit borrower, matched fuzzily on name,' and names the underlying source (SEC EDGAR BDC schedules of investments, ol-derived, not filer-published). This cleanly separates it from siblings like ol_bdc_top_borrowers and search_company without opening their schemas.

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

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

Gives clear situational context: it returns borrowerNorm, 'the key the ol_bdc_* tools take,' which tells the agent this is the entry point that feeds the BDC analytics siblings, and warns a miss is {found: false}, not a finding of no exposure. It stops short of naming a specific alternative tool or a when-not condition, so it's clear context without explicit 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?

Goes well beyond the readOnlyHint annotation: it discloses that NO network call is made, the sub-millisecond latency, the exact response object including status, note, use_instead, query, empty issuers, totalBonds: 0 and error, and warns that the empty lists are the retired shape rather than a search result. It also explains the licensing/redirect cause. Fully consistent with readOnlyHint=true.

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 RETIRED (2026-09-13) so the critical fact lands first, and the deprecated-return payload is enumerated precisely rather than vaguely. It is dense and slightly long, but the aside about the wheel and licence-class registries pinning the name is the only part that could be trimmed.

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

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

With no output schema, the description inlines the entire returned object shape, confirms no side effects or network access, and gives the exact migration paths. An agent has everything needed to decide not to call it and what to call instead.

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

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

Schema coverage is 100% and the single 'query' parameter is already documented as an issuer name in the schema, so the description only echoes it as part of the return shape. Baseline 3 applies; no additional syntax or format guidance is given or needed.

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

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

The description states unambiguously that this is a RETIRED issuer-name bond search over FINRA TRACE that answers no query, and it names the two replacement tools for the two distinct intents (corporate-bond discovery vs. one issuer's maturity schedule). An agent can distinguish it from ol_bond_directory_screen, get_bond_data and get_debt_maturities without opening any schema.

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

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

Explicit when-not-to-use (the tool answers no query) plus two named alternatives with the condition that selects each: ol_bond_directory_screen for corporate-bond discovery with issuer/grade/coupon/maturity filters, get_debt_maturities for a single issuer's maturity schedule. Nothing is left to inference.

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

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

Annotations only declare readOnlyHint=true, and the description adds substantial beyond-schema behavior: a hard cap of 20 matches, null fields being omitted from rows, the tickerStatus field that must be checked before treating a match as live, the literal-substring matching rule, the Oxford Ledge source column allowlist, and the fact that caveats ride in the response's tool_notes.

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?

Information-dense and front-loaded: identity, return shape, cap, matching rule, caveats, next step all appear in order with little waste. It loses a point for the garbled clause 'plus the other class-share punctuation', which is hard to parse and slightly blunts an otherwise tight passage.

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 no output schema, the description carries the return contract and does so fully: {results, count}, the field list per row, and the null-omission rule. Source, matching limits, cap, and caveat location are all covered, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100% and the schema already describes the single query parameter, so the baseline is 3. The description goes beyond it by specifying what forms actually resolve (name, ticker, digit-only CIK, class-share punctuation) and that substring matching means misspellings fail, which materially changes how an agent should craft the query.

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: 'Resolve a company name, ticker or CIK to its SEC identity.' The identifier-resolution framing cleanly distinguishes it from sibling search tools such as search_bonds, search_news_archive and ol_filing_search, which search different corpora.

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