Oxford Ledge

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

With only readOnlyHint in annotations, the description carries real weight: it discloses that cusip is stripped on every channel, that there is no ticker field, that position_type must not be summed across, the SEC EDGAR source with ~45-day delay, and a concurrency limit of max 2 concurrent. This is exactly the behavioral context annotations cannot provide.

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

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

Purpose is front-loaded in the first sentence and the dense remainder is largely load-bearing (input resolution, return shape, caveats). It is a single run-on paragraph that could be broken into sections, but little is wasted.

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

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

There is no output schema, so the description must document returns, and it does thoroughly ({cik, fundName, filingDate, periodOfReport, totalHoldings, totalValue, holdings} plus row fields). For a read-only tool with rich annotations, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents the CIK/ticker/name resolution rules and the max_holdings default, so the description largely restates them. It reinforces the tricky resolution behavior and adds the 'resolved_from' cue, but adds little beyond the structured field.

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

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

States a specific verb and resource ('What one institutional filer owns: the largest positions in its latest SEC 13F-HR, plus quarter-over-quarter changes'), which an agent can distinguish from siblings like ol_13f_filer_search or get_institutional_holders without opening a schema.

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

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

Gives clear context on when the tool applies and routes the agent elsewhere for name resolution ('the error names ol_13f_filer_search'), and states the CIK is preferred over ticker/name. It stops short of an explicit when-not comparison against the several overlapping institutional-ownership siblings.

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

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

With only readOnlyHint=true in annotations, the description carries the rest and delivers: keyless callers get STORED rows and never trigger an EDGAR refresh, with stale/stale_basis to inspect; caveats ride in the response's tool_notes; is_activist is disclosed as a form-type label rather than a judgement. This is unusually rich 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?

Dense but front-loaded: purpose first, then return shape, then the substantive semantics (is_activist, reports_zero), then the FRESHNESS caveat in a clear label. No filler sentences; each clause adds operational information.

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

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

No output schema exists, so the description supplies the return contract ({ticker, count, filings} newest first, plus row fields filer_name, filing_date, form_type, shares, percent_of_class, accession_number, is_activist), the limit behavior, and the freshness/notes caveats. 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 schema already documents both params (ticker, limit default 50/max 200), so the description's restatement of default 50 and hard cap 200 is mostly redundant. It adds 'newest first' ordering, which is useful but is about the result set rather than the parameters.

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

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

States a precise verb and resource — 13D/13G >5% beneficial-owner filings for a ticker — and explicitly contrasts it with quarterly 13F and with siblings get_institutional_consensus/get_institutional_holders. An agent can distinguish it from get_13f_holdings and get_institutional_holders 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 context (event-driven stake-building vs quarterly 13F), names the complementary tool (get_institutional_consensus), and states a conditional check (cross-check get_institutional_holders before reading reports_zero as a sale). Alternatives and conditions are spelled out 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?

With annotations only covering readOnlyHint, the description carries the rest and does so richly: exact return shape, severity enum semantics ('red' or 'amber', red first), the meaning of available:false, the non-obvious fact that empty flags is not an all-clear, caveat placement in tool_notes, and the API-key/auth requirement. This is far beyond what the annotation provides.

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

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

Front-loaded with the core action, then tight clauses for return shape, severity, semantics, and auth. It is dense but nearly every clause earns its place; the long screen enumeration is the main weight, though it does clarify scope.

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 completely (flags, count, severity, available/reason). Combined with auth requirements, caveat routing, and interpretation caveats, 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% for the single ticker parameter, so the schema already documents its format (e.g. AAPL). The description adds no syntax or format detail beyond the schema, making the baseline 3 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 ('Run 15 red-flag screens on a ticker') and enumerates the actual screens, so the agent knows exactly what analysis is produced. It is clearly distinguishable from value/quality siblings like get_fundamentals and ol_intrinsic_value, which it explicitly names as pairings.

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 ('Pair with get_fundamentals and ol_intrinsic_value') and important interpretive guidance ('A flag is a question to investigate, NOT a sell signal'). It stops short of explicit when-not-to-use or exclusion conditions versus alternatives, so it lands just below the top.

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; the description goes well beyond, disclosing provenance ('Oxford Ledge's parse, not filer-published figures'), a reconciliation block, a critical usage warning ('READ fairValueBasis BEFORE using totalFairValue'), the under-counting behavior of parsedRowSumFairValue ('UNDERSTATES the book'), the pseudo-ticker convention, and that caveats ride in tool_notes. This is unusually rich behavioral context for a read-only tool.

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

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

Front-loaded with scope and exclusions, then the no-arg fact, then the return shape, then the usage warning, then the sibling pointer. Dense but every clause carries signal. The per-field enumeration of the reconciliation block is long but justified because no output schema exists to carry 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?

For a no-arg read tool with no output schema, the description does the schema's job: it enumerates the return shape ({bdcs, count}, per-BDC fields, reconciliation block) and tells the agent how to interpret the fields, including the fairValueBasis > totalFairValue precedence and the under-counting risk. Nothing material is missing.

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

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

Zero parameters, so baseline is 4. Description confirms 'No arguments' and spends its parameter budget on clarifying the return payload instead, which is the correct behavior for a no-arg 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 ('roster of ACTIVE BDCs tracked by Oxford Ledge') and immediately distinguishes scope from alternatives ('our coverage, not the whole BDC universe; wound-down issuers are excluded by design'). Names the sibling counterpart 'search_bdc_borrower' explicitly, so an agent can route without ambiguity.

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 when to use this tool (roster of covered BDCs) versus the borrower-keyed alternative ('Borrower-keyed counterpart: search_bdc_borrower'). Also flags exclusions ('wound-down issuers are excluded by design') and the no-argument invocation, so the agent knows the preconditions and limits.

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

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

Goes well beyond readOnlyHint=true: no network call, sub-millisecond fixed envelope, every price field null, a status/unavailable/note/use_instead block, and an error channel that distinguishes malformed input ('CUSIP must be at least 6 characters') from an outage. It also discloses the API-key auth requirement and that anonymous callers are refused.

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 'RETIRED (2026-09-13)' and front-loads the replacement tool. It is dense and long, and the 22-key envelope enumeration is borderline padding, but each clause carries retirement, licensing, return-shape, or error 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 full burden and does so: it enumerates the returned envelope, explains the status fields, the error semantics, and the auth requirement. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single cusip parameter is already documented as a 9-character CUSIP. The description adds only the malformed-input error threshold (6 characters), which is a behavioral detail rather than added parameter semantics, so baseline 3 is appropriate.

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

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

The description states precisely what the tool is (retired FINRA TRACE single-bond lookup by CUSIP), what it now does (fixed-key envelope, no network call), and how it differs from siblings by naming ol_bond_directory_screen and get_debt_maturities. An agent can tell instantly it is a retired stub, not a live price source.

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

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

Explicit routing: 'Use ol_bond_directory_screen ... or get_debt_maturities for one issuer's own maturity schedule.' It also states why this tool cannot be used (TRACE host auth-walled, no redistribution licence), leaving no ambiguity about when to call it.

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

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

Annotations only carry readOnlyHint, so the description does the heavy lifting and delivers: response field names, that `summary` is a status line and not content, ~2400-char truncation, that available=false means provenance keys are absent, that an unreachable store is refused with DATA_UNAVAILABLE, and a known provenance quirk for rows pre-dating 2026-09-13. That is exactly the kind of beyond-annotations behavioral detail this dimension rewards.

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 source before the return-shape and caveat detail, and every clause carries information. It is a dense single block rather than cleanly segmented, which costs it a point but nothing is wasted.

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

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

There is no output schema, so the description must describe the return payload itself, and it does so thoroughly (summary, available, business_summary, short_summary, provenance keys, truncation limit, and the failure modes). Nothing needed to call or interpret the result is missing.

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

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

Schema description coverage is 100% and there is only one parameter (ticker), which the schema already documents with an example. The description adds no syntax, format, or edge-case meaning for the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('first-party business summary for a ticker from its SEC annual report') and pins down the exact source (10-K Item 1 / 20-F Item 4). It explicitly distinguishes itself from the nearest sibling by naming ol_filing_search as the tool for full-corpus passage retrieval.

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 a clear routing rule: use this for the curated overview, use ol_filing_search for semantic passage retrieval over the full filing corpus. It does not spell out explicit when-not conditions beyond that one alternative, so it falls short of a full 5.

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

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

Annotations only carry readOnlyHint=true, and the description goes well beyond that: it warns that netBuybacks is a derived dilution proxy rather than a buyback figure, that split-basis share counts are withheld rather than shown as phantom buybacks, and that IFRS reporters are refused rather than served zeros. It also discloses the SEC EDGAR XBRL source, a 24h cache, and that caveats ride in tool_notes.

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

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

Front-loaded with the core purpose and return shape, and every sentence carries distinct information (field list, derived-metric caveat, split handling, refusal behavior, source, tier). It is dense and the inline object listing is heavy, but with no output schema that detail 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 carries the return contract itself, enumerating every field as parallel arrays aligned to `years` and explaining the tricky derived metrics. Combined with source, cache, tier, 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 description coverage is 100% for the single ticker parameter, so the schema already documents it fully. The description adds no ticker-specific meaning (format, case, exchange prefixes), so the baseline of 3 applies.

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

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

States a specific purpose ('Where a company sent its cash, up to 30 annual labels') and enumerates the exact returned fields, so the resource is unambiguous. Naming get_fundamentals and get_debt_maturities as complements helps an agent separate this tool's capital-allocation niche from adjacent fundamentals tools.

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

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

The description says it 'complements get_fundamentals and get_debt_maturities' and notes a Researcher tier requirement, which implies context but never states explicitly when to choose this over those siblings or when not to call it. No alternative-selection rule is given.

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: a hard 20-event cap with no caller-settable limit, newest-first ordering, dual-class union, ~7-day re-index cadence, refusal semantics (DATA_UNAVAILABLE rather than empty events), and the fact that caveats arrive via tool_notes. This is unusually rich behavioral disclosure.

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

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

Front-loaded with the scope and cap before secondary details; every clause carries information (cap, ordering, return shape, filter vocabulary, failure mode, source freshness). Dense and slightly over-packed, but 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?

No output schema exists, yet the description enumerates the response envelope and per-event fields, plus freshness, failure mode, and caveat location. 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 the schema already spells out the 17 stored categories and the 'anything else returns events=[]' behavior. The description's restatement of 'STORED CATEGORIES ONLY' adds emphasis and cross-references acquisition_disposition, but no new syntax or format detail. 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, and scope: the 20 most recent 8-K item events for a ticker, newest first, from a named source. It explicitly distinguishes itself from get_insider_activity and from M&A lookups via acquisition_disposition.

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 ('a recent-events feed, not a history') and when-not ('for Form 4 insider transactions use get_insider_activity'; 'for M&A use acquisition_disposition'). Names the alternative tools by name.

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

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

Annotations only declare readOnlyHint=true, so the description carries the real behavioral load: amounts are in millions not raw dollars, the ladder is as-of filing date rather than today, current-year buckets may already be repaid/refinanced, empty answers include refusal fields, and caveats ride in tool_notes. It also discloses the Researcher tier requirement and SEC EDGAR source, adding substantial 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?

The description is dense but front-loaded: it opens with the core purpose, then gives return shape, units, temporal caveat, validation check, refusal behavior, and the alternative tool. Every sentence adds 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?

There is no output schema, so the description fully documents the return structure, units, confidence and validation fields, refusal behavior, and caveats. Given the single required parameter and no nested objects, this is complete for an agent to call and interpret the tool correctly.

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

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

Schema description coverage is 100% and the single ticker parameter is already documented with an example in the schema. The description does not add parameter-specific syntax or format details beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb+resource: a forward debt maturity ladder parsed from the latest 10-K/20-F footnote. It clearly distinguishes from the sibling get_capital_allocation by assigning historical issuance/repayment there, 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?

It explicitly names the alternative for historical data ('For historical issuance/repayment use get_capital_allocation') and tells the agent to check `validation` before quoting a total. These are concrete when-to-use and when-to-avoid signals, not implied guidance.

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

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

Far exceeds what readOnlyHint alone conveys: 6h caching, the critical instruction to always check source_status because all failure modes return events=[], the auth requirement (Oxford Ledge API key, anonymous refused), where caveats live (tool_notes), and the refusal threshold above 180 days. This is exactly the behavioral context an agent needs before calling.

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

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

Dense but front-loaded: what it is, what it returns, what it excludes, then operational constraints. Every sentence carries information, though the parentheticals and emphatic caps make it slightly crowded.

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

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

With no output schema, the description correctly compensates by describing the return shape {days, events, count, source_status, error} and the per-event fields. Auth, caching, and failure semantics are all covered, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema lacks: the default of 90 and, importantly, that values above 180 are REFUSED rather than silently clamped. That is behavior beyond the maximum constraint.

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

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

Names a specific verb+resource (US macro data-release dates) and immediately scopes it: a schedule, not estimates, for exactly 9 named releases. It also explicitly excludes FOMC dates and prior/consensus/actual values, which distinguishes it from siblings like get_fred_data 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?

It implies usage through constraints (look-ahead window, cache, source_status check) and names what it is NOT for, but never states when to choose this over get_fred_data or ol_earnings_calendar. The exclusions function as partial guidance 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 readOnlyHint already covering safety, the description adds substantial behavioral context beyond annotations: empty/thin history reflects loaded files not absence of fails, prices are NOT split-adjusted, an unreachable store REFUSES with DATA_UNAVAILABLE, and the source is published twice monthly with ~3-week lag. Caveats in tool_notes are also disclosed.

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

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

Dense but front-loaded: purpose, return shape, then caveats in descending priority. Nearly every sentence carries load, though the return-field enumeration is slightly heavy given no output schema exists to absorb 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?

No output schema exists, yet the description fully specifies the response shape ({ticker, days, history, count, window, coverage, as_of, summary} and row fields), units (SHARES not dollars), ordering (oldest-first), and failure mode. 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% (baseline 3), but the description adds real meaning: `days` is anchored to the latest LOADED settlement date, not today, and `end_date` re-anchors the window. It clarifies the semantics of the default in a way the schema only partially 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 and resource ('SEC fails-to-deliver history for one ticker') and frames its analytical role ('the settlement-failure side of short pressure'). It also names the complementary sibling, ol_short_interest_trend, making it distinguishable from the many other data-fetch 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 context for interpretation ('read coverage and summary before reading a gap') and explicitly pairs with ol_short_interest_trend. It doesn't spell out when-not-to-use or prerequisites relative to all alternatives, 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?

Annotations only declare readOnlyHint=true. The description goes far beyond by disclosing the exact response shape, the latest-only observation constraint, refusal behavior for third-party licensed series (with a list of affected IDs and reason codes), the RESTRICTED/keyed posture, the need for an operator-configured API key, and that caveats appear in tool_notes. This is rich behavioral context that annotations do not cover.

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 return shape effectively, but the middle section is dense with error/refusal detail, a long enumerated ID list, and parenthetical date notes that reduce scannability. The information is valuable but could be structured more cleanly.

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, keyed, read-only tool with no output schema, the description covers the return format, the latest-only constraint, refusal cases with reason fields, auth requirements, and where caveats live. An agent has everything needed to call it correctly and interpret responses.

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 example (GDP, UNRATE) plus the description's enumeration of specific FRED IDs (BAMLH0A0HYM2, VIXCLS, etc.) illustrate valid and invalid inputs. Baseline 3 is appropriate since the schema already documents the single parameter fully.

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

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

States a specific verb+resource (retrieve one FRED series from Oxford Ledge's macro snapshot), keyed by FRED id, and explicitly scopes that only the newest observation is returned, not history. This distinguishes it clearly from siblings like get_yield_curve or get_economic_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?

The description implies usage by specifying 'newest observation each' and 'one series from the snapshot,' which implies when this tool is appropriate (single-series latest value) versus a history tool. However, it never explicitly names alternatives or states when NOT to use this tool, leaving the agent to infer limits.

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

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

Annotations only declare readOnlyHint=true, so the description carries the behavioral load and does: it discloses the source (SEC EDGAR company-facts XBRL), the ~45-day post-quarter lag, a 24h cache, and how IFRS reporters or untagged filers fail ({error, taxonomy, formsSeen, unitsSeen}). It also covers edge semantics (missing year = null never 0, pre-split per-share cells withheld) that no annotation conveys.

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

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

Dense but front-loaded, leading with the one-line purpose before the return-shape detail and sibling routing. Every clause carries information (alignment-by-index, unit conventions, basis caveat); it is long because it is substituting for an absent output schema, not padding.

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

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

With no output schema, the description fully specifies the returned object shape and its invariants (parallel arrays aligned to `years`, newest-first, null-vs-0, withheld per-share cells, error shape). Nothing an agent needs to correctly call and interpret this tool is missing.

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

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

Only one input parameter (ticker) with 100% schema description coverage, so the schema already documents it fully. The description adds no ticker-format or resolution nuance beyond the schema example. Baseline 3 per the high-coverage rule.

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

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

States a specific verb and resource ("Full XBRL financial history for one ticker") and immediately distinguishes itself from siblings by naming get_capital_allocation, ol_intrinsic_value, and ol_operating_kpis for adjacent tasks. An agent can tell 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?

Explicitly routes three related questions to alternatives: cash deployment to get_capital_allocation, per-share fair value to ol_intrinsic_value, industry operating metrics to ol_operating_kpis. This is concrete when-to-use-this-vs-that guidance rather than implied context.

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

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

Annotations provide only readOnlyHint=true, so the description carries the rest and delivers: hard row cap (20 most recent), dedup behavior for 4/A repeats, the instruction to exclude issuerSelfFiled rows from totals, a warning to check isDerivative before reading shares as common stock, provenance of totalValue, SEC EDGAR source and ~2-day filing deadline, and a pointer to in-response tool_notes caveats. This is far beyond what the annotation conveys.

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

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

Front-loaded with the outcome, then routing, then field semantics; every clause is load-bearing, including the field list that substitutes for a missing output schema. Still dense and caps-heavy, and the field enumeration could be tightened, so it stops short of ideal economy.

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 define the return contract, and it does field by field (insiderName, position, transType with SEC code decoding, shares, pricePerShare, totalValue, isDerivative, url) plus dedup and exclusion rules. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds decisive semantics the schema does not: `days` is a documented NO-OP on this path (the schema implies a working default-365 window, which would mislead), and ticker is implicitly single-issuer. That correction is critical for correct invocation.

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

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

Specific verb+resource+scope: 'Recent Form 4 insider transactions for one ticker', with the exact return shape named ({ticker, transactions}). It explicitly distinguishes itself from the three nearest siblings (ol_insider_recent_buys, ol_insider_cluster_scan, get_activist_stakes), so an agent can route 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 three alternatives with the condition that selects each ('Market-wide buys: ...; clusters: ...; >5% stakes: ...'), states the access prerequisite ('Requires Researcher tier'), and scopes the tool to a single ticker. The only missing piece is an explicit negative case, but the sibling routing is unusually 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?

Annotations only declare readOnlyHint, so the description carries the behavioral load and does it well: common-stock-only tally (not exposure), each fund contributing its own latest quarter which may differ across funds, SEC EDGAR 13F-HR source with ~45-day delay, and caveats living in the response's tool_notes.

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

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

Front-loaded with the core question, then return shape, then scoping, then sibling routing. Dense but nearly every clause earns its place; the return-shape notation is compact rather than verbose.

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 response shape, row fields, ranking order, truncation semantics, source, and latency. 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 baseline is 3, but the description adds real semantics: top_n truncates only `consensus` while `tickers_found` is the FULL count meeting min_funds, clarifying that the two params affect different parts of the result. It restates the defaults/caps already in the schema, so not a full 5.

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

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

States a precise verb+resource: which tickers tracked 13F filers most widely hold in common. It explicitly differentiates itself from the sibling get_13f_holdings by contrasting the two questions each answers.

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: 'Answers who is buying X?; get_13f_holdings answers what does fund X own?' Plus it scopes the data to common stock only and notes the quarterly-delay source.

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 burden and delivers: it discloses the 100-row display cap vs the true total_holders count, common-stock-only scope, off-cadence quarter divergence, CUSIP-resolution failure risk, ~45-day SEC 13F-HR lag, and that caveats ride tool_notes. This is unusually rich 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?

Dense but front-loaded: purpose first, then return shape, caps, caveats, and routing in labeled fragments. Nearly every clause earns its place given the absence of an output schema, though the packed run-on style is slightly heavy.

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

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

No output schema exists, yet the description enumerates the returned fields, flags the aggregate-quoting pitfall, and points to tool_notes for caveats. 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% for the single 'ticker' parameter, so the schema already documents it 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 ('which institutions hold one ticker, and which way they moved') and immediately names the two sibling alternatives it is not (ol_ownership_changes, get_13f_holdings). An agent can differentiate it from the other ownership tools without opening any schema.

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

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

Explicitly routes to alternatives with conditions: 'Direction-only view: ol_ownership_changes; fund-keyed inverse: get_13f_holdings,' and instructs to 'Check coverage.basis ... before quoting an aggregate.' Clear when-to-use-this vs when-to-use-that 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=true in annotations, the description carries (and richly fills) the behavioral burden: argument-dependent response shapes, hard cap and absence of pagination offset, prefix-word rather than semantic matching, sentiment as a label string, cron-populated multi-provider source, caveats surfaced in tool_notes, and an API-key/refusal requirement for anonymous callers.

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

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

Front-loaded with purpose and scope, then the response-shape warning, all in tight sentences with no filler. The all-caps emphasis is punchy but slightly shouty, and a few clauses (tool_notes, multi-provider provenance) could be tightened without any loss.

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

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

With no output schema, the description correctly compensates by spelling out both possible return shapes and their fields. Combined with the auth requirement, cap, and matching 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 100% so the baseline is 3, but the description adds real meaning beyond the schema: query matching is prefix-word not semantic, sentiment is a label string not a number, and ticker-only versus free-text queries produce different response shapes. That is substantive semantics 'limit'/'query'/'ticker' don't carry alone.

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

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

The description gives a specific verb+resource+scope: 'Read the Oxford Ledge news archive by ticker and/or keyword, newest first.' It is highly specific about behavior, but it never names or distinguishes itself from the closest sibling, search_news_archive, so an agent cannot fully route between them from the text alone.

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

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

It conveys clear operational context (newest first, default limit 25, hard cap 100, no pagination offset) and explains how argument choice changes the result, but it never states when to prefer this tool over search_news_archive or ol_bdc_borrower_news_today, nor any exclusion conditions. Usage is implied rather than routed.

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

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

With only readOnlyHint provided, the description carries the disclosure burden and does it well: exact response envelope on every path, error semantics, the fact that an unknown portfolio_id silently yields an empty list (so empty does not prove existence), the absence of any price leg, and the API-key/auth requirement with anonymous callers refused.

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

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

Front-loaded with the core purpose and return contract; every clause earns its place, though the capitalized emphasis (ONLY, THERE IS NO PRICE LEG) makes it denser than necessary. Still efficient for the amount of contract detail conveyed.

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

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

No output schema exists, so the description must describe the return shape, and it does so exhaustively: envelope keys, per-position fields, sorting, error/null behavior, and the empty-list ambiguity. Auth and valuation caveats are also covered, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by documenting the invalid-value behavior of portfolio_id (unknown ID returns positions=[] with error=null) rather than just its type and default.

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: 'Stored positions of one saved portfolio.' It explicitly contrasts with the catalog-wide sibling get_sector_breakdown, so an agent can distinguish it 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 names an alternative (get_sector_breakdown for sector mix) and warns that valuation must be done by the caller, which is real usage guidance. It stops short of a full when-to-use/when-not matrix against other position-like siblings such as get_13f_holdings or ol_paper_portfolio.

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?

Annotations only carry readOnlyHint=true, and the description adds substantial context beyond that: wording is unverified unless `verbatim` is true, the `attribution` line must be credited, output shape switches on the arguments, results are cached 24h per argument set, and caveats appear in tool_notes. This is exactly the behavioral disclosure an agent needs for safe reuse of the text.

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

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

Front-loaded with the resource identity, then the verification caveat, then the argument-dependent shape. Dense but every sentence carries information; the all-caps emphasis is slightly heavy but signals the two highest-risk facts.

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 describing both return shapes ({facts,count,total_facts} vs {fact,total_facts}), the 10-item cap, caching, and where caveats surface. 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 baseline is 3, but the description adds real meaning by explaining that `query` yields a capped list of 10 while a bare `category` or no arguments yields a single random pick. The enum vocabulary itself is documented in the schema rather than the description, keeping it from a 5.

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

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

States a specific verb (retrieve) and resource (a value-investing fact) with explicit scope: a curated ~2,000-entry corpus about Buffett, Graham, Munger, Klarman. It clearly separates itself from the market-data siblings by declaring itself 'pedagogical content only', so an agent can distinguish 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 a clear when-not ('never a market signal') and explains the two usage modes (query vs bare category/no args), which is genuinely actionable context. It does not, however, name a specific alternative sibling for adjacent needs (e.g. glossary terms), leaving that 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 provide readOnlyHint, so the description carries the behavioral load and does so well: 4h cache TTL, data sources (Treasury.gov par yields with FRED fallback), the removal of OAS and UMCSENT series with a date and reason, unit conventions, and where caveats surface (tool_notes). This is far beyond what annotations disclose.

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

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

Front-loaded with the resource and the two-shape distinction, and every sentence carries information. The heavy capitalization for emphasis is slightly noisy but does not waste space; total length is justified by the number of behavioral facts packed in.

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

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

No output schema exists, so the description must describe returns, and it does: exact shapes, tenor range, comparison periods, units, and which series are included or excluded. An agent can invoke this and interpret the response without further documentation.

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: the schema's 'include history for comparison' understates that the flag switches the entire response shape from a flat list to parallel arrays. That clarification is genuinely additive.

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 (US Treasury yield curve) and immediately flags that it returns two different shapes, one of which is a broader macro dashboard. This distinguishes it from siblings like get_fred_data or get_bond_data by stating exactly what series it covers (11 tenors, CPI, unemployment, GDP, mortgage rate, national debt).

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

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

Explicitly tells the agent when to use include_history=true (steepening/inversion work needing parallel arrays) versus the default flat latest-value list. It does not name a sibling alternative for the macro series or warn against overlap with get_fred_data, 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=true in annotations, the description carries the burden and adds substantial behavioral context: the return shape, the denominator caveat ('REPORTED 13F long-equity value, explicitly NOT AUM'), refusal on unreachable store ('DATA_UNAVAILABLE'), no fabricated turnover for single-quarter filers, and source/licensing details. These are 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?

The description is dense but front-loaded: purpose first, then input constraint, return keys, denominator caveat, sibling disambiguation, edge cases, and source. Every sentence carries actionable information for correct invocation or interpretation, 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?

Given no output schema, the description adequately explains the return object keys and the denominator semantics. It also covers refusal behavior, single-quarter limitations, and where caveats appear ('tool_notes'), making it complete for an agent 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 schema already documents the single 'fund' parameter. The description adds meaning by requiring a numeric CIK and warning that a ticker will not resolve, plus pointing to ol_13f_filer_search for lookup. This is useful clarification beyond the schema example, though it does not elaborate on format beyond 'numeric CIK'.

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 and scope: 'Institutional-filer behavior derived purely from 13F holdings: concentration (top-N %, normalized HHI), turnover, and persistence... for one filer.' It explicitly distinguishes from siblings by noting 'ol_13f_filer_search finds it' for CIK lookup and 'NO position list -- use get_13f_holdings' for holdings, so an agent can route correctly without opening other 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 gives explicit usage constraints: 'Pass a NUMERIC CIK (a ticker will not resolve here; ol_13f_filer_search finds it)' and names the alternative for position-level data: 'NO position list -- use get_13f_holdings.' It also states edge-case behavior for single-quarter filers and unreachable stores, 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?

Annotations only declare readOnlyHint=true, and the description adds substantial context beyond that: THE UNIVERSE IS CURATED (not live EDGAR), filers=[] means 'store answered, nothing matched' vs REFUSED/DATA_UNAVAILABLE for an unreachable store, and caveats are surfaced via tool_notes. That empty-vs-refused distinction is exactly the kind of failure-mode disclosure that prevents an agent misreading a result.

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

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

Front-loaded with purpose and routing before the operational details, and every clause carries information (return shape, ranking, universe, failure modes, source). It is a dense single block, but there is little true 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, yet the description fully specifies the return shape ({summary, query, filers:[{cik, name, last_filing, page_url}], count}) plus ranking and empty/refused semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents query (3-80 chars) and limit (default 5, cap 10) and the description repeats those bounds. It does add one semantic detail the schema lacks: H2 'name-PREFIX matches rank first', telling the agent how matches are ordered and 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 and resource: 'Resolve a 13F FILER name to its CIK'. It also draws an explicit boundary against the sibling search_company ('search_company resolves ISSUERS'), so an agent can disambiguate without opening either schema.

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

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

Gives the exact trigger condition ('when you know the manager ... and not its CIK') and positions itself as 'the front door to get_13f_holdings and ol_13f_filer_analytics'. Both the when-to-use and the alternative-flow are explicit.

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; the description adds substantial behavior beyond that: newest-first ordering, is_failure derived from the CHANGECODE taxonomy, resolved_from indicating which charter matched, ambiguous-name handling, and the crucial DATA_UNAVAILABLE-vs-empty-list error semantics. This is exactly the 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 core purpose and scope in the first clause, then layers on resolution semantics, error behavior, and sourcing. It is dense but nearly every clause carries distinct, decision-relevant information; a slightly tighter phrasing would reach 5.

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

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

With no output schema, the description still discloses return-relevant fields (is_failure, resolved_from, ambiguous candidate list, tool_notes caveats) and the failure mode (DATA_UNAVAILABLE). Nothing an agent needs to call or interpret the 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 coverage is 100%, so baseline is 3, but the description adds real meaning: `name` resolves against both active and closed charters (so failed banks are found) and `resolved_from` reports the match, which goes beyond the terse schema text. It does not elaborate on `limit` behavior beyond what the schema states.

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

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

States a specific verb+resource ('FDIC STRUCTURAL EVENTS for one bank') and enumerates the event types covered (failures, assisted resolutions, mergers, acquisitions, charter changes). It explicitly differentiates from the sibling ol_fdic_bank by noting it 'complements ol_fdic_bank (active institutions only).' An agent can distinguish it from every other 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?

Gives explicit selection rules: 'Pass `cert` (FDIC certificate) or `name`,' explains the cert-vs-name tradeoff, and routes the agent to call again with `cert` when a name is ambiguous. It also names the alternative (ol_fdic_bank) and the condition that selects it.

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

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

Annotations only provide readOnlyHint=true, so the description carries the behavioral load and does so richly: exited positions excluded by default with the include_stale override, default 25 lenders with hard cap 100, the units trap (spread vs spread_bps), SEC EDGAR source, FREE cost, and that caveats ride tool_notes. This is well beyond what annotations supply.

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

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

Dense but front-loaded, leading with the MOAT purpose before the example and the units warning. Nearly every clause earns its place; the stacked parenthetical metadata (source, parse attribution, FREE) 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?

With no output schema present, the description compensates by outlining the return shape ({summary, borrower_norm, count, lender_count, tranche_count, lenders}), the row granularity (one per lender, tranches nested, widest spread first), and where caveats live. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains match_type-based resolution of borrower_norm, the stale-mark semantics behind include_stale, and warns about the spread/spread_bps field trap. It adds context 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 and resource: cross-lender loan-pricing dispersion for one borrower, showing how N BDCs price the same loan. The concrete S+550 @ 98 vs S+575 @ 99 example makes the concept unmistakable and distinguishes it from sibling pricing tools like ol_bdc_mark_changes or ol_bdc_loan_pricing_trend.

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

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

Clearly frames the use case and explicitly routes the required borrower_norm input to ol_bdc_top_borrowers or search_bdc_borrower. It does not explicitly state when to prefer a sibling (e.g. loan_pricing_trend) or when-not, but context is otherwise 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?

Goes well beyond the lone readOnlyHint annotation: discloses the >=0.9 confidence verification threshold, headline+link-only payload (no provider summary) to prevent false attribution, hard caps on all three params, that empty items means absence-not-signal, that an unreachable store returns DATA_UNAVAILABLE, and that an API key is required with anonymous callers refused.

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 the question it answers, then packs behavioral detail tightly. It is dense but somewhat repetitive, restating defaults/caps already in the schema, which costs a little efficiency.

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 specifies the return shape ({summary, count, items} with per-item fields), the empty-result and DATA_UNAVAILABLE semantics, and the auth requirement — 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 description coverage is 100% and each parameter already documents its default and hard cap, so the schema carries the load. The description repeats the same defaults/caps (limit 25/100, since_days 7/90, min_holders 2/max 50) without adding format or semantic detail 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 (recent VERIFIED news for private-credit borrowers held across MULTIPLE BDCs) and frames the exact question it answers. It is clearly distinguishable from siblings like get_news, search_bdc_borrower, and ol_bdc_common_borrowers by its cross-BDC borrower-news scope.

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 user question ('what broke recently for the cross-BDC borrowers I should watch?') gives a clear usage context, and the 'MOAT / daily pulse' framing implies recency-driven monitoring. However, it never names an alternative tool or states when NOT to use it (e.g., vs. generic get_news or search_bdc_borrower).

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 full behavioral burden and does so richly: it discloses the mixed-filing-date caveat, that rows mix as_of dates, that only debt positions are included, the truncation and cap behavior, the data source (SEC EDGAR BDC schedules, Oxford Ledge parse), that it is free, and that caveats appear in tool_notes. This goes 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?

Dense but front-loaded: the first sentence defines the tool and its core question, followed by return fields, caveats, caps, and related tools. Every sentence earns its place given the tool's complexity, and there is no filler.

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

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

No output schema exists, but the description enumerates the returned fields (borrower, borrower_norm, holder_count, holder_tickers, holders, total_fair_value, total_par_amount, as_of_oldest/newest), explains date-mixing, caps, source, and where caveats live. 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 description coverage is 100%, so baseline is 3. The description mostly repeats caps already in the schema (limit 50/200, min_holders max 50), but adds one non-obvious behavior: bdc_tickers is truncated at 25 (schema says max 25 but not what happens on overflow). That small addition bumps it slightly above 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+resource (borrowers common to a given set of BDCs) and frames it as the cross-portfolio set question, with a concrete example. It is immediately distinguishable from sibling ol_bdc_top_borrowers (single BDC) and points to ol_bdc_borrower_dispersion for follow-on pricing.

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

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

Explicitly says when to use this tool (cross-portfolio set question) and names alternatives: 'for one BDC's book use ol_bdc_top_borrowers' and 'Feed a borrower_norm to ol_bdc_borrower_dispersion.' It also clarifies the min_holders semantic (what is SHARED). Nothing is left to inference.

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

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

Annotations only declare readOnlyHint, but the description discloses substantial behavior beyond that: the response shape {summary, ticker, latest, trend}, that trend is OLDEST-FIRST, that flagged_pct uses a determinate-flag denominator rather than total_debt_fv, and that it is deliberately NULL (never zero) when determinate coverage falls under 90% or the flag rate looks misparsed. It also names the data source (SEC EDGAR schedule-of-investments, Oxford Ledge parse), states the tool is FREE, and points to tool_notes for caveats.

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

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

The purpose and primary metric are front-loaded, and each clause carries real information (denominator rule, NULL policy, trend ordering, source). It is dense and slightly run-on with heavy punctuation, but there is little pure filler.

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

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

With no output schema, the description compensates by naming the returned fields and the ordering of trend, plus the critical NULL/coverage_state semantics an agent must respect before interpreting flagged_pct. It also covers the data source and where caveats live, leaving nothing essential unstated for a two-parameter read 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 both parameters are documented in the schema, so the baseline is 3. The description repeats the quarters default of 12 and hard cap of 24 without adding format or syntax beyond the schema, and says nothing extra about ticker handling.

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 ('BDC non-accrual credit-deterioration signal') and the exact metric measured ('share of debt fair value on non-accrual ... in the latest filing, plus the trailing-quarter trend'). It also names the sibling tools it complements (ol_bdc_borrower_dispersion, ol_bdc_top_borrowers), so an agent can place it within the BDC family 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?

Provides clear context: it is a latest-filing credit signal that 'pairs with' two named sibling tools, which helps routing among the many ol_bdc_* siblings. It also warns that flagged_pct must be read only after coverage_state, an implicit usage condition. It stops short of explicit when-not or alternative-selection rules, so it is not 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?

With only readOnlyHint provided, the description carries and exceeds its behavioral burden: it explains null-vs-zero handling, refusal as DATA_UNAVAILABLE for unreachable stores, that internally-managed BDCs have no fee lines, and that caveats ride response tool_notes. This is rich, non-contradictory behavioral 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?

The definition is dense but front-loads purpose and return shape, then layers edge cases and source provenance. Every sentence is substantive, though the semicolon-heavy delivery makes it slightly less scannable 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?

There is no output schema, so the description must carry return semantics, and it does: it names the top-level keys, explains fees and dividend_coverage units, and clarifies what is not returned. Along with the source and caveat behavior, an agent has enough to call and interpret the tool correctly.

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

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

Schema description coverage is 100% and the single ticker parameter is already documented with examples in the schema. The description adds no extra ticker semantics, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: BDC fee load plus NII-based dividend coverage for one fiscal year. It explicitly distinguishes the scope from a series and from a vendor fundamentals feed, so an agent can tell it apart from siblings like get_fundamentals or ol_bdc_credit_quality.

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 clear context that the tool is for ONE fiscal year (not a series) and notes that internally-managed BDCs carry no fee lines by construction. It does not name a specific sibling alternative, but the scope exclusions and source caveat are enough to guide appropriate use.

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: it discloses unit normalization ('BASIS POINTS, normalized at the store', never average raw spreads), parser-grain sensitivity of position counts, honest-empty behavior (trend=[] for an unparsed BDC), the data source/parse lineage, and where caveats live (response tool_notes). That is rich behavioral context 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 purpose and scope in the first clause, then dense telegraphic fragments. Nearly every clause earns its place (units, field preference, defaults, empty case), though the backtick-heavy fragments and output-shape listing push it toward the verbose 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 still outlines the return shape ({summary, ticker, count, spread_unit, trend}) and explains spread_unit semantics, defaults, empty behavior, and caveat location. 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%, so both parameters are already documented; the description's 'quarters default 16, max 24' only restates the schema. It adds no new parameter-level semantics (e.g. ticker format constraints), 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 precise verb+resource+scope: 'Per-quarter loan-pricing trend for ONE BDC, from the parsed schedule of investments'. It names the exact metric (fair-value-weighted average credit spread, average mark, position counts) and the output ordering (OLDEST-FIRST), which cleanly separates it from sibling BDC tools like ol_bdc_credit_quality and 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 real selection guidance: 'Prefer priced_borrowers over debt_positions across quarters' and 'Pairs with ol_bdc_borrower_dispersion', plus the explicit per-ONE-BDC scope. It does not state when to choose this over the other BDC siblings (e.g. ol_bdc_credit_quality), so it stops short of explicit alternatives/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 cover only readOnlyHint=true, and the description adds substantial behavioral detail beyond that: the inclusion thresholds (|mark_delta| >= 1.0pt and fair value >= $500k), what is excluded into `suspect_moves`, what `coverage` reports for unread BDCs, the 25-ticker cap and 10/50 row limits, the data source, and that caveats ride in tool_notes. This is exactly the extra 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?

The description is dense and front-loaded, leading with the purpose and the exact question answered before the response shape and constraints. Every clause carries information, though the cap/limit details are repeated from the schema, adding slight redundancy.

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

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

With no output schema, the description carries the burden of describing returns and does so fully: the {increases, decreases} top-level shape, the per-row fields, `suspect_moves`, `coverage`, and `tool_notes`. 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%, so both parameters are already documented in the schema (including the cap behavior and global ranking note). The description largely restates the caps and adds nothing new about parameter syntax or format, so the baseline of 3 applies.

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

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

States a precise verb and resource: quarter-over-quarter mark moves across a SET of BDC portfolios, with the exact question it answers ('which borrowers got marked up or down the most last quarter, and by whom'). This clearly differentiates it from siblings like ol_bdc_borrower_dispersion, ol_bdc_credit_quality, 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?

Gives a clear context for use ('which borrowers got marked up or down the most last quarter') and stresses it is 'ONE deterministic call' for a set of portfolios, implying batch/ranking usage. It does not, however, explicitly name alternatives or state when NOT to use it versus a sibling like ol_bdc_borrower_dispersion.

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 ranking tie-breakers, hard/default caps, that mis-parsed rows are filtered only when the filter is available, the `borrower_filters` flag, the data source and freshness ('latest filings'), cost (FREE), and that caveats live in tool_notes. That is unusually rich behavioral context for a read-only tool.

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

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

Front-loaded with purpose and ranking before return shape and caps, and every sentence carries information. It is dense with parentheticals (borrower_norm, holder_count_active, whole USD) that slow reading slightly but are not 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 envelope {summary, count, borrowers} and per-row fields, plus source, cost, caps, and where caveats appear. Nothing an agent needs to call or interpret the result is missing.

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

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

Schema coverage is 100% and both parameters (limit, min_holders) are already fully documented in the schema, including their defaults and caps. The description restates the same caps and min_holders meaning without adding new syntax or edge-case semantics, so baseline 3 applies.

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

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

States a specific resource (private-credit borrowers syndicated across BDCs) and an explicit ranking rule (holder_count_active, then holder_count, then exposure), and positions itself as 'the entrypoint for the BDC/private-credit category', which separates it from ol_bdc_common_borrowers and get_bdc_list.

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 downstream handoff ('Feed a borrower_norm into ol_bdc_borrower_dispersion for cross-lender pricing') and calls itself the category entrypoint, giving clear context for use. It stops short of stating when NOT to use it versus the other BDC sibling tools.

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

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

Annotations only declare readOnlyHint=true, so the description carries the real load and does so richly: auth requirement (operator-configured key, anonymous refused), limit default and hard cap, provenance/redistribution restriction, and that caveats ride tool_notes. This is well beyond what the annotation provides.

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

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

Front-loads the purpose, then return shape, then constraints; dense and mostly earns its place. Minor redundancy (limit default/cap and grade-as-source-bucket are stated in both description and schema) keeps it from a 5.

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

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

No output schema exists, yet the description documents the return envelope ({summary, count, total_matching, bonds}) and per-bond fields, plus auth and provenance constraints. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all 8 params, including the 'not a rating' grade note and offset/coupon-band interaction. The description largely restates those semantics rather than adding new meaning, so baseline 3 is appropriate.

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

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

States a specific verb (screen) and resource (corporate-bond browse directory) with the filter dimensions, and the 'browse directory' framing plus reference-data-only note distinguishes it from search_bonds and get_bond_data. An agent can tell it apart from siblings without opening a schema.

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

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

Gives clear context: reference data only, no price/yield/spread/trade activity, first-party-only, requires an API key. However it never explicitly names the alternative tools (e.g., search_bonds or get_bond_data) or states the condition that would route an agent to them 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?

With only readOnlyHint=true in annotations, the description adds substantial behavioral detail: acquisitions are VERIFIED-only (unaudited/refuted events never surface), footprint matching is exact-normalized-name with matched_entities provenance, same-name matching is not a guaranteed identity, empty footprints are normal, and the tool is honest-empty on unknown keys. It also discloses source and cost (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?

One dense paragraph, front-loaded with the purpose and return shape, and each clause carries information (verified-only filter, matching caveats, source, cost). It is information-dense rather than padded, though the long enumerations make it heavier than strictly needed.

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

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

No output schema exists, but the description enumerates the return payload ({summary, borrower_norm, borrower, profile, acquisitions, count, public_footprint}), explains empty/honest-empty behavior, and notes that caveats ride in tool_notes. 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 both parameters are already documented in the schema (borrower_norm's key/name resolution and limit's default 20/hard cap 100). The description largely restates the key-source and name-resolution semantics rather than adding new meaning, 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+scope: 'Profile + verified M&A/ownership history for one private-credit borrower.' It also names the key source (ol_bdc_top_borrowers), distinguishing it from sibling borrower tools like search_bdc_borrower and 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?

It specifies the input contract ('Pass borrower_norm (a key from ol_bdc_top_borrowers, or a name)'), which routes the agent to the upstream tool. However, it never states when to choose this profile tool over sibling borrower tools, nor any exclusion conditions, leaving usage implied rather than explicit.

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; the description carries the rest and does so richly: units are CONTRACT counts not dollars, mm_* semantics differ by report family (Managed Money vs Leveraged Funds), limit default 52 / hard cap 156, refusal behavior on unreachable store (DATA_UNAVAILABLE), and where caveats appear. This is exactly the context annotations cannot supply.

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

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

Front-loaded with purpose, then usage, then behavioral caveats and attribution. Dense with no filler, but it packs selection-relevant and output-relevant details into one long block, slightly blurring the scan for a tool-selection decision.

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 names the return shape ({summary, market, matched_market, rows}), explains field units and semantics, and points to tool_notes for caveats. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: name normalization ('wti', 'GOLD', 'e-mini s&p' resolve) and the fact that `limit` applies to the series only, plus the newest-first ordering. That goes beyond the schema's terse parameter docs.

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

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

States a specific verb+resource (CFTC Commitments-of-Traders positioning) and scopes it to three named curated markets with their keys. No sibling covers CFTC COT data, so the agent can immediately tell what this tool is and what it returns.

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

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

Explicitly routes between the two modes: 'Pass `market` for its weekly history... or omit it for the latest report across the three.' Clear context for both paths, though it offers no explicit when-not or alternatives (there are no overlapping siblings, so this is minor).

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

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

Annotations only declare readOnlyHint=true; the description carries everything else and does so richly: the two data sources are NOT merged, published_events come from the issuer's own IR calendar while estimate is a model projection with confidence, published_events_degraded must be read before treating the note as fact, and caveats ride tool_notes. This is well beyond what the annotation provides.

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

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

Dense but front-loaded: purpose first, then return shape, then the non-merging rule, then scope, then sibling differentiation, then source/cost. Every sentence carries load, though the packing of caveats makes it 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?

No output schema exists, so the description must explain return values — and it enumerates the response keys and their provenance semantics. Scope limits, degradation flag, presentation rules, and source are all covered, leaving nothing 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?

One parameter at 100% schema description coverage, so the schema already documents 'ticker'. The description reinforces 'one issuer' (single-ticker scope) but adds no format, exchange-suffix, or casing guidance. 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: 'Upcoming EARNINGS DATES for one issuer', and immediately distinguishes itself from the sibling get_economic_calendar (macro releases). An agent can select it without opening the schema.

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

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

Explicit exclusions ('US domestic 8-K filers only'), explicit alternative ('Distinct from get_economic_calendar'), and explicit handling instruction ('prefer a published date yourself, and never present the estimate as a company announcement'). The when/when-not/alternative triad is fully present.

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

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

With only readOnlyHint provided, the description carries the burden well: it discloses the return shape, value-rank ordering and caps, the opaque=true + reason behavior for unfiled holdings, the DATA_UNAVAILABLE distinction for store outages, the ~60-day N-PORT lag, FREE cost, and where caveats live (tool_notes).

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

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

Front-loads the core purpose in the opening clause, and every subsequent sentence adds operational value. It is dense and enumerates many output fields, which edges toward over-stuffing, but nothing central is buried or wasted.

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

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

With no output schema, the description fully compensates: it names the response envelope, per-ETF fields, edge-case states, the data source and its latency, and the cost model. An agent has everything needed to call it 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 genuine semantics beyond the schema: top_holdings is 'value-ranked' (an ordering meaning absent from the schema), and it clarifies value_usd is whole USD and weight_pct is derived so rows won't sum to 100.

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

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

States a precise verb and resource: 'expand up to 25 ETF tickers into the underlying holdings the fund ITSELF filed on Form N-PORT.' The N-PORT framing and 'look-through' scoping clearly distinguish it from sibling holdings tools like get_13f_holdings or get_institutional_holders, which cover different filings.

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 (ETF tickers in, underlying holdings out) plus an explicit exclusion: 'HOLDINGS-ONLY: no yield, NAV or premium,' tells the agent when NOT to rely on it. It does not name a concrete sibling alternative, 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?

Goes far beyond readOnlyHint: discloses that the store is ACTIVE-ONLY so merged/failed banks are absent by construction, that misses surface a `structure_event` explanation, that an unreachable store is REFUSED with DATA_UNAVAILABLE, and that `ticker` is a proprietary mapping rather than FDIC data. 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?

Front-loads purpose and the two modes before the units, store, and attribution caveats. Dense but every clause carries operational information; the all-caps emphasis is heavy-handed 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?

With no output schema, the description supplies the return shape ({summary, query?, found?, institutions}), the unit convention, failure semantics, and attribution caveats. 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 real meaning: `query` is a name PREFIX (not substring), results are largest-asset first, and `asset`/`dep` are in THOUSANDS of dollars. Only minor parameter nuance remains undocumented.

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

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

States a specific verb and resource ('FDIC-insured banks and thrifts') plus the exact lookup modes: prefix search on `query` or a top-by-assets list. An agent can distinguish this from ol_bank_structure_events, which it explicitly references for structure-event explanations on misses.

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 explains both invocation modes ('Pass `query` for a name PREFIX search... or omit it for the largest active institutions') and what a miss means. It does not name a competing tool to use instead for other bank questions, so it falls short of the explicit alternatives bar.

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

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

Goes well beyond readOnlyHint=true: it discloses ordering (newest FY first, largest first), the partial-FY trap (period_complete false, year-to-date, never compare to a full year), the semantic caveat that awards are not company revenue, the DATA_UNAVAILABLE refusal, the free/public-domain source, and that caveats live in tool_notes.

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

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

Dense but front-loaded: the two shapes, the required-one-of rule, and the ordering caveats come in sequence, and no sentence is filler. Slightly long for a 3-param tool, but each clause carries operative 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 full burden and meets it: it describes the return shapes, fields (ten largest recipients, dropped_unresolved), ordering, partial-year flag, and where caveats surface. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: the ticker-over-fiscal_year precedence rule and the distinct semantics of fiscal_year alone (leaderboard of crosswalked public companies). Limit's default/cap is restated from the schema.

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

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

States a specific verb+resource ('Federal-contract obligation history') and explicitly names the two shapes it returns (ticker history vs. fiscal-year leaderboard). No sibling covers federal contracts, so it is trivially distinguishable and the dual-mode framing removes ambiguity.

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 the decision context ('for government-revenue-dependence diligence') plus the routing rule that exactly one of ticker/fiscal_year is needed and ticker wins ties. It does not name an alternative tool or state when-not-to-use, but no sibling competes here, so the guidance is adequate.

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 the annotations, the description carries the behavioral load and does it well: metered AI quota (25/day, UTC reset, burst limiter), auth requirement (signed-in account or API key, anonymous calls fail AUTH_REQUIRED), and a crucial semantic warning that `score` is a fused-rank value comparable only within one response, not a similarity.

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

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

The purpose and metering caveat are front-loaded, and the return-shape sentence is dense but useful. It loses a point for redundancy: the auth requirement is stated twice ('it needs a signed-in account or an API key' and 'anonymous callers are refused') within a single paragraph.

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

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

There is no output schema, but the description compensates fully by enumerating the response envelope ({summary, ticker, count, chunks, quota_remaining_today}) and each chunk's fields, plus where caveats appear (tool_notes). An agent has everything needed to call it 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 description coverage is 100%, so `ticker`, `query`, and `k` are already documented in the schema; the description's restatement of k's default 5 / cap 15 adds nothing new. It does add meaning about the `score` field, but that is an output, not a parameter, 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?

The description states a specific verb and resource: semantic retrieval over embedded SEC filings for a ticker, driven by a natural-language question. It clearly distinguishes itself from the structured-data siblings (get_fundamentals, get_13f_holdings, etc.) by being the qualitative chunk-retrieval tool, so an agent can route to it without opening any schema.

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

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

It gives a concrete usage pattern ('ask a natural-language question... get the most relevant filing CHUNKS back') and flags that this is the ONE metered tool, which implicitly tells the agent to spend it deliberately. It does not, however, name a specific alternative (e.g., search_company or search_news_archive) or state when-not to use it, so it falls 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?

Annotations only declare readOnlyHint=true, and the description substantially enriches that with the quarterly posting lag (~one quarter after quarter-end), the limit default of 50 and hard cap of 200, the fact that amounts are whole USD as disclosed, and that total_offering_amount is a ceiling rather than money raised. It also tells the agent where caveats live ('ride the response's tool_notes').

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

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

Front-loads what the tool returns and its scoping, then layers caveats in short, information-dense sentences. No filler; the warning about empty windows is placed before the operational details where it matters most.

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 response shape ({summary, count, days, industry, offerings}), notes that caveats ship in tool_notes, and covers the lag/cap semantics. An agent has everything needed to call it 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%, so the baseline is 3; the description goes slightly beyond by reinforcing the empty-window behavior of `days` and the hard cap on `limit`, and by interpreting the returned amount fields. It adds interpretation rather than raw parameter syntax, so it is above baseline but not exceptional.

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

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

Names a specific verb+resource ('Recent SEC Form D private-placement filings'), states scope ('newest first, optionally scoped to industry group and/or trailing filing-date window'), and cites the source data set. An agent can distinguish this from siblings like ol_filing_search or ol_13f_filer_search without opening any schema.

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

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

Gives clear context for when the tool applies and an explicit warning about when a result will be misleading ('a short `days` window is EMPTY BY CONSTRUCTION -- not evidence that nothing was filed'). It does not, however, name an alternative sibling for other filing types, so it stops short of full when-not/alternatives 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?

Adds substantial behavior beyond the readOnlyHint annotation: silent truncation to the FIRST 10 unique tickers, the critical rule that a MISSING METRIC FAILS its criterion (so a fail can mean 'no data'), the caveat location (tool_notes), and the data source. This is exactly the kind of context an agent needs to interpret results correctly.

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: scope, criteria, return shape, caveats, and disclaimers in a tight block with no filler sentences. It reads as run-on in places, which slightly hurts readability, but every clause carries signal.

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 enumerates the response shape ({summary, count, passing_count, criteria, results, as_of}) and each result's fields, plus the failure semantics and caveat location. Nothing material is missing for correct invocation and interpretation.

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 adds genuine meaning beyond the schema: unit conventions (whole USD, *_pct as percentage numbers) and, crucially, that tickers are silently capped to the first 10 unique — information the schema's 'hard-capped at 10' does not convey.

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

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

States a specific verb and resource: a threshold screen over a caller-supplied ticker set on latest-year SEC EDGAR XBRL fundamentals. It also explicitly distinguishes itself from siblings by denying discovery/universe-sweep behavior and disclaiming a buy signal.

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

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

Gives clear when-not guidance: 'never sweeps a universe', 'not a discovery screen', 'a fundamentals filter, NOT a buy signal'. It stops short of naming the specific alternative tool (e.g., get_fundamentals or ol_peer_fundamentals) for the discovery case, so it isn't a full 5.

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

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

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?

Beyond the readOnlyHint annotation, the description discloses that absence of clusters is not a signal, that an unreachable store is refused, that the window is on FILING date (look-ahead-safe), that it is free, and that caveats live in tool_notes. These are substantive operational traits not derivable from 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?

Dense but front-loaded with the flagship framing and grain routing ahead of return-shape and caveat details. Every sentence carries information, though the heavy capitalization and packed clauses make it slightly harder to parse than an ideal size.

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 envelope {summary, count, events, grain, since_days, limit} plus per-event fields, and covers grain selection, windowing, and failure behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter; baseline is 3. The description adds value by framing the ticker/tickers/neither interplay as three distinct grains, clarifying the semantics of omitting both, which the schema only states more tersely.

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

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

States a specific verb and resource ('scan for ACTIVE multi-insider cluster-buy/sell signals') and qualifies it as distinct-actor Form 4 clusters with statistical strength. An agent can distinguish this from siblings like ol_insider_recent_buys or get_insider_activity without opening a schema.

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

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

The 'THREE GRAINS' sentence explicitly states when to pass `tickers`, when to pass `ticker`, and when to pass neither for the market-wide scan. This is direct when-to-use 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 readOnlyHint=true already covering safety, the description adds substantial behavioral context: return ordering (newest first), the hard caps on since_days/limit, the SAMPLING TRAP that results are the newest N filings rather than the whole window, which fields are derived, the SEC EDGAR source, and that caveats ride tool_notes. This is exactly the kind of non-obvious trait an agent needs to avoid misreporting totals.

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 caveats and sourcing; nearly every clause earns its place. It does restate the since_days/limit defaults and hard caps that already live in the schema, a minor redundancy that keeps it from a 5.

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

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

No output schema exists, yet the description specifies the return envelope ({summary, since_days, count, buys}), per-row fields, ordering, truncation behavior, and data provenance. For a four-parameter read tool with annotations covering safety, nothing an agent needs to call or interpret it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by explaining how `limit` interacts with the window (newest-N truncation) and by flagging totalValue and the fallback `position` label as the two derived fields. That is real added semantic value rather than restatement.

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

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

Names a specific verb and resource ('Recent OPEN-MARKET insider PURCHASES, SEC code P') and scopes it to the Oxford Ledge issuer catalog (~5.3k tickers) as a daily screen. It explicitly distinguishes itself from siblings by naming ol_insider_cluster_scan and get_insider_activity, so an agent can tell the three apart 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?

Frames the tool as a daily insider screen and points to the sibling tools it pairs with, plus a clear warning about the sampling trap that governs correct use. It stops short of an explicit 'use this instead of X when Y' routing rule, but the context is strong and actionable.

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

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

Annotations only declare readOnlyHint=true; the description adds substantial context beyond that: the full verdict enum, the guarantee that verdicts are never coerced to neutral, the location of caveats (response tool_notes), the data source, and the absence of tier gating or AI metering. It does not discuss latency, rate limits, or what happens when coverage is thin beyond the two insufficiency verdicts.

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 verb and the fused inputs come first, then return shape, then the derived-vs-raw distinction, then provenance. Every sentence carries information, though the enumeration of verdict values is lengthy and slightly crowds the 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 fully by naming the returned verdict values, the accompanying payload fields (institutional, insider, cluster, coverage, summary), and where caveats live. An agent can call this correctly and interpret the response without additional documentation.

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

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

Schema description coverage is 100% for the single ticker parameter, so the schema already carries the load. The description reinforces that the read is scoped to one ticker and fused on that ticker's reference 13F quarter, but adds no 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?

Names a precise verb and resource ('quarter-aligned institutional-confluence read for one ticker') and enumerates the exact inputs fused (13F accumulation x Form 4 net buying x buy-cluster). It also explicitly distinguishes itself from siblings by stating it is a DERIVED verdict with no per-fund rows, which separates it from get_13f_holdings/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?

Explicitly names the companion tools ('Pairs with get_institutional_holders and ol_insider_cluster_scan') and clarifies when to prefer this tool over raw-data siblings via 'A DERIVED verdict, not raw data: no per-fund rows.' It does not spell out an explicit when-not or a decision rule for choosing among the three, 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?

Highly transparent beyond the readOnlyHint annotation: reveals null semantics ('A model is null when its inputs are negative or missing'), retry guidance for fetch_error, DCF methodology caveat (FCFE-style not EV-DCF), fixed assumptions, and source. This is the description's core strength.

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 return shape and caveats come before the technical details. Every sentence adds operational value, though the output-shape enumeration is verbose. Appropriate 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?

Complete for a 1-param read tool with no output schema. It specifies return keys, units (USD per share), null behavior, retry semantics, methodology caveat, and where caveats are surfaced. An agent has everything needed to call and interpret the result.

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

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

Only one parameter with 100% schema coverage ('Stock ticker symbol (e.g. AAPL)'). The description adds no syntax beyond the schema. Baseline 3 is appropriate when the schema fully documents 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?

Specific verb+resource: 'Per-share intrinsic value from SEC EDGAR XBRL' with three named textbook models. Clearly distinct from sibling tools like get_fundamentals or ol_peer_fundamentals because it computes valuation estimates rather than reporting raw facts.

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?

Implicit when: value an issuer's shares. The description explains what is and isn't returned ('NO current price, market cap or margin of safety is returned -- fetch a price yourself'), which guides downstream usage. Does not name explicit alternatives, but the boundary against siblings is clear from the purpose 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?

Annotations only declare readOnlyHint=true, so the description carries real disclosure burden and delivers: absence is first-class (value=null with is_absence=true and metric_availability explaining why), values are confidence-gated, needs_review rows are excluded, and caveats ride tool_notes. This is behavior an agent could not infer from annotations or schema.

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

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

Dense but front-loaded: the core purpose and absence semantics lead, and the sibling routing and caveat notes follow. Almost every sentence adds usable information, though the ALL-CAPS emphasis and parenthetical list make it slightly heavier than needed.

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

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

With no output schema, the description must explain return shape, and it does: metric rows with definitions, full provenance, null/is_absence rows as valid answers, confidence gating, and tool_notes caveats. Nothing critical 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 all five parameters (ticker, metric, period, industry, limit) are already documented in the schema. The description names the optional filters but adds no syntax or value guidance beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb+resource with scope: a per-issuer KPI panel of curated metric rows (ARR, RPO/cRPO, NRR, etc.) extracted from SEC filing exhibits. It explicitly distinguishes itself from the sibling ol_operating_kpis ('For broad operating KPIs across 26 configured industries use ol_operating_kpis'), so an agent can choose between them 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 when-to-use (single-issuer curated KPI rows) and when-not ('Per-issuer by design. For broad operating KPIs across 26 configured industries use ol_operating_kpis'). Also flags the hard constraint that cross-issuer panel reads are not answerable on this surface.

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

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

Annotations provide only readOnlyHint, so the description carries the behavioral load and does so richly: USD-millions units, an explicit warning that by_rating uses a leverage heuristic rather than agency ratings, coverage limited to parsed schedules with unscheduled issuers NAMED not estimated, live SEC EDGAR fetching with seconds-per-issuer latency, and caveats deferred to tool_notes. These are exactly the traits an agent cannot infer from 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?

Dense but front-loaded: the resource and its output blocks come first, then caveats, coverage, and latency. Every clause carries information, though the em-dash-heavy style is slightly 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?

With no output schema, the description still names the return fields, units, coverage limits, data source, cost, latency, and where caveats live. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% with only two parameters, so the schema already documents both. The description reinforces the tickers semantics (max 50, omit for market-wide) but says nothing about by_sector, so it adds only marginal value over the schema 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 ('scheduled bond/loan maturities aggregated by year') and enumerates the return blocks (total_by_year, by_rating, top_issuers_by_year, peak_year, concentration), so the agent knows exactly what comes back. It does not differentiate itself from the very similarly named sibling get_debt_maturities, which is the one disambiguation an agent most needs here.

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

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

The description clarifies scope mechanics ('market-wide when tickers is omitted, or scoped to up to 50 tickers') and warns about live-fetch latency, which implicitly guides usage. However it never states when to choose this over alternatives such as get_debt_maturities or get_bond_data, leaving the closest sibling distinction 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?

Goes well beyond readOnlyHint: discloses auth-tier behavior (anonymous callers capped at 3 rows and flagged partial, keyed callers get the full panel), the AS-REPORTED/confidence-gated nature of values, live coverage being a subset of 26 configured industries, the ambiguous available=false semantics with explicit do-not-retry guidance, and where caveats surface (tool_notes, provenance). This is exactly the kind of 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 core purpose and source before edge cases, and nearly every clause carries information the agent needs (auth tiers, coverage caveat, no-retry rule). It is dense and somewhat packed into one paragraph, with the metric-example list costing a little space, but nothing is wasted.

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

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

For a specialized per-issuer data tool with no output schema, the description still enumerates the returned panel fields (ticker, industry, metrics, available, partial, total_metrics, period, as_of, provenance, caveat), coverage limits, auth behavior, and the ambiguity trap. An agent has everything needed 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% and only one parameter exists, so the schema already documents the ticker and its per-issuer constraint. The description reinforces the single-issuer design but adds no syntax or format detail beyond what the schema states. Baseline 3 is appropriate.

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

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

States a specific resource (industry operating KPIs) scoped to ONE issuer, with a vivid enumeration of the metrics it covers (same-store sales, RevPAR, load factor, medical-loss ratio, ...) and the source (SEC 10-K/10-Q/8-K exhibits). The scope is unmistakable. It does not, however, name or differentiate from the near-identical sibling ol_issuer_kpi_panel, which is the one ambiguity an agent would actually trip over.

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 use (per-issuer panels by design, no cross-issuer screen) and explicit boundaries (do not retry with variations when available=false). It implicitly contrasts with income-statement data via 'the operational numbers the income statement hides', but never names an alternative tool such as ol_issuer_kpi_panel or get_fundamentals to route the agent explicitly.

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

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

Annotations only declare readOnlyHint=true, so the description carries the behavioral burden and delivers: it discloses the split_suspect withholding of unconfirmed corporate actions, that counts are always complete vs. row limits, that share classes are never summed/netted, and that figures are CUSIP-resolved approximations with caveats in tool_notes. It omits any error/rate-limit or empty-response behavior, keeping it just below a 5.

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

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

Dense but front-loaded: purpose first, then return shape, then the limit semantics, then caveats. The inline JSON return listing and the 'Source: SEC EDGAR 13F-HR ...; FREE' tail are slightly noisy but each line carries substantive 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 two-parameter read tool with no output schema, the description supplies the return shape, the completeness guarantee, the withholding behavior, and the provenance/source needed to trust the data. What remains missing is behavior on bad tickers or empty results, a minor gap.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning the schema doesn't: it clarifies that limit bounds EACH row list while counts remain the complete tally, and states the default/hard-cap relationship, which prevents a common misreading of pagination.

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

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

States a specific verb+resource+scope: quarter-over-quarter institutional accumulation/distribution for one ticker, with the four classification buckets spelled out. It also distinguishes itself from the sibling snapshot tool get_institutional_holders and gives a memorable framing ('who is moving on X?').

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 complements get_institutional_holders (snapshot), which tells the agent when to pick this flow-read over the point-in-time read. It stops short of stating when-not-to-use or naming other close alternatives like get_institutional_consensus or ol_institutional_confluence.

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

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

Reads as exceptionally candid for a readOnly tool: it discloses never-cached behavior, delayed-quote mark-to-market at read time, the honest empty portfolio shape ({has_portfolio: false, how_to_start}) versus an error, AUTH_REQUIRED on stdio, the per-response _meta.disclaimer that this is practice money, and that caveats ride tool_notes. These are all traits the readOnlyHint annotation 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?

Front-loads the purpose and the exact response key list, then layers parameters and constraints; nearly every clause carries information. The auth requirement is stated twice ('Requires an authenticated Oxford Ledge caller' and again 'Needs an Oxford Ledge API key... anonymous callers are refused'), which is the one redundant beat in an otherwise dense passage.

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

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

With no output schema, the description fully compensates by enumerating the response keys (portfolio, positions, totals, position_theses, summary, has_portfolio) plus the conditional recent_trades and empty-state keys, and it covers auth, caching, and error behavior. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented; the description restates the same facts (include_history adds recent_trades, history_limit 1..50, default 20) and only marginally enriches them by calling the entries 'fills'. With the schema doing the heavy lifting, 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 ('YOUR paper (practice) portfolio on Oxford Ledge') and pins the scope precisely — caller's own paper portfolio, matching the /practice/ web sandbox. The 'paper (practice)' qualifier cleanly separates it from the real-portfolio sibling get_portfolio_positions, 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?

Usage context is implied rather than stated: it explains the auth conditions under which the tool works (API key or OAuth token; local stdio server returns AUTH_REQUIRED) and when to set include_history, but never names an alternative or a when-not condition (e.g., 'to place trades use ol_paper_trade', 'for the live portfolio use get_portfolio_positions'). Adequate but with a clear routing gap.

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

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

Annotations only declare readOnlyHint=false, so the description carries the rest and does so richly: dry-run default and its preview payload, idempotency replay semantics, that a rejection is a normal non-error response, a 20-fills-per-UTC-day cap, auth modes (API key/OAuth, cookie refused), and a disclaimer on every response. This is well beyond what the annotation provides.

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

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

The 'WRITE (opt-in)' prefix and dry-run rule are front-loaded, and nearly every clause carries operational information. It is a dense single block with many facts packed into one paragraph, which slightly hurts scannability but wastes little.

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 mutating tool with no output schema, it covers the return shapes (dry_run, replay, rejection), the execute flow, auth, rate limits, and the practice-money framing. 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 coverage is 100%, so the schema already documents all six parameters including enums, min/max, and defaults. The description largely restates shares range and buy/sell and adds only minor framing (thesis as the USER's reason), so the baseline 3 is appropriate.

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

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

States a specific verb (place a market order) and resource (paper/practice portfolio), and explicitly situates itself among siblings by naming reading_list_annotate as the only other mutating tool. An agent can tell exactly what this does and that it is not a real-money trade.

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

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

Gives an explicit usage flow: default dry run, re-call with _dry_run:false plus the same _idempotency_key to execute, and how to interpret rejections and replays. It also states the auth requirement and that browser-session callers are refused, so when-not conditions 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?

Goes well beyond readOnlyHint: discloses the continuation-vs-grant TRAP for non-empty patent_number, that ingest is on-demand rather than scheduled, that an unreachable store is REFUSED with DATA_UNAVAILABLE rather than served as count 0, and that caveats ride tool_notes. This is unusually rich behavioral disclosure.

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

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

Front-loaded with purpose and scope, and every sentence carries information (return shape, ordering, limits, caveats, attribution). It is dense and long, and the limit default/cap is stated redundantly with the schema, but there is little true 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 supplies the return shape ({summary, ticker, count, filings}), ordering (NEWEST FIRST), source and licensing, attribution boundaries, and error 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: `count` is the number RETURNED (not total available), `ticker` is an Oxford Ledge applicant-name resolution rather than a verbatim USPTO field. That clarifies the semantics of a schema field the schema itself does not explain.

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

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

States a specific verb+resource ('Recent USPTO patent filings for a ticker') plus the analyst use case (innovation-intensity diligence). No sibling tool covers patents, so it is naturally distinguishable from the 13F/BDC/insider cluster.

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 frames the usage context: a 'recent slice, never a full portfolio', sized by limit (default 50, cap 200), for diligence on innovation intensity. It does not name an alternative tool or an explicit when-not-to-use condition, 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?

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 declare readOnlyHint=true, so the description carries the behavioral load and does it well: units (millions USD, with a concrete 28,000,000 = $28 trillion example), the double-counting trap of component plus Total rows, the limit default/cap, the DATA_UNAVAILABLE refusal on an unreachable store, and where caveats live (tool_notes).

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

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

Dense but front-loaded: the primary no-arg behavior comes first, then the series pattern, then units, then gotchas and failure modes. Every sentence carries a distinct fact and none is filler.

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

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

There is no output schema, yet the description discloses the return envelope, the row composition caveat, units, pagination limits, and the failure mode, plus points to tool_notes for caveats. Nothing needed to call it correctly is missing.

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

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

Schema coverage is already 100%, but the description adds joint-parameter semantics the schema cannot express: the two security args must be supplied together or neither, a lone arg is silently ignored, and limit applies only to series requests. That is real meaning beyond the field-level 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?

The description names a specific dataset (US Treasury debt composition from the Monthly Statement of the Public Debt) and states the shape of what comes back ({summary, rows}), so the agent knows exactly what resource it is. It only gestures at sibling differentiation with 'Sibling of get_yield_curve' without saying when to prefer one over the other.

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

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

It gives explicit call patterns: omit BOTH args for the newest month's full class breakdown, pass security_type AND security_class together for a monthly series, and states that passing only one is IGNORED. That is a complete when/how matrix with no inference required.

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 real burden and delivers: dry-run default with the exact proposal shape, idempotency replay semantics ({replay: true} without double-write), auth failures (AUTH_REQUIRED on stdio), tier gating, API-key requirement, and the privacy guarantee that notes can never be published. This is well beyond what the annotation provides.

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

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

Front-loaded with 'WRITE (opt-in)' and the sibling comparison, then proceeds through dry-run, auth, constraints, and privacy with no filler. It is dense and slightly long, but every sentence conveys an actionable fact.

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

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

No output schema exists, yet the description documents both return shapes (proposal and replay) and notes that caveats ride tool_notes. Combined with the auth and constraint disclosures, 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 baseline is 3, but the description adds meaning the schema lacks: the replay behavior of _idempotency_key, the proposal/execute two-call flow for _dry_run, and the 'slug must already exist on /reading-list' precondition. The 500-char cap is merely restated from the schema.

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

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

Opens with 'WRITE (opt-in): save or update YOUR private note on an Oxford Ledge reading-list entry', a specific verb+resource+scope, and immediately distinguishes itself from its only sibling mutator (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?

Explicit when/when-not: it states the tool defaults to a dry run, tells the agent to re-call with _dry_run: false plus the same key to execute, and names ol_paper_trade as the other mutating tool. Preconditions (slug must exist, Researcher tier, authenticated caller) are all spelled out.

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

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

With only readOnlyHint available, the description carries real behavioral weight: ~45-60 day reporting lag, caveats surfaced in the response's tool_notes, the above-par trap (a mark >100 isn't a premium until fairValue is checked against cost), aggregates scoped to CURRENT holders, and the explicit miss shape {found: false}. These are substantive traits beyond the single 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 question the tool answers, followed by return fields and caveats. It is dense and clause-heavy, but nearly every clause is load-bearing (provenance, trap, miss semantics, pagination scope), so it stays efficient despite 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?

There is no output schema, so the description must enumerate returns, and it does: borrowerName, borrowerNorm, description, descriptionSource, industry, the four CURRENT-holder aggregates, and the per-TRANCHE holders rows. Combined with source lag and miss 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%, so the schema already documents query's 3-character minimum and limit/offset paging. The description restates these (query needs 3+ chars, limit/offset page holders only) without adding format or semantic detail the schema lacks, which is the baseline-3 case.

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 one private-credit borrower') and immediately pins down the data provenance (Oxford Ledge's parse of SEC EDGAR BDC schedules, not filer-published data). This scope is clearly distinct from sibling aggregations like ol_bdc_top_borrowers or ol_bdc_common_borrowers.

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

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

Usage is implied rather than explicit: the definition names borrowerNorm as 'the key the ol_bdc_* tools take', which sketches a downstream workflow, and warns that a miss is not evidence of no BDC exposure. However, it never says when to choose this over ol_borrower_profile or ol_bdc_common_borrowers, nor states 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?

Goes well beyond the readOnlyHint annotation: states no network call is made, gives a sub-millisecond latency, enumerates the exact return shape ({status:'retired', note, use_instead, query, issuers:[], totalBonds:0, error}) and warns that empty lists are the retired shape rather than a result. Also discloses the auth requirement (Oxford Ledge API key, anonymous refused) and the licensing reason. Consistent with readOnlyHint=true.

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

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

Exceptionally front-loaded — retirement status, then alternatives, then mechanics. Dense and slightly run-on when listing the return object, but nearly every clause carries information an agent needs (retired status, no-call guarantee, auth, alternatives) so 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, yet the description specifies the return object field-by-field, the auth model, the network behavior and the correct substitute tools. Nothing an agent needs in order to handle this retired 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 coverage is 100% and the single parameter is documented in the schema ('Issuer name to search (e.g. Apple, Goldman Sachs)'). The description only restates 'search by issuer name' and echoes query in the returned object, adding no syntax or format detail beyond the schema. 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?

Opens with 'RETIRED (2026-09-13)' and immediately states what the tool was — a bond search by issuer name over FINRA's TRACE host — plus why it now answers nothing. An agent cannot confuse it with any sibling after reading the first clause, and the name/verb relationship is fully explained.

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 the tool answers no query, names two concrete alternatives (ol_bond_directory_screen for corporate-bond discovery, get_debt_maturities for a single issuer's schedule) and the condition selecting each. This is a textbook when-not/use-instead directive.

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