Oxford Ledge

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

Annotations provide only readOnlyHint, and the description fills the gap extensively: the exact return shape ({cik, fundName, filingDate, periodOfReport, totalHoldings, totalValue, holdings}), row-level fields, the CUSIP licence restriction, 'do NOT sum across types' guidance, ~45-day EDGAR delay, and a concurrency limit. This is far beyond what annotations 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?

Front-loaded with what the tool returns, then input forms, then payload shape and caveats; nearly every clause carries distinct operational information. It is dense and clause-heavy in places, but for a tool with no output schema that density is largely earned.

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 explain return values — and it does, enumerating the envelope and row fields, noting what is stripped (cusip) and what is absent (ticker). Combined with the resolution and concurrency 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 real semantics: that resolution is recorded in `resolved_from`, that ambiguous names are refused with candidates rather than guessed, and that there is NO ticker field with `title_of_class` acting as the share-class discriminator. That reinforces the fund parameter's resolution contract beyond the schema 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 — the largest positions one institutional filer holds in its latest SEC 13F-HR, plus quarter-over-quarter changes. It is distinguishable from siblings like get_institutional_holders, get_institutional_consensus, and ol_13f_filer_analytics 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?

Clear context for use: one filer, latest 13F filing, with QoQ change framing, plus operational guidance ('Heavy operation, max 2 concurrent') and the input-resolution contract that governs correct invocation. It stops short of explicitly naming an alternative tool or a when-not-to-use condition in the description text (the ol_13f_filer_search fallback appears only in the schema).

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 from annotations, the description carries the burden and delivers: field-level return shape, newest-first ordering, limit default 50 / hard cap 200, is_activist defined as a form-type label rather than a judgement, and a FRESHNESS section explaining that keyless callers get stored rows and never trigger the EDGAR refresh (read stale/stale_basis). 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?

Dense but front-loaded, moving from purpose to return shape to caveats to freshness. Each sentence carries distinct information, though the run-on density is at the upper edge of what stays readable.

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 object, row fields, ordering, pagination limits, a semantic caveat on reports_zero, and freshness behavior. 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 both parameters are already documented, and the description's limit/default/cap details largely restate the schema. Baseline 3 is appropriate; the description adds no parameter meaning 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+resource (Schedule 13D/13G >5% beneficial-owner filings for a ticker) and explicitly distinguishes itself from 13F and from siblings like get_institutional_holders and get_institutional_consensus. An agent can identify exactly what this returns 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 clear interpretive routing: cross-check get_institutional_holders before treating reports_zero as a sale, and notes it complements get_institutional_consensus. It frames usage well but does not state an explicit 'use this instead of X when...' selection rule.

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 readOnlyHint=true, the description discloses the return shape, the exact enum-like severity values ('red' or 'amber', red first), the available:false semantics, the skipped-screen caveat for empty flags, the data source, and the API-key/operator-config requirement. This is a rich behavioral disclosure that annotations alone would 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-loads the action and the return contract, and the parenthetical screen list is dense but informative rather than filler. The long enumeration with 'and others' is slightly unwieldy, but every sentence carries usable 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 specifies the return object ({ticker, available, flags, count} and the flag fields), the severity domain, and the failure mode. It also covers the auth prerequisite, leaving nothing an agent needs in order 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?

The single parameter (ticker) is fully documented in the schema at 100% coverage, so the schema does the heavy lifting. The description adds no format or constraint detail beyond what the schema already states, giving the expected baseline of 3.

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 with their thresholds, so an agent knows exactly what is computed. The enumerated content (short interest, Altman Z, net leverage, etc.) cleanly separates it from generic sibling tools like get_fundamentals or ol_fundamentals_screen.

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 how to interpret results ('a flag is a question to investigate, NOT a sell signal') and names complementary tools ('Pair with get_fundamentals and ol_intrinsic_value'). It lacks explicit when-not-to-use guidance or a stated alternative for pure screening, 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 cover only readOnlyHint=true, and the description adds substantial behavioral context beyond that: the reconciliation block semantics, the warning to read fairValueBasis before totalFairValue, the note that fairValueGap means an under-counting parse that UNDERSTATES book value, and the disclosure that figures are Oxford Ledge's parse rather than filer-published. These are exactly the caveats an agent needs to avoid misusing output.

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 scope and the key routing cue, and every clause carries information (scope, return shape, caveats). It is dense and the long run-on clause enumerating return fields is heavy, 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 must carry the return contract, and it does: {bdcs, count} plus the full per-BDC field list and the reconciliation block. Combined with the parse-fidelity caveats, an agent has everything needed to call and interpret this 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?

There are zero parameters, so there is nothing to disambiguate; the description confirms 'No arguments.' Baseline for a no-param tool is 4, and no additional semantic value is possible or missing.

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: 'Roster of the ACTIVE BDCs tracked by Oxford Ledge, sorted by portfolio size.' The scoping clause 'our coverage, not the whole BDC universe' plus the named borrower-keyed sibling (search_bdc_borrower) lets an agent distinguish it from the many 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?

Clear usage context: active-only, wound-down issuers excluded by design, and no arguments required. It also points to the alternative (search_bdc_borrower) for borrower-keyed needs. It stops short of stating the exact condition that should route an agent to that alternative or away from the other ol_bdc_* tools, so it is slightly below 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?

Goes well beyond the readOnlyHint annotation by disclosing the failure semantics (available=false means no verified row and ABSENT provenance keys; unreachable store is REFUSED with DATA_UNAVAILABLE), a provenance staleness caveat for rows generated before 2026-09-13, and the free/first-party sourcing. This is exactly the operational 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 purpose before the return-shape and caveat detail, and nearly every sentence carries distinct information. It is dense and backtick-heavy, which slightly impedes scanning, but there is little genuine 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 enumerates the returned fields (summary, available, business_summary, short_summary, provenance), explains the summary-vs-content distinction, and covers failure modes and a known data quirk. Nothing an agent needs to call and 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?

Only a single 'ticker' parameter with 100% schema description coverage, so the schema already documents it. The description says 'for a ticker' but adds no format or edge-case meaning beyond what the schema provides; 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: a first-party business summary for a ticker sourced from the SEC annual report, with exact form/item references (10-K Item 1, 20-F Item 4). It explicitly distinguishes itself from the sibling ol_filing_search ('For semantic passage retrieval over the full filing corpus use 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?

Names a concrete alternative (ol_filing_search) and the condition that selects it, which is more than most definitions offer. It stops short of a full when/when-not treatment (e.g., no guidance on when to prefer get_company_profile-style siblings or caching), so it is clear context without complete 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 only declare readOnlyHint=true, yet the description discloses substantial extra behavior: a 24h cache, a Researcher-tier auth requirement, an IFRS refusal path ('never served zeros'), and pre-split share-count withholding. It also warns that netBuybacks is a derived dilution proxy rather than a true buyback figure, which prevents a serious misreading.

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 is front-loaded in the first clause, and every sentence carries load-bearing information (return shape, caveats, refusal behavior, source, cache, tier). It is dense and parenthetical-heavy, but no sentence is redundant, so it earns its length.

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 object and its parallel-array alignment, plus source, cache duration, tier requirement, and refusal/withholding edge cases. An agent has everything needed to call it and interpret results 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?

With a single parameter at 100% schema description coverage, the schema already documents ticker and the description adds nothing parameter-specific. The extra detail it provides (fiscal labels, newest-first ordering, parallel arrays) describes output shape, not parameter semantics, 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 ('Where a company sent its cash') with a concrete scope ('up to 30 annual labels'), and explicitly names the complementary siblings get_fundamentals and get_debt_maturities. An agent can distinguish this from other fundamentals-family 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?

The phrase 'Complements get_fundamentals and get_debt_maturities' gives implied routing context, and the Researcher-tier requirement plus the IFRS refusal effectively constrain when it can be used. However, there is no explicit when-to-use-vs-alternative guidance or exclusion criteria, 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 declare readOnlyHint=true, so the description carries the rest and does so well: hard 20-item cap, newest-first ordering, dual-class union (GOOG/GOOGL), refusal with DATA_UNAVAILABLE rather than an empty array, and ~7-day re-index cadence. This is unusually rich behavioral disclosure; a 4 rather than 5 only because the exact failure/return semantics could be tightened.

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 behavior (20 most recent, newest first, hard cap) in the first sentence, and every subsequent clause carries distinct information (return shape, category constraint, dual-class union, failure mode, alternatives). It is dense to the point of being run-on, which slightly hurts readability, 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?

No output schema exists, so the description supplies the return contract itself: {ticker, events, count, coverage, summary} with the per-event fields enumerated. Combined with the failure-mode and source/indexing 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by clarifying that event_type matches STORED CATEGORIES ONLY and that alias terms like acquisition/merger are refused (INVALID_PARAMS), steering callers to the correct stored vocabulary. It goes beyond the schema's parameter documentation without contradicting 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+scope: the 20 most recent 8-K item events for a ticker, sourced from Oxford Ledge's 8-K index of SEC EDGAR, newest first. It distinguishes itself from siblings by naming get_insider_activity and the acquisition_disposition category, so an agent can route 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 the tool as a recent-events feed rather than a history ('hard cap with no caller-settable limit'), and routes the agent elsewhere for related needs: 'for M&A use acquisition_disposition' and 'For Form 4 insider transactions use get_insider_activity.' Both when-to-use and when-not are covered.

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 rest of the burden and does so: unit convention (millions, not raw dollars), the as-of-filing-date caveat with the risk that the current-year bucket is already repaid, refusal_reason/refusal_note on empty results, and the Researcher-tier requirement. These are exactly the non-obvious traits an agent needs before quoting numbers.

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 what the tool is and its units caveat, then layers validation, refusal, alternative-tool, source and tier notes. The field enumeration earns its place because there is no output schema to document the return shape.

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

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

For a single-parameter read tool with no output schema, the description covers return shape, units, temporal caveat, refusal behavior, prerequisite tier, and a sibling alternative. 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?

Only one parameter (ticker) with 100% schema description coverage, so the schema already documents the input fully. The description adds no syntax or format detail beyond the schema, 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 ('Forward debt maturity ladder parsed from the latest 10-K/20-F footnote'), including the exact source document. It explicitly distinguishes itself from get_capital_allocation, so an agent can separate it from the closest sibling 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?

Names the alternative and the condition that selects it ('For historical issuance/repayment use get_capital_allocation'), and instructs the agent to consult `validation` before quoting a total. This is explicit routing rather than implied usage.

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 behavioral load and does so richly: return shape, the critical 'ALWAYS CHECK source_status' failure-mode warning (every failure returns events=[], indistinguishable from a quiet calendar), 6h caching, FRED as source, and a required operator-configured API key. This is material context an agent could not infer from annotations.

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

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

The description is front-loaded with the resource and scope, then layers the return shape, exclusions, limits, and source. Every sentence carries information, though the heavy parenthetical/em-dash stacking makes it slightly dense to parse quickly.

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 correctly compensates by spelling out the return object ({days, events, count, source_status, error}) and the per-event fields. Combined with the auth prerequisite and the source_status caveat, nothing needed to call or interpret 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?

Schema coverage is 100% and the single param is self-documenting, so the baseline is 3. The description adds real semantics beyond the schema's 'maximum 180' by stating that values above 180 are REFUSED and that the default is 90, clarifying the failure behavior rather than just the bound.

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

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

The description names a specific verb+resource ('Upcoming US macro DATA-RELEASE DATES') and scopes it precisely with an enumeration of the 9 tracked releases. It explicitly excludes adjacent concepts ('a schedule, not estimates', 'FOMC meeting dates are NOT included'), which distinguishes it from siblings like get_fred_data, get_corporate_events, and ol_earnings_calendar.

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 context is clear: this is for forward-looking release dates, not values, and the 9 covered releases are listed so an agent knows whether its target release qualifies. It also flags the days limit rule. It stops short of explicitly naming an alternative tool for actual/prior values (e.g. get_fred_data), so it is strong but not a full routing statement.

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 readOnlyHint=true, it discloses rich behavioral traits: the `days` window is anchored to the latest LOADED settlement date (not today), empty/thin history reflects loaded SEC files rather than absent fails, prices are NOT split-adjusted, an unreachable store REFUSES with DATA_UNAVAILABLE, and data is published twice monthly with ~3-week lag. These are exactly the traps an agent would otherwise misread.

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 before diving into caveats, and every clause carries information (units, anchoring, refusal behavior, cadence). It is dense and long, but little is expendable; a minor trim of redundant window wording could tighten it.

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

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

With no output schema, the description fully specifies the return shape ({ticker, days, history, count, window, coverage, as_of, summary} and per-row fields) and warns how to read `coverage`/`summary` before trusting a gap. Nothing an agent needs to call and 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 material meaning: it clarifies the LOADED-settlement-date anchoring of `days` and that `end_date` re-anchors the window elsewhere, which goes beyond the schema's own text. It also pins units (fails in SHARES, price in USD).

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 ('SEC fails-to-deliver history for one ticker') and immediately frames its analytical role ('the settlement-failure side of short pressure'). It explicitly distinguishes itself from the sibling it complements: 'Pair with ol_short_interest_trend for the other half.' An agent can place it without opening the schema.

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

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

Gives clear context (short-pressure analysis, pairing with ol_short_interest_trend) and a concrete usage rule: read `coverage` and `summary` before interpreting a gap, and pass today's date via end_date to measure against the calendar. It stops short of explicit when-not-to-use exclusions, but the routing guidance is strong.

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 substantial extra context: it documents the returned object shape, latest-only behavior, out-of-snapshot error behavior, third-party licensing refusals, and the need for an Oxford Ledge API key. This goes well beyond the annotation and gives the agent the operational and access constraints it 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?

The description is long and dense, but the length is justified by the tool's licensing, auth, and output-shape complexity. It is generally front-loaded with the core purpose before exceptions, though the all-caps refusal section is somewhat run-on.

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

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

Given the lack of an output schema, the description adequately explains the return object for successful and error/refusal cases. It also covers licensing restrictions and API-key requirements, leaving little ambiguity for an agent trying to call 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?

The schema already documents the single series parameter at 100% coverage with examples, so baseline credit applies. The description adds meaningful constraints beyond the schema by indicating the parameter must identify a series in the snapshot and that specific FRED ids such as BAMLH0A0HYM2, VIXCLS, and UMCSENT are refused.

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 action and resource: retrieving one FRED macro series from Oxford Ledge's snapshot by FRED id. It clearly distinguishes scope from history-oriented or curve-oriented siblings by stating it returns the newest observation only, never 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?

It defines when the tool is appropriate: one series from the approximately 41-series snapshot, identified by FRED id, with latest-only output. It also states key exclusions such as series outside the snapshot and licensed series that are refused, though it does not explicitly route the agent to an alternative sibling tool.

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

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

Annotations only provide readOnlyHint, so the description carries the rest and does so richly: parallel-array alignment, null-vs-0 convention, WITHHELD pre-split per-share cells with a pointer to `basis`, the {error,...} return for IFRS/no-fact filers, source, ~45-day lag, and 24h cache. This is well beyond what the annotation declares.

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

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

Front-loaded with purpose then return shape, and nearly every clause carries distinct semantic value (array alignment, units, null handling, withheld cells, error shape, alternatives, source). The density is justified for a rich return payload, though it reads as a dense block rather than cleanly segmented lines.

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 (and does) fully specify the return contract including the field list, index alignment, units, null semantics, and the error variant. Nothing an agent needs to interpret or trust 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?

Only one parameter (ticker) with 100% schema description coverage, so the schema fully documents it. The description adds no syntax, format, or edge-case meaning for the ticker argument itself; baseline 3 applies 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 ('Full XBRL financial history for one ticker') and immediately scopes what it returns. It explicitly routes to siblings ('For cash deployment use get_capital_allocation; for per-share fair value ol_intrinsic_value; for industry operating metrics ol_operating_kpis'), so an agent can distinguish it from get_capital_allocation and ol_operating_kpis 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?

Names three specific alternatives with the condition that selects each, which effectively tells the agent when to choose something other than this tool. The scope statement (full XBRL history for one ticker) plus the alternative routing leaves no ambiguity about task fit.

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 rest and does so richly: the hard 20-row cap, the dedup of 4/A repeats, the warning to exclude issuerSelfFiled rows from totals, the origin of totalValue, and the isDerivative caveat. It discloses the exact quirks that would otherwise cause wrong answers.

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 load-bearing constraint (20 rows only) is front-loaded in caps before any other detail, and sibling routing is compressed into a single sentence. It is dense and long, but nearly every clause conveys a real 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?

With no output schema, the description fully specifies the return shape (ticker, transactions and every row field), the cap, dedup behavior, and exception handling, plus the source and tier. Nothing an agent needs to call or interpret this correctly is missing.

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

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

Schema coverage is 100%, establishing a baseline of 3, but the description goes further by restating and stressing the crucial semantics that `days` only filters within the 20 newest rows and 'never reaches past the 20' - a limit that materially changes how an agent sets the parameter. It adds emphasis beyond the schema 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 ('Recent Form 4 insider transactions for one ticker') and immediately distinguishes itself by naming the alternative data sources for market-wide buys, clusters, and activist stakes. An agent can select this over get_activist_stakes or ol_insider_cluster_scan without opening another 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 routes to alternatives: 'Market-wide buys: ol_insider_recent_buys; clusters: ol_insider_cluster_scan; >5% stakes: get_activist_stakes.' It also states the tier prerequisite ('Requires Researcher tier'), which is a real gating condition the agent needs.

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

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

Annotations supply readOnlyHint=true, so the safety profile is covered externally. The description adds real operational context beyond that: common-stock-only scope, ownership-tally-not-exposure framing, per-fund differing latest quarters, SEC EDGAR 13F-HR source, and ~45-day quarterly delay. These are meaningful behavioral disclosures, though it stops short of noting rate limits or error conditions.

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

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

Purpose is front-loaded, followed by return shape, parameter effects, scope caveats, sibling routing, and data source. It is dense but every sentence carries distinct information; 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 fully carries the burden and delivers: it enumerates the return object and row fields, ranking order, truncation behavior, data provenance, and freshness delay. An agent has everything needed to call and interpret results.

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, but the description adds non-obvious meaning: top_n truncates only the `consensus` array while min_funds governs the FULL `tickers_found` count, with defaults and caps restated. This clarifies how each parameter interacts with specific output fields, 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?

The opening sentence states a specific verb and resource: which tickers the tracked 13F filers most widely hold in common. It further distinguishes itself from sibling get_13f_holdings via the 'who is buying X?' vs 'what does fund X own?' contrast, 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?

It explicitly names an alternative (get_13f_holdings) and the question each tool answers, giving a clear selection rule. The 'COMMON STOCK ONLY: an ownership tally, not exposure' note further bounds when its output is and isn't appropriate.

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 full return shape, the true-vs-displayed holder distinction, coverage.basis semantics, common-stock-only scope, per-row quarter variance, CUSIP resolution failure behavior, and the ~45-day 13F delay. This is rich, decision-relevant behavioral context.

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

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

Front-loads the purpose sentence, then organizes output fields and caveats compactly. Dense and slightly long, but nearly every clause carries actionable 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?

For a complex 13F-holdings tool with no output schema, the description carries the return-value and caveat burden well, covering structure, coverage interpretation, resolution risk, and data latency. 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 limit parameter is already fully documented in the schema. The description restates the default/max and confirms total_holders and coverage are unaffected, but adds little syntax or semantics beyond what the schema already provides. 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 ('which institutions hold one ticker, and which way they moved') and explicitly distinguishes itself from siblings ('Direction-only view: ol_ownership_changes; fund-keyed inverse: get_13f_holdings'). An agent can route correctly 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 context and names two alternatives with their differing shapes (direction-only vs fund-keyed inverse), plus a 'check coverage.basis before quoting an aggregate' precondition. Lacks a crisp when-to-use/when-not statement, but the routing is clear.

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

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

Beyond the readOnlyHint annotation, the description discloses the default limit (25), hard cap (100), absence of pagination offset, that the response shape changes with the arguments, that 'sentiment' is a label not a number, that matching is prefix-word rather than semantic, and that a configured API key is required. 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, with scope first and the crucial response-shape warning capitalized for emphasis. The all-caps sentences are justified by the risk they flag, though the description is on the longer side.

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 explicitly, documenting both possible shapes ({articles, total} vs {articles, count} with richer rows). For a read tool whose annotation already covers safety, 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 baseline is 3, but the description adds genuinely new semantics: query matching is 'prefix-word, not semantic' and 'sentiment' is a label string. That goes beyond the schema text and materially affects how an agent builds a 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 ('Read the Oxford Ledge news archive by ticker and/or keyword, newest first'), so an agent immediately knows what it does. It does not, however, differentiate itself from the sibling 'search_news_archive' or 'ol_bdc_borrower_news_today', leaving overlap ambiguous.

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 'by ticker and/or keyword' phrasing implies when the tool fits, but there is no explicit when-to-use versus the sibling 'search_news_archive', nor any exclusion. Usage is implied rather than stated.

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

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

Goes well beyond the readOnlyHint annotation: exact return shape on every path, the absence of a price leg (no price/market value/gain/weight), the empty-list-on-unknown-id behavior, and the API-key auth requirement. This is unusually rich disclosure for a read tool.

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

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

Front-loads what it returns and what it lacks; every sentence carries information. The capitalized emphasis ('ONLY', 'THERE IS NO PRICE LEG') is slightly noisy but justified for preventing hallucinated price fields.

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 return object, its fields, sorting, null semantics, and failure behavior. 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?

Schema coverage is 100% and there is a single optional portfolio_id already documented with its default, so the schema carries the parameter meaning. The description only adds that an unknown id yields an empty list, which is behavioral rather than syntactic.

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 ('Stored positions of one saved portfolio') and explicitly distinguishes itself from the sibling get_sector_breakdown for the catalog-wide sector mix. An agent can identify it without inspecting the schema.

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

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

Names the alternative tool and the condition that selects it (sector mix -> get_sector_breakdown), and warns that an empty list does not prove existence. It does not spell out broader when-to-use/when-not scenarios, but gives clear 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?

Goes well beyond the readOnlyHint annotation: reveals the bare-list return shape, that totalMarketCap is ALWAYS null (critical to avoid misreading results), that rows are sector+industry pairs requiring aggregation, blank-sector exclusion rules, single-sector industry assignment logic, the {error} dict on failure, and the data source with ~5,200 tickers. This is rich behavioral context that no structured field 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 every sentence earns its place, front-loading the scope distinction and following with return-shape and edge-case caveats. No filler; the ALL-CAPS emphasis on key gotchas (BARE LIST, PAIR, IS ALWAYS NULL) aids fast scanning.

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 fully compensates by documenting the return structure, nullability, aggregation requirement, exclusion rules, and error shape. An agent has everything needed 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?

Zero parameters, so baseline is 4. The description correctly notes 'No arguments', sparing the agent from speculating about filters, which is the right content for a zero-param tool.

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 ('splits across sectors and industries') and explicitly scopes it as the whole catalog, not a portfolio. This differentiates it from portfolio-oriented siblings like get_portfolio_positions and ol_etf_lookthrough without the agent needing to open a schema.

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

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

Explicitly names the alternative for portfolio-scoped data ('For a named portfolio use get_portfolio_positions'), routing the agent correctly. It does not enumerate other when-not conditions, but the catalog-vs-portfolio distinction is the primary decision an agent faces here.

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 heavy extra context: text is not verified against primary sources, must not be presented as the author's exact words unless `verbatim` is true, must be credited with the `attribution` line, and results are cached 24h per argument set. This is exactly the kind of non-obvious behavioral constraint annotations cannot express.

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 resource, the verification caveat, and the argument-dependent return shapes all appear in order of decision relevance. No sentence is filler, including the caching note.

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

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

No output schema exists, so the description compensates by specifying both return shapes ({facts, count, total_facts} vs {fact, total_facts}) and the 10-item cap. Combined with the attribution and verbatim rules, an agent has everything needed to call it and to report results responsibly.

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, but the description adds real meaning: `query` results are capped at 10, a bare `category` or no arguments yields a single random pick, and an invalid category is refused with INVALID_PARAMS naming the valid values. It goes beyond the schema rather than restating 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 pair: retrieving a curated value-investing principle, historical fact or attributed paraphrase from Oxford Ledge's ~2,000-entry corpus. The corpus size, named authors (Buffett, Graham, Munger, Klarman) and pedagogical framing clearly separate it from quantitative siblings like ol_intrinsic_value or ol_glossary_term.

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 describes the two usage modes (query for search, bare category or no arguments for a random pick) and adds a clear scope boundary: 'Pedagogical content only -- never a market signal.' It does not, however, name a specific alternative sibling for when an agent should prefer a different tool.

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

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

With only readOnlyHint available, the description carries substantial extra load: it discloses units (percent, with a worked example), the 4h cache, the data source (Treasury.gov par yields with FRED fallback), and that OAS/UMCSENT were removed — all beyond what annotations or schema say. It stops short of stating freshness guarantees or failure behavior when the fallback triggers.

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 critical "TWO DIFFERENT SHAPES" warning and every sentence carries information (shapes, default, units, removals, source, cache). It is on the dense side and leans on shouty capitalization, 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?

There is no output schema, so the description must describe return values — and it does, for both modes, including the tenor range, the comparison dates, and the macro series mixed in. Combined with units and source, an agent has everything needed to call and interpret this 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%, so a 3 is the baseline, but the description adds genuine meaning the schema omits: the parameter doesn't just "include history," it switches the entire response shape (parallel arrays over 11 tenors at three dates vs. a flat latest-value list mixing macro series). That materially changes how an agent should set 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 (US Treasury yield curve) and its scope (plus the wider macro dashboard), with unusually precise detail on what comes back. It does not, however, distinguish itself from siblings such as get_fred_data, which also surfaces FRED-sourced series — the description even mentions FRED fallback/series without clarifying the division of labor.

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 a real use case for the non-default mode ("for steepening/inversion work") and clearly marks the default, which implies when each shape applies. But it names no alternative tool and sets no explicit when-not-to-use boundary, leaving selection against get_fred_data or get_economic_calendar 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?

Beyond the readOnlyHint annotation, it discloses the denominator semantics (reported long-equity value, explicitly NOT AUM), edge-case behavior (a single stored quarter yields no fabricated turnover rate), and a named failure mode (unreachable store REFUSED with DATA_UNAVAILABLE), plus the data source. This is rich 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 and slightly heavy on capitalization, but front-loaded with the core purpose and every clause carries operational information (return shape, denominator, exclusions, edge cases, source). Little 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?

Although there is no output schema, the description enumerates the return keys ({summary, fund, quarter, n_positions, reported_long_equity_value, analytics}) and covers the failure modes, so 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% and the schema already documents 'fund' as a CIK with an example, so baseline would be 3. The description adds real value on top: it warns the value must be numeric and that a ticker will not resolve, which affects how the agent should supply the 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 precise verb+resource: derives institutional-filer behavior (concentration, turnover, persistence) from 13F holdings for one filer. It clearly distinguishes itself from siblings by naming ol_13f_filer_search for CIK resolution and get_13f_holdings for position lists.

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 states the input precondition (numeric CIK; a ticker will not resolve here), the tool to use instead when you lack the CIK (ol_13f_filer_search), and the tool to use instead when you want raw positions (get_13f_holdings). 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 available, the description carries the burden and delivers: curated narrow universe (never live EDGAR full-text), prefix-match ranking, refusal semantics on unreachable store, and data provenance. This is substantial behavioral context 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 and alternative routing, then return shape, then universe caveat. Dense but each clause carries signal; a few length/cap details repeat the schema and are slightly redundant.

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 fully specifies the return object shape ({summary, query, filers:[{cik, name, last_filing, page_url}], count}) and the empty/error cases, so 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 3-80 char and 10-cap constraints are already documented; the description largely restates them. It does add one semantic beyond the schema, the 'name-PREFIX matches rank first' ordering behavior, which lifts it above the baseline 3.

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 ('Resolve a 13F FILER name to its CIK') and immediately distinguishes itself from siblings by naming get_13f_holdings, ol_13f_filer_analytics, and contrasting with search_company which 'resolves ISSUERS'. An agent can route without opening another schema.

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

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

Explicitly frames itself as 'the front door' to the holdings/analytics tools for when the manager is known but the CIK is not, and names search_company as the alternative for issuers. It also gives the when-empty vs when-unreachable distinction (filers=[] vs DATA_UNAVAILABLE).

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 behavior beyond that: newest-first ordering, is_failure from the CHANGECODE taxonomy, name resolution across active AND closed charters, the resolved_from field, ambiguous-candidate return behavior, and the DATA_UNAVAILABLE error contract. This is rich disclosure for a read 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?

Effectively one dense paragraph, front-loaded with what the tool returns before the parameter and error guidance. Every clause carries information, though the run-on length is slightly heavier than ideal.

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 a readOnlyHint annotation, the description still conveys result ordering, key flags (is_failure, resolved_from), ambiguity handling, and error semantics. An agent has everything needed to call it correctly and interpret failure modes.

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 meaningfully extends the schema: it explains the cert-vs-name tradeoff, that name resolution spans closed charters, and the resolved_from/ambiguous outputs that follow from parameter choice. It adds semantics rather than restating types.

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 structural events for one bank) plus the event types covered and ordering, and explicitly distinguishes itself from sibling ol_fdic_bank ('active institutions only'). An agent can tell it apart from the sibling 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 about which parameter to pass (cert or name), what happens when name is ambiguous ('call again with the cert'), and which sibling to prefer for active-institution questions. Nothing about when-to-use 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 from annotations, the description carries real behavioral weight: exited positions are excluded by default and include_stale=true reveals them, default 25 lenders with a hard cap of 100, one row per lender sorted widest-spread-first with nested tranches, and the SEC EDGAR schedules-of-investments source. The units trap note ('spread' mixes percent and bps across filers; compare on spread_bps only) is exactly the kind of hazard disclosure 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?

Front-loaded with the concept and a concrete example, then the required parameter, then return shape, then the units warning and defaults — sensible ordering with no filler sentences. It is dense on a single block of prose, and the enumerated return keys are a bit listy, but each element carries information given there is no 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 and no rich annotations, the description compensates fully: it describes the return shape ({summary, borrower_norm, count, lender_count, tranche_count, lenders}), row granularity and ordering, the parameter sourcing path, pagination-style caps, staleness handling, units trap, and the upstream source. An agent can call this correctly without further discovery.

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 materially extends it: the units trap on spread vs spread_bps, the fact that 'spread' is the raw as-filed value, and the resolution behavior of borrower_norm (key or human name, resolved via match_type). The hard cap and nesting semantics for limit are corroborated in both places.

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

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

States a specific verb and resource — cross-lender loan-pricing dispersion for a single borrower — and illustrates the exact signal ('one BDC marks S+550 @ 98, another S+575 @ 99'). It is distinguishable from siblings like ol_bdc_common_borrowers, ol_bdc_mark_changes and ol_bdc_credit_quality 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?

It routes the agent to the right source for the required key (ol_bdc_top_borrowers, search_bdc_borrower, or a raw name) and states the default/exclusion behavior for stale positions. It never explicitly contrasts itself with adjacent analysis tools such as ol_bdc_mark_changes, so the when-to-use-this-vs-that guidance is implied rather than 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?

Beyond readOnlyHint, it discloses verification policy (matcher-VERIFIED, >=0.9 confidence), payload limits (headline + link only, no provider summary, so false attribution cannot surface), caps and defaults for all three knobs, the empty-result semantics (items=[] is not a signal), and the DATA_UNAVAILABLE refusal path. Auth (operator-configured free API key) and cost (FREE) are also stated.

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 the operator question, then return shape, then constraints – a good information ordering with no filler. It loses a point for duplicating the schema's cap/default numbers (limit 25/100, since_days 7/90) in prose, which is redundant with the input 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 having no output schema, it documents the return shape ({summary, count, items} with per-item fields), the empty and error outcomes, the data source, and the auth requirement. 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 description coverage is 100%, so defaults and hard caps for limit, since_days, and min_holders are already in the schema; the description largely restates them. The one added nuance is the framing of min_holders as a cross-BDC requirement, which the schema also conveys. 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 the private-credit borrowers held across MULTIPLE BDCs', and pins the cross-BDC holder threshold. This clearly separates it from siblings like search_bdc_borrower (a search tool), ol_borrower_profile (entity profile), and generic get_news/search_news_archive.

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 directly with the operator question 'what broke recently for the cross-BDC borrowers I should watch?', which tells an agent when this tool fits. It also warns that absence is not a signal and that an unreachable store is refused, but it never names an alternative tool or an explicit when-not 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?

Goes well beyond readOnlyHint=true: warns that each BDC is read at its most recent filing so rows MIX filing dates and instructs the agent to read as_of_range before treating marks as contemporaneous. It also discloses the debt-positions-only scope, the bdc_tickers truncation at 25, the limit and min_holders caps, and the SEC EDGAR source.

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 example question, and every sentence carries operative information (return fields, date mixing, caps, routing, source). It is dense and slightly run-on in places, but there is no filler.

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

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

With no output schema available, 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) plus units, so an agent can consume the result without guessing. All caps and defaults are stated.

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 interpretive value by framing the set as an intersection and clarifying that min_holders governs what is SHARED rather than one book's depth. It also clarifies that bdc_tickers is truncated (not rejected) at 25, which the schema's 'max 25' does not specify.

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 -- 'borrowers common to a GIVEN SET of BDCs' -- and crystallizes it with a concrete cross-portfolio question ('what do ARCC, OBDC and AGTC all lend to?') in one call. It is immediately distinguishable from the sibling ol_bdc_top_borrowers, which covers one BDC's book.

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 defining use case (intersection across multiple BDCs) and explicitly routes the alternative case elsewhere: 'for one BDC's book use ol_bdc_top_borrowers'. It also tells the agent what to do next -- feed a borrower_norm into ol_bdc_borrower_dispersion for cross-lender pricing.

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 behavioral burden and does so richly. It discloses returned fields, oldest-first trend ordering, the determinate-flag denominator, NULL withholding under 90% coverage or parse misread, and the need to read coverage_state before flagged_pct.

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 signal and keeps every clause substantive, but it is a dense single paragraph with several parenthetical caveats. It is efficient for the complexity, though not ideally structured for quick scanning.

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 takes responsibility for return values and does so: it names {summary, ticker, latest, trend}, explains trend order, and clarifies the critical flagged_pct/coverage_state semantics. For a two-parameter read-only tool, the description is complete.

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

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

Schema description coverage is 100%, so the schema already documents ticker and quarters. The description repeats the default/cap and ticker examples but adds little parameter-level meaning 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 signal: BDC non-accrual credit deterioration, defined as share of debt fair value on non-accrual plus trailing-quarter trend. It distinguishes itself from siblings by focusing on non-accrual credit quality and explicitly pairs with ol_bdc_borrower_dispersion and ol_bdc_top_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?

Implies usage as a BDC credit-quality check and notes related sibling tools, but does not state when to choose this tool versus the alternatives or when not to use it. The guidance is contextual rather than 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?

With only readOnlyHint available, the description carries the burden and delivers well beyond it: explicit return shape, units (whole USD vs ratio, '0.92 means 0.92x'), interpretation rule (under 1.0 = dividend partly funded from capital), missing-input policy (null, named, never zero), a refusal error code (DATA_UNAVAILABLE), and the internally-managed BDC edge case.

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 scope constraint and return shape come first, then the semantics of the ratio, then failure modes and caveats. Nearly every clause carries operational value, though the source/licensing sentence is the least essential.

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 explain returns — and it does, enumerating every returned key with its units and interpretation while covering error, null, and edge-case behavior. Nothing needed to call or interpret 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?

Single parameter with 100% schema coverage, so the schema already documents the ticker and its examples. The description adds no parameter-specific syntax or format guidance, 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 resource (BDC fee load + NII-based dividend coverage) with an explicit scope qualifier ('ONE fiscal year (not a series)'), which immediately separates it from time-series siblings. An agent can identify the exact artifact produced 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 clear context for when the tool applies: single fiscal year rather than a series, one BDC issuer, SEC EDGAR Statement-of-Operations filing data rather than a vendor feed. It does not name an alternative sibling or state exclusions, so it stops short of the top band.

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 goes well beyond: bps normalization at the store and the warning never to average a raw spread (as-filed column mixes percent and bps), honest-empty behavior (trend=[] for an unparsed BDC), oldest-first ordering, and FREE data provenance. These are exactly the operational caveats an agent needs to interpret and trust the output.

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 and scope come first, then unit normalization, then metric-preference guidance, then defaults and empty-state. Every clause earns its place, though the semicolon-heavy single block is 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 still names the return shape ({summary, ticker, count, spread_unit, trend}), the units (basis points), the empty case, and the data source/parse lineage. An agent has everything required to call it 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 description coverage is 100%, so both parameters are already documented; the description restates the quarters default/max and clarifies ticker is one BDC but adds no format or constraint detail beyond the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('per-quarter loan-pricing trend for ONE BDC') plus the exact computed fields (fair-value-weighted average credit spread, average mark, position counts) and the underlying data source (parsed schedule of investments). The 'ONE BDC' scoping and 'OLDEST-FIRST' ordering make it immediately distinguishable from siblings like ol_bdc_borrower_dispersion.

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

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

Gives concrete in-tool guidance ('Prefer `priced_borrowers` over `debt_positions` across quarters: position counts are parser-grain-dependent') and names a pairing sibling (ol_bdc_borrower_dispersion). It stops short of stating when to choose this tool over an alternative tool or when not to use it.

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

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

With only readOnlyHint=true in the annotations, the description carries rich extra context: inclusion thresholds (|mark_delta| >= 1.0 point, fair value >= $500k), how implausible moves are diverted to `suspect_moves`, what `coverage` reports, ticker/limit caps, and the SEC 10-K/10-Q source. This is well beyond anything the annotations 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 answering question are front-loaded, and the dense sentences each carry substantive rules (thresholds, caps, output keys). It is information-rich rather than padded, though the packed run-on style slightly reduces skimmability.

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 enumerates the return shape ({increases, decreases}, row fields) and the auxiliary fields (suspect_moves, coverage). For a two-parameter read-only query tool, everything needed to call and interpret it correctly is present.

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, including the caps and the GLOBAL-ranking note. The description largely restates those facts (capped at 25, limit default 10 / hard 50 per direction) rather than adding syntax or format meaning, so the baseline 3 holds.

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-over-quarter mark moves across a set of BDC portfolios — and frames it with the exact question it answers ('which borrowers got marked up or down the most last quarter, and by whom'). This is clearly distinguishable from siblings such as ol_bdc_credit_quality or ol_bdc_borrower_dispersion 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?

The quoted question supplies an implied use case, and 'in ONE deterministic call' hints at it being the consolidated option, but the description never names alternatives or when NOT to use it. Usage context is present but alternatives are left to inference against a large BDC sibling set.

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 well: default/hard caps on both params, the default min_holders, the parser mis-ingest filtering and the `borrower_filters` flag reporting whether it ran, data freshness ('latest filings'), and provenance ('SEC EDGAR BDC schedules of investments (Oxford Ledge parse); 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?

Dense but front-loaded: purpose and ranking come first, then return shape, then caps and caveats. Every clause carries information, though the packed semicolon-run format is heavier than ideal for quick scanning.

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 documenting the return envelope {summary, count, borrowers} and per-row fields including the borrower_norm key and unit conventions ('whole USD, latest filings'). Combined with caps, defaults, and the data source, an agent has everything needed to call and interpret this 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 the description's param information (limit default 25/hard 100, min_holders default 2/max 50, 'lenders a borrower must appear in') restates what the schema already declares. It adds marginal value through the holder-count ranking semantics but does not extend the parameters meaningfully, 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 (rank private-credit borrowers syndicated across the most BDCs) and self-identifies as 'the entrypoint for the BDC/private-credit category'. The ranking key (holder_count_active, then holder_count, then exposure) is spelled out, so an agent can distinguish it from sibling borrower tools like ol_bdc_common_borrowers or search_bdc_borrower 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?

It explicitly routes the agent downstream: 'Feed a borrower_norm into ol_bdc_borrower_dispersion for cross-lender pricing', and states the entrypoint role for the BDC category. It lacks explicit when-not-to-use guidance (e.g., versus ol_bdc_common_borrowers or search_bdc_borrower), which keeps it 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?

Beyond the readOnlyHint it discloses a great deal: the grade field is a source bucket not a rating, coupon bands are applied in-tool over a fetched page, there is a hard cap of 100, auth requires a free first-party API key, and a provenance/redistribution caveat. This is exactly the kind of 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 return shape, and nearly every sentence carries operational value. The provenance/legal-review clause is long, but it conveys a material constraint for agent use, so it largely earns its place.

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

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

No output schema exists, yet the description spells out the return envelope ({summary, count, total_matching, bonds}) and each bond field. Combined with auth, limits, and filter semantics, an agent has everything needed to call and interpret this 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 already 100%, so baseline is 3, but the description adds real interpretive value: it clarifies grade is a bucket not a credit rating, restates the 25/100 limit behavior, and notes coupon filters operate over the fetched page. It adds meaning beyond 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 verb ('Screen') and resource (corporate-bond browse directory), then enumerates the filterable facets (issuer, grade, coupon, maturity). It is immediately distinguishable from sibling screeners like ol_fundamentals_screen or ol_maturity_wall.

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 scopes what the tool is for (reference-data screening) and explicitly excludes what it cannot do ('no price, yield, spread or trade activity, and no security identifier'). It does not name an alternative tool for those excluded needs, so it falls short of the top mark.

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 rest and does so richly: acquisitions are VERIFIED-only (unaudited/refuted never surface), same-name footprint matches are 'never a guaranteed identity', empty footprint is normal, honest-empty on unknown key, and the data source is attributed. This is meaningful behavior beyond the 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?

Purpose is front-loaded, followed by input then return shape, and every clause carries information (caveats, provenance, source). It is dense and the inline return-field enumeration runs long, which slightly hurts scanability but not substance.

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, and the description compensates by enumerating the return keys (summary, profile, acquisitions, count, public_footprint, matched_entities provenance) and their semantics. An agent has everything needed to call it 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%, so baseline is 3, but the description adds value by explaining that borrower_norm may be a stored key or a name and is 'resolved to the stored key (see match_type)', plus that limit caps M&A/ownership events. This exceeds what the schema alone conveys.

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 ('Profile + verified M&A/ownership history') and scopes it to 'one private-credit borrower', which separates it from the BDC-borrower list/aggregate siblings. It also names ol_bdc_top_borrowers as the upstream key source, so the agent can place it in the tool chain.

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 explains the input path (a key from ol_bdc_top_borrowers, or a name) and the honest-empty behavior, which is useful context. But it never says when to prefer this over alternatives such as search_bdc_borrower or ol_bdc_borrower_news_today; the usage guidance is implied rather than stated.

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

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

Annotations only mark readOnlyHint, so the description carries the behavioral burden; it discloses ordering (NEWEST FIRST), return keys, unit semantics (CONTRACT counts, one category per family), limit defaults/caps, and DATA_UNAVAILABLE refusal. Rich and non-contradictory.

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 scope and market keys, then proceeds through usage, return shape, units, limit, errors, and attribution. Dense but every sentence adds needed context for a financial data tool; no obvious 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?

Given two optional params, no output schema, and readOnly annotation, the description covers all an agent needs: valid markets, alias handling, ordering, units, limits, and error behavior. Complete.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds alias examples and clarifies `limit` applies only to series, but most semantics are already in 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 dataset (CFTC Commitments-of-Traders positioning) and the exact curated markets (gold, crude_oil, sp500), so an agent can tell it apart from generic financial siblings. The verb 'Pass/omit' clarifies the operation.

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?

Explains when to pass `market` (weekly history) vs omit it (latest all-market snapshot), and documents alias resolution. It does not name alternative tools or when-not to use this one, so 4 rather than 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 cover readOnlyHint=true, so safety is handled; the description goes well beyond that by disclosing provenance semantics, that the two date sources are NOT merged, the meaning of the degraded flag, cost (FREE), and the underlying sources. It stops short of describing pagination/latency, but for a read-only data lookup this is substantial 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, then provenance, then the return shape, then scope and sibling differentiation. Dense with jargon and several back-to-back constraints, but each sentence carries distinct operational information and nothing is redundant.

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 enumerating the return object fields ({ticker, published_events, published_events_degraded, estimate, provenance_rule, note}). Combined with the provenance rules, scope, and sibling exclusion, 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% and there is a single required ticker parameter, so the schema already documents it fully. The description adds only the framing that the result is scoped to 'one issuer', which is marginal but consistent. 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?

Specific verb+resource ('Upcoming EARNINGS DATES for one issuer') with an explicit scope and an explicit sibling exclusion ('Distinct from get_economic_calendar (macro releases)'). An agent can distinguish it from macro-calendar and corporate-events 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 explicit when-to-use and when-not guidance: 'prefer a published date yourself', 'never present the estimate as a company announcement', 'Read published_events_degraded before reading the note as an issuer fact', plus the SCOPE constraint (US domestic 8-K filers only). Routing and handling conditions are all stated rather than 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 declare readOnlyHint, so the description carries most of the behavioral burden and does so well: it discloses the N-PORT source, latest-period basis, ~60-day lag, FREE status, value-ranked top_holdings, derived weight caveat, and error semantics (opaque=true with reason vs DATA_UNAVAILABLE for outages). This is rich, actionable context 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 the primary action and highly information-dense, with almost every clause carrying necessary return, source, or limitation detail. The single long paragraph is a bit run-on and could be more scannable, but it is appropriately sized for a tool with no 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?

Because there is no output schema, the description must explain the return contract, and it does: it names the top-level and per-ETF fields, clarifies units, ranking, and non-summing weights, and covers the no-holdings and outage cases. For a read-only data-retrieval tool with minimal annotations, nothing essential appears 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 would be 3, but the description adds meaning by saying top_holdings is value-ranked and confirming the default 10 / hard cap 50 behavior. It also clarifies tickers are ETF symbols capped at 25, beyond what the schema alone conveys about how the parameter is interpreted.

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, and scope: 'expand up to 25 ETF tickers into the underlying holdings the fund ITSELF filed on Form N-PORT.' The Form N-PORT source distinguishes it from the sibling 13F holdings tools, so an agent can identify it without opening the schema.

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

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

Gives clear context and scope exclusions: 'HOLDINGS-ONLY: no yield, NAV or premium,' plus the 25-ticker limit and N-PORT filing basis. It does not explicitly name alternative tools for users who need fund fundamentals or NAV data, but the intended use is unambiguous.

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

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

Annotations only declare readOnlyHint, so the description carries most of the burden and delivers: units (asset/dep in thousands), an ACTIVE-ONLY store with the merge/fail consequence, the DATA_UNAVAILABLE refusal on an unreachable store, and the `ticker` attribution caveat. This is exactly the behavioral 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 purpose and return shape, then units, store scope, error state, and attribution. Dense and telegraphic but every clause carries information; the ALL-CAPS emphasis aids scanning without adding 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 still describes the return shape ({summary, query?, found?, institutions}), units, active-only scope, error behavior, limit bounds, and source/attribution. 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 baseline is 3, but the description adds value beyond the schema: `query` is a prefix (not substring) match scoped to active institutions with largest-asset-first ordering, and it reinforces the limit default/cap. Prefix vs substring semantics are genuinely useful.

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 the exact lookup behavior: name-prefix search when `query` is passed, top-by-assets list when omitted. An agent immediately knows this is an FDIC institution lookup, distinct from the structure-events sibling it references.

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 explains the two usage modes (pass `query` for prefix search vs omit for the largest active institutions) and hints at the structure-event angle. It does not name an alternative sibling tool or state when-not-to-use, so it falls 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 behavioral burden and does so richly: DATA_UNAVAILABLE refusal on an unreachable store, partial-FY semantics, result ordering (newest FY first / largest first), the curated-crosswalk caveat, and that it is free/public-domain. This is substantially more than 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?

Dense and front-loaded, with the two-shape rule stated early and caveats clustered afterward. It is long, and some constraint detail duplicates the schema, but nearly every sentence carries operational value and nothing is buried.

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 explains both return shapes (per-FY obligations with dropped_unresolved, and the leaderboard), ordering, defaults, and failure modes, so 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 genuine meaning beyond the schema: mutual exclusivity of ticker/fiscal_year, sort ordering of the two result shapes, and the leaderboard scope ('not of all federal contractors'). These clarify usage beyond the 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+resource (federal-contract obligation history / fiscal-year leaderboard) and is explicitly different from any sibling by naming its two output shapes and its USAspending source. An agent can tell exactly what this returns versus get_fundamentals or ol_operating_kpis 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 explicit when-to-use for each mode: pass `ticker` for per-year history, `fiscal_year` for the leaderboard, and both is refused. It also warns not to compare a partial (period_complete false) year to a full one and clarifies obligations are not company-reported revenue.

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 discloses a wealth of behavior: metered daily AI quota (25/day, UTC reset, burst limiter), auth requirement and AUTH_REQUIRED failure mode, and a precise return shape. It even warns that `score` is a fused-rank value comparable only within one response, which prevents misuse.

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 key facts (paid, semantic retrieval, ticker-scoped), and each clause carries real information about quota, auth, and return format. It is dense with parentheticals and slightly long, but nearly every sentence earns its place.

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

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

With no output schema, the description fully specifies the response object ({summary, ticker, count, chunks, quota_remaining_today}) and per-chunk fields, plus auth and quota constraints. An agent has everything needed to call and interpret the result 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 every parameter (ticker, query, k) is already documented in the schema, including k's default and hard cap. The description mostly restates this, though it adds the fused-rank meaning of the returned score, which is output rather than parameter semantics. 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 ('semantic retrieval over EMBEDDED SEC filings for a ticker') and clarifies the input style with a concrete example natural-language question. It is clearly distinguishable from sibling search tools like search_company, search_news_archive, and ol_13f_filer_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?

Explains when to reach for it (a natural-language question over filing text) and gives strong operational context: it is 'the ONE metered tool', needs a signed-in account or API key, and anonymous calls fail AUTH_REQUIRED. It stops short of naming an explicit alternative or a 'when-not-to-use' case, so not quite 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 supply readOnlyHint=true, yet the description adds substantial behavior: the exact return shape {summary, count, days, industry, offerings}, the caveat that total_offering_amount is a ceiling rather than money raised, the quarterly posting lag, and limit default/cap. This is rich disclosure well 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 the core scope, then tight supporting notes on return shape, the ceiling caveat, the empty-window pitfall, and limits. Every sentence carries actionable information with no filler.

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

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

With no output schema, the description supplies the return keys and the key semantic traps (ceiling vs raised, empty window by construction), plus limits and data source. 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 description coverage is 100% and the schema itself already explains the days window construction, the limit default/cap, and the industry filter. The description reinforces the days caveat and limit cap but adds little semantic detail not already in the schema, 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 (recent SEC Form D private-placement filings), names the source data set, and specifies ordering (newest first) and optional scoping. It is clearly distinguishable from siblings like get_insider_activity or ol_13f_filer_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?

Gives strong operative context: optional industry/date-window scoping and a critical warning that a short `days` window is empty by construction, not evidence of no filings. It does not explicitly name an alternative sibling 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 supply readOnlyHint=true; the description carries the real behavioral load. It discloses result semantics (verdict: pass/fail/unknown, failed_criteria vs unevaluated_criteria), that unknown is not a fail, the overflow behaviour (extras named in `dropped`), and the data source — genuinely useful context 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?

Dense but front-loaded: the core operation and the 10-ticker cap come first, then criteria, then result semantics and caveats. Every clause carries information, though the single long sentence is heavy and could be broken for scanability.

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 explaining the result shape (verdict, failed_criteria, unevaluated_criteria) and the dropped-tickers overflow. For a read-only screening tool with full schema coverage, 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 description coverage is 100%, so each parameter's unit and meaning are already documented (USD, percent). The description's restatement of units ('whole USD; *_pct as percentage numbers') and the criteria list adds only marginal value beyond the schema, 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?

The description states a specific verb+resource with scope: a threshold screen over up to 10 caller-supplied tickers on latest-year SEC EDGAR XBRL fundamentals. It also pre-empts misidentification with siblings/neighbours by declaring 'Not a universe screen; a fundamentals filter, NOT a buy signal', so an agent can tell it apart from get_fundamentals or ol_peer_fundamentals 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?

Usage context is clear: it is a multi-ticker (2-10, hard cap) fundamental threshold filter with optional criteria, and explicitly not a universe screen or buy signal. However, no alternative tool is named for the single-ticker or peer-comparison case, so the when-to-use-vs-sibling 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?

readOnlyHint=true already tells the agent this is a safe read; the description adds real value beyond that by disclosing the corpus size (~1,500 terms), the in-house editorial provenance, that access is FREE, and the case/punctuation tolerance of the lookup. It doesn't describe pagination or fallback behavior when a term isn't found, which is the only remaining gap.

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

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

Front-loads the resource and its scope before the usage rationale, and every sentence carries information the agent can act on. It's slightly verbose in the marketing-flavored clause ('written for lifelong students of the market'), but nothing is 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?

With no output schema, the description carries the return-value burden and does so by enumerating the fields a lookup returns plus the educational metadata (see-also, learning paths). For a single-parameter read tool with annotations covering safety, nothing essential 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% for the single parameter, so the baseline is 3; the description goes beyond the schema by specifying normalization behavior ('case and punctuation tolerant') with concrete examples ('first lien', 'convexity', 'duration') that signal multi-word and no-punctuation inputs are valid.

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 (Oxford Ledge's editorial glossary of ~1,500 finance/investing terms) and enumerates exactly what a lookup yields: definition, worked example, etymology, pronunciation, related terms, and learning paths. No sibling tool touches editorial glossary content, so the tool is unambiguously distinguishable from the screener/data siblings.

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

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

Explicitly frames the use case ('ground explanations in the SAME definitions the platform teaches from, instead of improvising one'), which tells the agent both when to reach for it and what behavior it replaces. It stops short of naming a competing tool or an exclusion condition, but no sibling offers an alternative glossary, so the guidance is effectively complete.

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?

ReadOnlyHint is set, so the bar is lower, yet the description adds real behavioral context: the exact return shape, empty-result semantics (events=[] means absence is not a signal), refusal on an unreachable store, and the SEC EDGAR Form 4 source windowed on FILING date for look-ahead safety. This is substantive 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 the core purpose and then organized under clear 'THREE GRAINS' and return-shape structure. Dense but nearly every clause carries information; the all-caps emphasis is stylistic noise but does not waste 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?

With no output schema, the description compensates by giving the top-level return object and each event's fields, plus the module's edge-case behavior. 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%, so the schema already documents all five parameters; the description still adds grain-level meaning (which params pair with which grain, plus refusal caps per grain). It goes beyond the schema without fully restating per-parameter syntax, so slightly above the 3 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: 'scan for ACTIVE multi-insider cluster-buy/sell signals (distinct-actor Form 4 clusters with statistical strength)'. This cleanly distinguishes it from siblings like ol_insider_recent_buys and get_insider_activity by naming the distinct concept of a multi-actor cluster with statistical strength.

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 (watchlist via `tickers`, single name via `ticker`, or neither for market-wide) and the constraints that select them. It also states exclusions ('not accepted with `ticker`') and semantic caveats ('absence is not a signal'), leaving little 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?

Beyond the readOnlyHint annotation, it discloses return shape and ordering (NEWEST FIRST), a critical SAMPLING TRAP (limit returns newest N filings, not the whole window, so rows must not be totaled), which fields are derived (totalValue, fallback position label), the data source, and that it is FREE. 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?

A single dense paragraph that is front-loaded with purpose before the caveats. Nearly every clause earns its place (sampling trap, derived fields, source), though the density borders on cramped for one block of prose.

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

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

With no output schema, the description compensates by enumerating the return object ({summary, since_days, count, buys}) and per-row fields, plus ordering, caps, and the sampling caveat. 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 limit, min_value, since_days, and common_only semantics. The description restates defaults and hard caps (30/180, 25/100) rather than adding new parameter meaning, so baseline 3 applies; the sampling-trap note adds context around limit but is not parameter syntax.

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 OPEN-MARKET insider PURCHASES (SEC code P)' across ~5.3k tickers, framed as a daily insider screen. It distinguishes itself from siblings by naming ol_insider_cluster_scan and get_insider_activity, so an agent can route 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?

It names complementary siblings ('Pairs with ol_insider_cluster_scan and get_insider_activity') but never states the conditions under which to prefer this tool over them or get_insider_activity. The 'daily insider screen' framing implies usage, but there are no explicit when/when-not rules.

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 behavioral burden well: it discloses the return verdict taxonomy, the edge-case verdicts (insufficient_13f_coverage / insufficient_history, 'never coerced to neutral'), that the output is derived with no per-fund rows, and the data source (SEC EDGAR 13F-HR + Form 4). It also notes FREE access with no tier gate or AI metering, which is meaningful operational context.

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

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

Front-loads the purpose, then layers return shape, derivation semantics, sibling relationships, and access terms in dense, earning sentences. No repetition or filler, and the most important distinction (derived, not raw) appears early.

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

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

With no output schema, the description fully compensates by enumerating the return fields (verdict, institutional, insider, cluster, coverage, summary) and the verdict values. For a one-param read tool, an agent has everything needed to decide and invoke correctly.

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

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

There is a single required parameter (ticker) with 100% schema description coverage, so the schema already documents it. The phrase 'for one ticker' reaffirms the scope but adds no format or edge-case detail beyond the schema. Baseline 3 applies 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+scope: a quarter-aligned, derived institutional-confluence read for a single ticker fusing 13F accumulation, insider Form 4 net buying, and buy-cluster confirmation. It explicitly declares it is a DERIVED verdict rather than raw data ('no per-fund rows'), which cleanly separates it from siblings like get_institutional_holders and ol_insider_cluster_scan.

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 related tools it pairs with (get_institutional_holders, ol_insider_cluster_scan) and makes clear this is the fused/derived alternative to raw-data tools. However, it stops short of an explicit 'use this when... instead of...' rule; the selection logic is inferred from the derived-vs-raw distinction rather than 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?

With only readOnlyHint available, the description carries the burden and does so richly: full return shape, fixed assumption constants, null-on-negative/missing-input behavior with null_reasons, and transient 'fetch_error' retry guidance. This is far 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-loads the core purpose and packs return keys, assumptions, and caveats densely with little waste. Minor redundancy in restating 'USD PER SHARE' twice, but given no output schema the return enumeration earns its space.

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

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

No output schema exists, so the description must explain returns — and it enumerates the return object, clarifies units, assumptions, null semantics, and error retry behavior. An agent has everything needed to call and interpret this 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?

Single parameter with 100% schema description coverage, so the schema already documents ticker. The description adds no ticker-specific syntax or format detail, 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?

Names a specific resource (per-share intrinsic value) and its exact provenance and method (SEC EDGAR XBRL; levered-FCF DCF, Greenwald EPV, Graham number). This clearly separates it from generic siblings like get_fundamentals or ol_fundamentals_screen 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 states what the tool does NOT give you and what to do instead ('fetch a price yourself and compare'), plus a compatibility warning ('FCFE-style, not comparable to an enterprise-value DCF'). It gives clear usage context but does not name sibling tools or state when-not-to-call-it conditions.

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

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

With only readOnlyHint=true available, the description carries the rest and does so well: null + is_absence=true rows are legitimate answers, metric_availability explains why, values are confidence-gated, and needs_review rows are excluded. It also discloses extraction lineage (SEC exhibits, Oxford Ledge parse) and that reads are 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-loads scope, then the absence semantics, then filters and the sibling alternative. Dense but every clause earns its place; the all-caps emphasis is slightly noisy 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?

No output schema exists, yet the description explains what rows look like (value/is_absence/metric_availability), what is filtered out, and where data comes from. For a read-only panel tool this covers 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 the schema already documents ticker, limit, metric, period, and industry. The description names the same three optional filters and adds the useful constraint that there is no cross-issuer read, but supplies no extra syntax or format detail 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 resource and scope ('Tier-3 KPI PANEL for ONE issuer'), enumerates the metric dimensions (ARR, RPO/cRPO, NRR, etc.), and names the sibling it is NOT (ol_operating_kpis) plus the source. An agent can distinguish it from every sibling 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?

Explicitly says per-issuer by design and routes broad cross-industry KPI queries to ol_operating_kpis. The 'ABSENCE IS FIRST-CLASS' note tells the agent how to interpret null rows rather than retry or substitute. When-to-use and the alternative are both 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=true, so the description carries real weight here and delivers: it discloses the LATENCY profile (live SEC EDGAR fetch, seconds per issuer, minutes for a cold list), the coverage limitation (only companies with parsed schedules), and the explicit refusal to estimate unscheduled issuers. It also flags that by_rating uses a leverage heuristic rather than agency ratings, which prevents a serious misinterpretation.

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 resource and its outputs, then layers caveats (units, heuristic, coverage, latency) in order of importance. Despite the caps-heavy style and length, every sentence conveys a fact the agent needs and none 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?

There is no output schema, so the description must describe the return shape, which it does via the named output fields. Combined with units, coverage boundaries, the estimation policy, and latency, an agent has everything needed 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 description coverage is 100% and both parameters are already documented in the schema (max 50, omit for market-wide, by_sector default false). The description largely restates this rather than adding syntax or format detail, so the baseline of 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 resource (the corporate debt maturity wall) and enumerates exactly what it returns (total_by_year, by_rating, top_issuers_by_year, peak_year, concentration), so the agent knows precisely what it gets. It does not, however, differentiate itself from the sibling get_debt_maturities, which an agent could easily confuse it with given the near-identical subject matter.

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 states the two usage modes: market-wide when `tickers` is omitted, or scoped to up to 50 tickers. This gives the agent an actionable condition for how to call it. It stops short of naming when to prefer it over the sibling get_debt_maturities or when a different tool is more appropriate.

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?

Extremely thorough beyond the lone readOnlyHint: it discloses the anonymous 3-row truncation and `partial`/`total_metrics` signalling, that values are AS-REPORTED and confidence-gated, and the ambiguous meaning of available=false (uncovered industry vs. empty issuer vs. outage) with a no-retry directive. Source (SEC 10-K/10-Q/8-K exhibits) and FREE status are also stated.

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 (operating KPIs for one issuer) before the qualification chain about deployment flags and coverage. It is dense and partly run-on with heavy parentheticals, but nearly 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 carries the return-shape burden and does so by enumerating the panel fields (ticker, industry, metrics, available, partial, total_metrics, period, as_of, provenance, caveat). Coverage caveats, gating, and source are all present, so an agent has what it needs to call and interpret results.

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

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

With one parameter and 100% schema description coverage, the schema already documents `ticker` as a mandatory single issuer symbol including the no-cross-issuer-screen note. The description largely repeats this ('ONE issuer', 'Per-issuer by design') rather than adding new syntax or format guidance.

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

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

States a specific verb+resource with concrete examples (same-store sales, RevPAR, load factor, medical-loss ratio) and scopes it to ONE issuer extracted from SEC filings. However, it never acknowledges the very similar sibling `ol_issuer_kpi_panel`, leaving the agent to guess which panel tool to call.

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 operating context: anonymous vs keyed callers, the 3-row anonymous cap, and a clear 'do not retry with variations' instruction for available=false. It also states the tool is per-issuer by design, ruling out cross-issuer screens, but names no alternative sibling to use instead.

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

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

Goes well beyond the readOnlyHint annotation: explains that counts is always the complete tally while limit bounds each row list, that split-like deltas are withheld into split_suspect with as-filed counts, that share classes are never summed/netted, and that CUSIP-resolution makes figures approximations. It also names the source (SEC EDGAR 13F-HR) and cost profile.

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

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

Front-loaded with purpose, then return shape, then behavioral caveats and source. Dense but every clause carries information. Slightly packed with parentheticals, but no wasted 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, so the description carries the return-burden and does so: it enumerates the response fields and explains the tricky ones (counts, split_suspect). Edge cases, data provenance, and limitations are all 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 the baseline is 3, but the description adds real meaning: it clarifies that limit bounds EACH row list while counts remain the complete tally, which is the key semantic distinction an agent needs. It adds a bit beyond the schema's own description of limit.

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-over-quarter institutional accumulation/distribution for one ticker,' with the classification scheme (new/increased/decreased/exited) spelled out. It explicitly distinguishes itself from the sibling get_institutional_holders by calling that tool a 'snapshot' and positioning this as the flow read.

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 as the 'who is moving on X?' flow read and names the complementary tool (get_institutional_holders) and its distinction (snapshot). It does not give explicit when-not-to-use guidance, but the context and alternative are clearly 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?

Goes well beyond the readOnlyHint annotation: delayed quote marking at read time, never cached, empty-portfolio returns {has_portfolio: false, how_to_start} rather than an error, auth failure semantics (AUTH_REQUIRED), and a per-response _meta.disclaimer. These are exactly the operational traits an agent could not infer from annotations alone.

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 layered constraints; every sentence carries new information. It is dense with parentheticals and semicolons, which slightly reduces readability, but there is no filler.

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

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

With no output schema, the description compensates by enumerating the returned fields (portfolio, positions, totals, position_theses, summary, has_portfolio, optional recent_trades) plus the empty-state and disclaimer behavior. 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 description coverage is 100%, and the description largely restates the same facts (history_limit 1..50 default 20; include_history adds recent_trades). It adds marginally by tying recent_trades to the include_history flag, but the schema already carries the numeric bounds and defaults, 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 precise resource and scope: the caller's own paper/practice portfolio on Oxford Ledge, matching the /practice/ web sandbox snapshot. It names the exact response shape and clearly separates this from the real-portfolio sibling get_portfolio_positions by emphasizing 'paper' and 'YOUR ... only'.

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: authenticated Oxford Ledge caller (API key or linked OAuth), caller's own portfolio only, local stdio server gets AUTH_REQUIRED, and include_history opts into fills. However, it never names an alternative tool (e.g. ol_paper_trade or get_portfolio_positions) or an explicit when-not-to-use condition, so routing guidance is strong but not complete.

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 single readOnlyHint=false annotation: dry-run default, idempotency/replay semantics ({replay: true}), the fact that a rejection is a normal non-error response that must be read and relayed, credential requirements, the 20-fills-per-UTC-day cap, and the practice-money disclaimer in _meta. This is exactly the behavioral context an agent needs before a mutation.

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 single paragraph, but front-loaded with the most decision-relevant facts (WRITE opt-in, dry-run default, sibling mutating tool). Some clauses repeat schema-level constraints (shares 1..1,000,000, thesis 250 chars), which slightly dilutes the signal without making it hard to parse.

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 sketching the return shapes for both dry-run and replay responses, plus error semantics, auth, and rate limits. For a 6-parameter mutating tool with only one annotation, nothing an agent needs to invoke it safely 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 baseline is 3; the description still adds meaning by tying _dry_run and _idempotency_key together as a two-step execute protocol and framing thesis as the USER's own reason rather than the agent's. It largely restates the shares/side bounds already in the schema, so it does not fully escape redundancy.

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: 'place a market order in YOUR paper (practice) portfolio', and immediately contrasts the paper engine with real money/accounts. It also positions itself among siblings by naming the only other mutating tool (reading_list_annotate), so an agent can distinguish it from the many read-only ol_* 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 operational context: dry-run is the default, execution requires re-calling with _dry_run: false plus the same _idempotency_key, and auth must be an API key or OAuth token (cookies refused). It does not state explicit exclusions (e.g., when to prefer ol_paper_portfolio instead), but the workflow conditions are unambiguous.

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

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

With only readOnlyHint available, the description carries the burden well: it discloses the limit default/hard cap effect, that `count` is returned-not-total, the continuation-vs-grant trap, ingest freshness, and that an unreachable store yields DATA_UNAVAILABLE rather than a misleading zero. It also documents source and attribution scope.

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 what is returned before the trap, freshness, and attribution notes; every sentence adds distinct operational value with no filler or repetition.

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

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

No output schema exists, so the description has to describe the return shape — and it does ({summary, ticker, count, filings}, newest first). Combined with the trap, freshness, and refusal semantics, 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% and the schema already documents both parameters including the default 50 / cap 200, which the description largely restates. The added meaning ('count is the number RETURNED') is marginal, so baseline 3 is correct.

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 ('Recent USPTO patent filings for a ticker') plus the analyst use case ('innovation-intensity diligence'). No sibling in the list covers patent filings, so the resource alone differentiates it clearly.

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 ('recent slice, never a full portfolio') which implicitly tells the agent when-not to rely on it, and labels the diligence scenario it serves. It does not name an alternative tool for full-history patent research, so it stops short of 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?

With only readOnlyHint available, the description carries the burden well: it discloses truncation behavior (first 6 unique tickers, rest named in `dropped`), the missing-coverage case ({ticker, available:false}, never dropped), the absence of a price leg (no P/E or EV), the data source, and the cost profile (one cold EDGAR fetch per ticker). These are exactly the behavioral traits annotations cannot 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 compare scope leads, then the return shape, then constraints and caveats. Every sentence carries information, though the field list and unit notes make it longer 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?

No output schema exists, so the description must explain return values -- and it does, enumerating the response envelope and per-peer field names plus units (whole USD vs *_pct) and edge cases. Nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema coverage is 100% and the single parameter is documented, so baseline is 3. The description adds meaning beyond the schema by explaining what happens past the hard cap (first 6 kept, remainder reported in `dropped`), which the schema's 'hard-capped at 6' note only hints at.

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 (side-by-side compare) and resource (latest-fiscal-year fundamentals) for a peer set, and explicitly names the sibling get_fundamentals as the alternative for history. An agent can distinguish this from ol_fundamentals_screen and get_fundamentals 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?

Explicitly says 'ONE YEAR ONLY -- no history (use get_fundamentals)', which gives a clear when-not plus the alternative. It doesn't address when to prefer this over ol_fundamentals_screen, 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 only readOnlyHint in annotations, the description carries the burden well: it discloses oldest-first ordering, the reporting lag, that as_of is the settlement date rather than today, honest-empty behavior for unpublished tickers, and an explicit DATA_UNAVAILABLE refusal for an unreachable store. It also rules out share counts and days-to-cover, pre-empting wrong assumptions.

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, then return shape, then constraints and caveats. Dense but every clause carries information an agent needs; 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, so the description supplies the return shape ({summary, ticker, count, as_of, trend} and the exact per-point keys) plus edge-case behavior. Nothing needed to invoke 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% and already documents points' default and max, so the baseline is 3. The description adds real meaning beyond the schema: 'about one year' for the 26-point cap and that ticker resolves to the FINRA settlement-date series, which clarifies the parameter's semantics.

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

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

States a specific verb+resource+scope: 'FINRA short-interest trend for one ticker', and pins the exact series (biweekly settlement-date short-percent, oldest-first). It is clearly distinguishable from siblings like get_fails_to_deliver or get_institutional_holders.

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 useful framing that this is a fortnightly snapshot with a reporting lag rather than a live short-float figure, which shapes when it is appropriate. However, it never names an alternative tool or states an explicit when-not condition, leaving the routing decision 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 supply readOnlyHint, so the description carries the behavioral load and does so richly: units (AMOUNTS ARE IN MILLIONS OF USD with a worked example), a data hazard (component AND Total rows double-count when summed), the rate/cap profile (limit default 120, hard cap 360, series only), and failure behavior (unreachable store refused as DATA_UNAVAILABLE). This is precisely the context annotations cannot 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 mode selection are front-loaded, and nearly every clause carries operational weight. The dense ALL-CAPS emphasis and the $28 trillion example make it feel packed, but the information density is justified rather than 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?

With no output schema, the description still discloses the return shape ({summary, rows}), the unit convention, and the summing pitfall. Combined with the mode rules and error code, 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 baseline is 3, but the description adds genuine meaning beyond the schema: the two-vs-zero argument modes, the refusal of a lone argument, and the series-only scope of limit. That is more than restating the field docs, though some overlap with the schema's 'Sent only together with...' text remains.

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: 'US Treasury debt composition from the Monthly Statement of the Public Debt.' It explicitly names a sibling ('Sibling of get_yield_curve') and its source, so an agent can distinguish it from the other Treasury-adjacent 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 explicit conditional routing: 'Omit BOTH args for the newest month's full class breakdown; pass security_type AND security_class together for that one class's monthly history (only one of them is refused).' Both the when and the when-not (partial pairing refused) are stated, 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?

Annotations only supply readOnlyHint=false, so the description carries the burden and delivers: dry-run-by-default semantics, exact proposal/replay return shapes, idempotency behavior, Researcher tier plus authenticated-caller requirement with AUTH_REQUIRED on local stdio, privacy guarantee, and API-key dependency. This is unusually rich disclosure for a write 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 critical fact ('WRITE (opt-in)') and every sentence carries operational information, but the paragraph is dense and the dry-run/idempotency mechanics are packed into long clauses. Slightly more than strictly needed, though 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?

For a write tool with no output schema, the description supplies the return shapes (proposal and replay objects), auth and tier prerequisites, failure mode (AUTH_REQUIRED), privacy constraints, and the full execute flow. An agent has everything required 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 baseline is 3; the description adds genuinely new meaning by requiring that `slug` already exist on /reading-list, and reinforces the 500-char `body` cap and its privacy. It does not, however, clarify how an auto-derived `_idempotency_key` is produced beyond 'auto-derived if omitted'.

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 ('save or update YOUR private note on an Oxford Ledge reading-list entry') and immediately scopes it against siblings by naming the only other mutating tool (ol_paper_trade). An agent can identify the operation 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 context (save/update a private note) and when-not (notes can never be published here; publishing requires the dashboard flow). It also spells out the operational sequence: call once to get a dry-run proposal, then re-call with _dry_run: false plus the same idempotency key to execute.

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 covering safety, the description still adds substantial behavior: the ~45-60 day data lag, that `description` is a compiled profile not filing text, the above-par trap (a mark above 100 is not a credit premium until fairValue is checked against cost), and that aggregates cover only CURRENT holders while `holders` is per-tranche.

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 dataset, then return shape, then traps and constraints. It is dense and slightly crammed with capitalized flags, but nearly every clause carries actionable 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 enumerating the returned fields (borrowerName, borrowerNorm, description, descriptionSource, industry, the four aggregates, holders) and explaining the tranche-row semantics. 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%, so the baseline is 3; the description earns extra by clarifying that query needs 3+ characters and that limit/offset page only the `holders` tranche rows, not the aggregates -- a scoping nuance the schema alone does not stress.

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: which BDCs lend to a single private-credit borrower, fuzzy name match. It also pins the underlying dataset (Oxford Ledge parse of SEC EDGAR BDC schedules, not filer-published data), which distinguishes it from generic company-search siblings.

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

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

Gives one important usage caveat -- a miss means {found: false} and is not evidence of no BDC exposure -- but never names alternatives or when to prefer them (e.g., ol_borrower_profile, ol_bdc_common_borrowers, get_bdc_list). Usage is implied by the phrasing rather than 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?

With only readOnlyHint=true in annotations, the description carries real behavioral detail: hard cap of 20 matches, return shape {results, count}, null fields are OMITTED so cik cannot be assumed present, matching is literal substring, and tickerStatus must be checked before treating a match as live. That is exactly the 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 action, then the return shape, then the caveats; every clause is operational (cap, omitted nulls, substring matching, downstream calls). It is dense and slightly packed, but nothing reads as 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 return shape, the field set, the hard cap, and the null-omission rule, plus the resolution caveats and next-step tools. An agent has everything needed to call it and interpret results 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 adds matching semantics the schema omits: literal substring on ticker/companyName, class-share punctuation handling, and a digit-only CIK path. It notably does not echo the schema's 'industry' mention, adding useful precision about what actually matches.

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 company name, ticker or CIK to its SEC identity.' It positions itself as the identity-resolution entry point among many sibling search/get tools and names the downstream siblings (get_fundamentals, get_business_summary), so an agent can distinguish it from get_* data tools 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?

Clear routing: 'Once resolved, call get_fundamentals or get_business_summary' tells the agent this is a precursor step. It also warns former names/misspellings do NOT resolve. There is no explicit when-not or statement of which query form to prefer, 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 rest and does so richly: the return shape ({query, count, results, index} with per-result fields and score range), the limit default/cap, first-call latency from index build, and the RESTRICTED keyed-auth posture. This is context well beyond what the single 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 return shape, limits, latency, auth, and alternatives in dense sequential sentences. Nearly every clause earns its place; only the limit restatement is 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?

With no output schema, the description usefully specifies the return structure and per-result fields. Combined with latency, auth, and sibling routing, nothing an agent needs to invoke this tool 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 schema already documents both parameters. The description restates the limit default (20) and hard cap (50), which the schema already declares, and adds no new syntactic or format detail for query. 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 ('TF-IDF full-text search over the archived news headlines + the pulse-fact corpus') and explicitly distinguishes the index type ('lexical index, not embeddings'). It names the sibling tools it must not be confused with (get_news, ol_filing_search), so an agent can route correctly 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 alternatives with selection conditions: 'For per-ticker archive reads use get_news; for semantic retrieval over SEC filings use ol_filing_search.' It also states the entry prerequisite (needs an Oxford Ledge API key configured by the operator) and that anonymous callers are refused.

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