DFX Real Estate Intelligence

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

Annotations only say read-only/non-destructive/idempotent. The description adds a large amount of valuable behavioral context: free keyless access, loan-level deduplication, ordering by maturity, confirmed maturity basis (19,821/19,821 from SEC/HUD filings), delivery-completeness reporting, and a principled treatment of defeasance codes (F, IP, X) and withheld loans. This far exceeds the annotation bar.

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

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

The paragraph is long, but each clause carries unique information such as authentication, dedup, data quality, completeness, and defeasance code interpretations. The access and 'loan rather than event' statement are front-loaded. It could be tightened slightly, but it is not bloated.

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

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

Because no output schema exists, the description compensates by enumerating all the return fields (maturity date, principals, rate, lender, instrument, origination date, address), ordering/scoping, completeness reporting, and defeasance edge cases. An agent has everything needed to call the tool correctly 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 the state, limit, and within_days parameters are already documented. The description echoes 'one state', 'one forward window', and 'up to 200 loans,' but does not add new semantic meaning beyond what the schema already provides. 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?

The description uses a specific verb ('Returns'), a well-defined resource ('LOAN'), and exact scoping ('one US state and one forward window'), while explicitly distinguishing itself from the event-level tools. The mention of maturity, principal, lender, and secured property makes the tool concrete. It clearly is not a generic search or event tool.

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

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

The description gives explicit context: it is for one-state, one-forward-window loan-level maturity data, is keyless/unauthenticated, and returns loans rather than events. It stops short of naming sibling tools or stating specific when-not-to-use conditions, but the core usage scenario is clearly inferable.

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

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

Annotations already cover read-only/idempotent/non-destructive, yet the description adds substantial behavior: entitlement gating (first 5 rows in full plus locked.count/locked.by_type), per-record truncation rules, and hard exclusions for contact values and decision-maker names. It even says where the withholding is reported (entitlement, locked), which an agent cannot infer from annotations.

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

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

Output list is front-loaded and dense, but the ALL-CAPS run-on enumeration plus the closing promotional sentence ('7 days free at https://...') bloat it. The access/withholding rules earn their place; the upsell and shouting do not.

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: sections, confidence label, and entitlement/locked withholding. Remaining gaps are minor, e.g. what a 'computed match' or confidence label actually looks like.

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 ID formats are already documented, but the description adds a genuine semantic fact the schema does not convey: the two IDs are order-independent ('either order'), which matters for a two-positional-ID tool. No further parameter nuance is added.

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 (explain a match between an investor and an opportunity) and enumerates the exact output sections: reasons, blockers, observations, comparable history, relationships, recent events, computed match, confidence. This is far more specific than the generic get_*/find_* siblings, and 'Facts, not a score' separates it from rank_* 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?

It tells the agent the expected input pairing ('an investor and an opportunity (either order)') but never states when to reach for this versus relationship_path, find_opportunities_for_capital, or get_capital_paths. Usage is implied by the input shape rather than stated.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds substantial non-obvious behavior: entitlement-gated truncation (first 5 rows plus locked.count/locked.by_type), per-record limits (first 3 related names), hard withholding of contact values and decision-maker names, basis labels on every row, and the entitlement/locked fields in the response. This is exactly the kind of context annotations cannot convey.

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

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

Purpose is front-loaded and the sentences are dense with real information about return shape and entitlement. The closing line ('Full access: DFX Intelligence, 7 days free at ...') is promotional filler rather than operational guidance, which slightly dilutes an otherwise tight block.

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 12-parameter, no-output-schema tool, the description does the heavy lifting: it explains the return shape (basis-labeled rows, entitlement and locked payloads) and the access constraints an agent must anticipate. It falls short only on the handful of unmentioned tuning parameters, which is a modest gap given the complexity covered.

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

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

With only 25% schema coverage the description must carry more of the load, and it does explain dfx_id (by describing the company-id mode), sector, state, deal size, stage, and control conceptually. However, it leaves limit, vertical, asset_class, check_size_usd, and sponsor_involved unexplained, so several parameters remain undocumented in both places.

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

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

States a specific verb+resource and enumerates the two input modes (a company dfx_id or a described opportunity via sector/state/deal size/stage/control). It also names the provider categories it returns (independent sponsors, family offices, venture firms, PE matcher rows), which separates it from siblings like find_pe_buyers_for_company and find_vc_investors.

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 conditions that select behavior ('venture firms when the opportunity is venture-shaped', 'DFX does not recommend first-time capital providers') and describes the access gating, but never explicitly routes the agent between this tool and near-neighbors such as find_lenders_for_financing, find_opportunities_for_capital, or find_pe_buyers_for_company. Usage is implied rather than stated.

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

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

Annotations only declare it a safe read; the description adds the scoring weights, refusal conditions (stale comparables, under-0.85 marks, passive holds under $2M), the lower-bound caveat on sizes, and a detailed access/entitlement model describing exactly what is withheld and what geo_coverage means. This is far beyond the annotation surface.

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 ranking behavior and criteria, then the refusal rules and access model. Dense but almost every clause carries information; the only drag is the promotional plan URL, though the entitlement explanation around it is genuinely useful.

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 9-parameter ranking tool with no output schema, the description explains what an answer contains, what it withholds, how coverage is reported (geo_coverage, entitlement, locked), and the ranking logic. 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 67%; the description adds real meaning beyond the schema by clarifying that sizes are BDC lower bounds never the commitment, that `states` only matches where DFX holds a headquarters, and how `industry` terms are matched against filer-written values.

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 (rank lenders) on a specific resource (comparable facilities currently held on BDC schedules) and enumerates the exact matching criteria. It is unmistakably distinct from siblings like search_private_credit or find_real_estate_lenders.

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

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

Explicitly routes the agent: gives a concrete example query ('$60M unitranche for a sponsor-backed healthcare services business') and says to use it before search_private_credit, explaining why the sibling differs. When-to-use and when-to-prefer-alternative are both 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description goes well beyond them: it details exactly what a free tier returns (first 5 rows, locked.count/locked.by_type), what is never returned (contact values, decision-maker names), and that withholding is surfaced via `entitlement` and `locked`. That is genuinely useful behavioral context an agent cannot get from the schema.

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

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

The content is a single sprawling, comma-heavy sentence followed by a dense access paragraph. The audience qualifier is front-loaded, but the matching logic is buried mid-sentence and the length is driven by entitlement boilerplate rather than tool-selection 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?

With no output schema, the description does carry return-value burden and explains the locked/entitlement envelope and 'returns the behaviour it reasoned from.' However, the actual match semantics (what counts as a match, how 'demonstrated behaviour' is derived) remain vague, leaving an agent without enough to predict results confidently.

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 only 50%: dfx_id is documented in the schema, but `limit` is not explained anywhere. The description's audience list loosely hints at the dfx_id entity types but adds no constraint, default, or interaction detail for either parameter, so it fails to compensate for the coverage gap.

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

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

It identifies an audience (family office, sponsor, capital provider, venture firm) and describes matching opportunities from 'demonstrated behaviour,' which gives a general sense of a recommendation/match tool. But the core verb+resource is buried in a run-on sentence, and it does nothing to distinguish itself from close siblings like search_opportunities, search_forward_opportunities, search_isi_opportunities, or search_vc_opportunities.

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 context (an investor wants matched opportunities) but gives no explicit when-to-use or when-not-to-use guidance and names no alternative among the many overlapping opportunity-search siblings. The only routing-like content is the access/entitlement explanation, which is about output, not selection.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description goes well beyond them with a detailed entitlement/paywall model: 5-row full lists with locked counts, per-record truncation to 3 related names, contact values and decision-maker names never returned, and the `entitlement`/`locked` disclosures. This is exactly the kind of behavioral context annotations cannot carry.

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

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

The purpose is front-loaded in the first clause, and each subsequent block (result fields, NOT_COVERED, ACCESS) earns its place. The dense access sentence is long but information-dense rather than padded.

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

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

With no output schema, the description fully carries the burden of describing return values, including the matcher fields, the entitlement/locked envelope, and truncation behavior. Nothing an agent needs to interpret or call 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 50%: dfx_id is documented in the schema, while `limit` is not. The description reinforces dfx_id's origin and format ('a dfx:pe: company id from search_pe_platforms') and hints at list-vs-record behavior, but adds nothing about the limit parameter or pagination. Baseline 3 is appropriate at this coverage level.

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

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

The description states a specific verb and resource ('Computed addon_for_platform matches for one platform') and enumerates the returned fields (reasons, blockers, why_now, comparable add-ons, owner, score, confidence, computed date), so the agent knows exactly what it produces. It also names search_pe_platforms as the source of the required id. It stops short of explicitly distinguishing itself from the reverse-direction siblings (find_pe_buyers_for_company, find_pe_companies_for_buyer).

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: call it with a dfx:pe id from search_pe_platforms to get add-on candidates. It clarifies the NOT_COVERED case ('not a statement that no add-on fits'), which prevents misreading an empty result. However, it never states when to prefer this over alternatives or any exclusions.

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

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

Annotations only declare read-only/idempotent safety. The description goes well beyond: it discloses free-plan truncation (first 5 rows, locked.count/locked.by_type), that contact values and decision-maker names are never returned, and that every answer self-reports withholding in `entitlement` and `locked`.

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, then the NOT_COVERED semantics, then access limits. Dense but every clause carries information, except the trailing promotional line about a free trial, which is sales copy rather than tool guidance.

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly (reasons, blockers, why_now, comparables, deal partner, score, confidence, model version, computed date). Entitlement behavior and the NOT_COVERED edge case are both covered, leaving no material gap for correct invocation.

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

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

Only dfx_id is documented in the schema, and the description merely restates its id prefixes without adding format or validation detail. The `limit` parameter (default 20, max 50) is undocumented in both the schema and the description, so the description fails to compensate for the 50% coverage gap.

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

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

States a specific verb+resource+scope: computed buyer_for_company matches from the PE matcher for a single company id, and enumerates what each row contains. It is clearly distinguishable from the inverse sibling find_pe_companies_for_buyer and from the broader find_capital_for_opportunity.

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 adjacent use cases elsewhere ('For sponsors, family offices and capital providers as well, use find_capital_for_opportunity') and explains the negative-result case (NOT_COVERED means DFX hasn't computed, never that no buyer exists), which prevents a serious misread.

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 readOnly/idempotent annotations: it explains the NOT_COVERED semantics (absence of scoring ≠ no fit), the free-tier truncation behavior (first 5 rows, locked.count/by_type), and the permanent withholding of contact values and decision-maker names, plus the entitlement/locked response fields. This is exactly the behavioral context annotations cannot convey.

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

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

Front-loaded with the core purpose and the important NOT_COVERED caveat, then the access rules. Dense but each clause carries real information; the trailing plan promotion and URL are the only slightly wasteful element.

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

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

With no output schema, the description carries the return-shape burden and does so: it lists the match fields returned and describes the entitlement/locked envelope for gated responses. 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 50%: dfx_id is documented in both schema and description (dfx:pe:<uuid> format), but the limit parameter is only defined by schema bounds/default. The description adds no syntax or format meaning beyond what the schema already carries, 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: computed company_for_buyer matches for one PE firm, enumerating the returned fields (reasons, blockers, why_now, comparables, score, confidence, date). The direction (firm → companies) is unambiguous, though it never names the reverse sibling find_pe_buyers_for_company to sharpen the distinction.

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 by the required dfx:pe: input and by the NOT_COVERED caveat, which tells the agent the empty-result case is meaningful. There is no explicit when-to-use-this-vs-an-alternative guidance, so the agent must infer routing from the tool name alone.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, but the description adds substantial uncovered behavior: the entitlement model (first 5 rows plus locked.count/locked.by_type, never full rows; contact values and decision-maker names withheld), the coverage boundary (conduit originators only; balance-sheet, debt funds, life companies absent), and how thin local markets fall back to national comparables.

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

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

Front-loaded with the purpose and routing guidance, and almost every clause carries operational value. It is dense and runs long (entitlement detail plus a trailing promotional plan link), which costs a point on tightness, but nothing essential is buried.

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

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

With no output schema, the description explains the row shape in detail (lender name normalised to parent, local/national counts and balances, latest origination, three example loans with property/city/trust/filing). Combined with access limits, coverage gaps and alternatives, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 89%, so the schema already does most of the work and the baseline is 3. The description adds the interpretation layer the schema does not: the ranking factors (property type, states/city, size band, recency and size fit) and the band-vs-comparable-size framing that gives meaning to band_min/max versus size_min/max.

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: lenders ranked on the commercial real estate loans they ORIGINATED, sourced from CMBS loan-level SEC ABS-EE filings. It explicitly distinguishes itself from the closest sibling (find_lenders_for_financing) and states its scope restriction to conduit originators.

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

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

Gives concrete when-to-use query examples ('find lenders for a $100M hotel in Atlanta'), an explicit exclusion ('use it, never find_lenders_for_financing, whose comparables are corporate BDC loans'), and a complementary sibling ('pair it with search_bank_cre_exposure for local banks'). When-not and alternatives are both covered with the reason why.

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 the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses the hard-vs-ranking constraint split, the exact/relaxed return model, the geography relaxation rule, and, unusually, the entitlement behavior (5 rows in full plus locked.count/locked.by_type, contact values never returned). That is exactly the behavioral context an agent needs to set expectations.

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 matching model and constraint taxonomy, then usage examples, then access rules. Dense and largely earning its length, though the trailing promotional sentence with the pricing URL is commercial noise rather than tool guidance.

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

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

No output schema exists, so the description carries the burden of explaining returns, and it does: match=exact vs match=relaxed rows, the named relaxed criterion, per-row venture fund lifecycle/vintage/state, and dfx:vc: identifiers. Combined with the entitlement/locked disclosure, 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?

With 75% schema coverage and 8 parameters, the description still adds real meaning: it enumerates which parameters are hard constraints (geography, sector, stage, amount_usd, active_only) versus ranking inputs, and clarifies geography semantics ('a city is its metro; Boston means the Boston area, the rest of Massachusetts is a relaxation') beyond the schema's terse field descriptions.

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

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

States a specific verb (find) and resource (VC investors) plus the exact scope: firms for a company raising a round, with hard constraints separated from ranking signals. It clearly distinguishes itself from the many search_vc_* siblings by describing the exact/relaxed matching model rather than a plain filtered search.

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

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

Gives concrete invocation examples ('find investors for my Series A', 'Series A fintech investors in Boston', 'investors for a $7M AI infrastructure round') that make the intended use obvious. It does not, however, name or exclude any sibling tool, so the agent must infer when to prefer this over search_vc_firms or search_vc_raise_candidates.

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 read-only and idempotent annotations, the description richly discloses access behavior: unentitled requests return only first 5 rows plus locked counts, records expose only first 3 related names per section, contact values and decision-maker names are withheld, and every answer reports withholding in entitlement and locked. It also clarifies data interpretation rules such as targets never being actuals and commitments repeating across reports.

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

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

The description is front-loaded with the core return profile for each entity type, followed by access constraints, so the most important content appears early. It is dense and runs long, but for a tool with this much varied output and entitlement behavior, most sentences carry relevant information rather than filler.

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

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

There is no output schema, so the description must carry the return-value burden, and it does so extensively across all four entity types. It also covers access tiers, withheld data, and what is reported in entitlement and locked, leaving no major contextual gap for an agent deciding whether and how to call 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?

The input schema has 100% description coverage for the single dfx_id parameter, including its format and source tools. The description adds no parameter-level syntax or usage detail beyond what the schema already provides, 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?

The description states exactly what the tool returns for each supported entity type: allocator card, Form 5500 plan filings, consultant details, and manager/fund backing. It names the resource and scope precisely, and references the sibling get_entity for same_as links, so an agent can distinguish it from search/list 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 makes clear that this tool returns a full record once a dfx_id is known, and it enumerates entity types it covers. However, it never says when to use this versus search_allocators, search_entities, or get_entity, nor does it provide explicit exclusions or alternatives. Usage is implied rather than guided.

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

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

Annotations already declare a safe read-only, idempotent, non-destructive operation, and the description adds substantial behavioral context beyond them: plan-gated access, first-5-row truncation, locked count/by_type behavior, withheld contact and decision-maker data, and entitlement/locked disclosure. It does not contradict any 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 long but front-loads the core retrieval scope and field list before access details. The access and entitlement sentences are dense but earn their place for a tool with real gating behavior; the promotional plan URL is the only slightly extraneous element.

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 covers the returned fields, paging behavior, default debt-only filtering, access restrictions, and withheld-data disclosure in entitlement/locked. For a complex, gated BDC portfolio tool, this gives an agent enough to invoke 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 only 50%, so the description must compensate. It adds useful meaning for as_of (latest quarter end), include_equity (debt only by default), and paging (25 rows), but it does not explain the sort parameter's meaning or the cursor beyond the schema's own description, leaving some gaps.

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

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

The description states a specific retrieval verb and resource: every position a BDC tagged at one quarter end, with the exact fields returned. It distinguishes this from sibling tools by centering on one BDC's schedule of investments rather than sponsors, borrowers, or search endpoints.

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 when to use the tool by describing its scope and default debt-only behavior, but it never names when to use it instead of alternatives such as search_private_credit or get_borrower_capital_structure. No explicit exclusions or routing guidance are provided.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, and the description adds substantial context on top: the fact-class taxonomy (filed/derived/carried/inferred), the semantics of 'lower bound' sums, mark-vs-impairment and moved-maturity-vs-amendment distinctions, where non-accrual data does and does not come from, and exactly what is withheld (contact values, decision-maker names) under entitlement/locked. This is unusually rich disclosure for a read tool.

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

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

The content is front-loaded with the returned sections before moving to fact classes and access rules, and nearly every sentence carries real information for an agent. It is still one dense paragraph, and the closing plan/pricing URL leans promotional rather than operational, keeping it short of a 5.

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

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

With no output schema and a complex, multi-section payload, the description carries the full burden and does so thoroughly: it enumerates every returned section, defines the fact-class provenance model, clarifies what signs do not mean (mark ≠ impairment, non-accrual not inferred from marks), and spells out entitlement/locked behavior and truncation limits. An agent has what it needs to interpret results correctly.

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

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

There is a single dfx_id parameter and schema description coverage is 100%, including the id format and the sibling tools that supply it, so the baseline is 3. The description adds no further detail about the parameter itself, relying entirely on the schema.

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

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

The description names a specific verb+resource and then enumerates exactly what comes back: the borrower group, facilities, BDC pieces, tape by quarter, sponsor attributions, and non-routine events. It distinguishes itself partially by noting search_credit_stress handles credit-stress roll-ups, but it never contrasts itself with the near-identically-named sibling get_borrower_facilities, leaving that boundary to inference.

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 — the tool is clearly the per-borrower detail view, and search_credit_stress is named for roll-ups, but there is no explicit 'use this when / not when' guidance. Access-tier behavior is well covered, which helps an agent know what it will actually get, but not when to prefer a sibling.

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

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

Annotations only cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description discloses a rich behavioral profile beyond them: the per-path payload contents, the sub-0.5 confidence labelling of candidate links, and an unusually detailed entitlement model (5 free rows, locked.count/by_type, contact values withheld, disclosure mirrored in `entitlement`/`locked`). This is exactly the kind of context the 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?

Densely front-loaded: purpose first, then path payload, then epistemics, then access. Nearly every clause is load-bearing given the tool's complexity, though the closing promotional line ('7 days free at ...') is sales copy rather than invocation guidance.

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

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

With no output schema and a fairly complex, multi-sectional return, the description carries the burden well by describing what each path contains, how confidence works, and what entitlement/locked will report. An agent can predict both the payload shape and its truncation behavior.

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 67% and the dfx_id enumeration is already fully documented in the schema itself. The description adds nothing about `kind` naming conventions or `limit` interaction with the lock behavior, so it neither compensates for the coverage gap nor repeats the schema usefully.

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: 'Published capital flow paths through one institution', then enumerates the three concrete shapes (allocator→manager, lender→borrower, properties under a RE manager). It is far more specific than a name restatement, but it never differentiates itself from the closest sibling, `relationship_path`, which also returns graph paths.

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

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

Gives strong interpretive guidance (NOT_COVERED means not computed, not 'no relationship'; paths built only from identity-grade or measured links), which implicitly frames when the result is trustworthy. However, it offers no explicit when-to-use versus `relationship_path` or the various `find_*` tools, and no stated prerequisites beyond the paywall note.

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

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

Annotations already declare a safe read (readOnlyHint, idempotentHint, non-destructive), and the description adds substantial behavior beyond them: the free-tier lock behavior (first 5 rows plus locked.count/locked.by_type), what is permanently withheld (contact values, decision-maker names), and the entitlement/locked self-reporting in every response. This is exactly the kind of context annotations cannot carry.

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

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

The core scoping is front-loaded, but the first sentence is an overlong run-on enumerating a dozen tape fields, and the closing marketing CTA about the 7-day free trial does not help an agent invoke the tool. Structure is workable but padded.

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

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

With no output schema, the description carries the burden and does well: it describes the access model, withholding rules, and entitlement/locked fields. It stops short of describing pagination or how multiple committed entities are ordered, but an agent has enough to call it correctly.

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

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

Schema coverage is only 33%, so the description must compensate. It does explain include_holdings well (holds that are performance-report lines, never approvals) and implies date/amount behavior for limit, but leaves the limit parameter's role and the accepted dfx_id prefixes largely to the schema. Partial compensation, so a baseline-adjacent 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?

The description states a specific verb+resource: it returns 'the commitment tapes' for any referenced id, and names the two tapes it unifies (allocator disclosure tape and real estate fund LP tape). The purpose is clear, but it never names or contrasts against obvious siblings such as search_allocator_commitments or search_vc_lp_commitments, so an agent cannot easily tell which commitment tool to pick.

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

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

It gives one concrete usage rule ('value-only holdings ... only with include_holdings') and clarifies the default (dated commitments with an amount). However there is no guidance on when to use this versus the many search_* commitment siblings, and no prerequisites for which ids qualify beyond the schema.

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

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

Annotations already declare a safe read-only, idempotent operation, but the description goes far beyond them: it discloses the access tier behavior (first 5 rows in full, rest locked by type, contact values and decision-maker names never returned), that every answer reports what was withheld in `entitlement` and `locked`, and the SUSB counting rule that multi-state firms count once per state.

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

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

The core purpose is front-loaded in the first sentence and the access caveats are grouped afterward, so an agent can extract the essentials quickly. It is dense and the trailing plans/promo URL is borderline noise, keeping 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?

With no output schema, the description carries the burden of describing the response and does so: firm counts by size band, DFX-held count, current-with-20+-participants count, coverage percentage, plus the entitlement/locked withholding structure. Nothing needed to call or interpret it is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema: it frames `naics` as a 2-to-6-digit code and `state` as either one state or the whole nation, and clarifies the multi-state counting semantics that the schema cannot express.

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: a Census SUSB firm count for one NAICS code and one state/nation, paired with the number of DFX-held companies and a coverage percentage. The concrete example ('how many HVAC contractors are there in Ohio and how many do you cover') makes the output unambiguous without opening the schema.

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

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

The example question and the 'count vs. list' framing clearly signal when to reach for this tool, and the access paragraph explains what you get back. It never explicitly contrasts itself with the sibling 'dfx_coverage' or other coverage tools, so the routing guidance stops short of full sibling differentiation.

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 readOnly/idempotent annotations, the description discloses a lot: entitlement gating on the vertical, the exact truncation rule (first 5 rows in full plus locked.count/locked.by_type for lists, first 3 related names for records), fields never returned (contact values, decision-maker names), and the entitlement/locked response fields that report withheld data.

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

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

Content is front-loaded — what the tool returns comes first, access/entitlement last — and every sentence carries information. The first sentence is a dense run-on listing many returned elements, which slightly hurts readability but does not waste space.

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

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

For a no-output-schema, single-param tool, the description covers returned contents, id provenance, and access restrictions thoroughly. It stops short of relating this tool to the closest sibling (get_borrower_facilities), leaving a small gap in routing context.

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 dfx_id parameter is already documented with its provenance in the schema. The description adds no format or validation detail beyond what the schema provides, 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 resource (one facility = one borrower group in one instrument class) and enumerates exactly what comes back: size, pricing, maturity, lender group, history, and changes at facility grain. It is clearly distinguishable from list-style siblings, though it never names a sibling directly (e.g. get_borrower_facilities) for contrast.

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 tells the agent where the required dfx_id comes from (get_borrower_capital_structure, search_credit_maturities, or an event), which is genuine usage guidance. However, there is no explicit when-to-use/when-not-to-use versus other facility or capital-structure tools, so usage remains largely implied.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behaviour beyond them: entitlement truncation rules for lists vs records, locked.count/by_type semantics, withheld contact values and decision-maker names, and the entitlement/locked response envelope.

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 contents, then the ACCESS block, so an agent can stop reading after sentence one. It is dense but a trailing pricing/promo URL is the one element that doesn't earn its place.

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

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

No output schema exists, so the description carries the return-shape burden and does so by enumerating profile, AUM/RAUM/13F, people, investments, relationships, events, evidence rows and cross-graph links, plus the entitlement/locked envelope.

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 description coverage, so the schema already documents the dfx id grammar fully. The description's "Accepts dfx:fo: ids" adds marginal value beyond the schema and doesn't explain error behaviour for wrong id types.

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

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

States a specific retrieval verb plus resource ("The full card for one family office") and enumerates the sections returned. It is clearly distinguishable from siblings like search_family_offices and rank_family_offices 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?

Implies the correct usage context: pass a dfx:fo: id to fetch a single record, versus list/search tools that return collections. It never explicitly names an alternative or a when-not-to-use condition, 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?

Despite annotations already declaring readOnlyHint, the description adds substantial behavioral context the annotations cannot: tiered access rules (first 5 rows plus a by-type count without a paid plan), what is never returned (contact values, decision-maker names), and the 'entitlement'/'locked' fields that disclose withholding. This is exactly the beyond-annotation disclosure the dimension asks for.

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

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

The purpose is front-loaded in the first clause, and the long field enumeration earns its place because there is no output schema. Sentences are dense and run long, and the entitlement/promotional tail ('7 days free at...') is the least essential part, but overall the content is proportionate.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so exhaustively—listing every metric per pattern and explaining the entitlement/locked withholding fields. For a 5-param, enum-rich read tool, 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 40% and two filter params (status, vertical) carry enum values. The description adds meaning by naming which fields are filterable ('vertical, status or signal key'), compensating partially for the undocumented limit parameter. It adds little beyond confirming the filters and gives no syntax for cursor or limit.

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

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

The description states a specific resource and scope: 'The ledger behind every forward claim,' followed by an enumeration of exactly what each record contains (definition, base rate, lift, lead time, q value, status). This distinguishes it from the opportunity-finding siblings and from search_signals. It stops short of naming a sibling to contrast against, so it is clear but not fully differentiated.

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 only operational guidance is 'Filter by vertical, status or signal key,' which describes parameters rather than when to choose this tool over search_forward_opportunities or search_signals. The note that rejected patterns are intentionally listed hints at a methodology-audit purpose but does not state when to reach for this versus the alternatives. No when-not or exclusion guidance 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 it is a safe, idempotent, closed-world read. The description goes far beyond that: it discloses entitlement truncation (first 5 rows + locked.count/locked.by_type, never the rows), that contact values and decision-maker names are suppressed to types and counts, and that every response carries `entitlement` and `locked` keys. This is exactly the behavioral context annotations cannot carry.

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

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

Purpose is front-loaded in the first clause and the entitlement caveat is separated cleanly. The dense, deeply nested parenthetical that enumerates each entity type's sections is heavy, but every clause carries real information rather than filler.

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

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

With no output schema, the description fully describes the return shape per entity type plus the relationship/event/evidence/cross-graph-link sections and the truncation metadata. An agent knows what it will receive and what will be withheld, leaving nothing essential unstated.

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

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

Schema description coverage is 100% and the schema already documents the full dfx id prefix vocabulary, so the description need not re-explain it. The description's 'Accepts dfx:isi: ids' adds only a scoping hint for this tool's graph, which is 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: 'the full card for any entity on the sponsor graph', then enumerates the three subjects (sponsor, capital provider, private company) and the sections each returns. An agent can distinguish this detail lookup from list/search siblings like search_independent_sponsors 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 'Accepts dfx:isi: ids' note and the title imply this is the point-lookup companion to search_independent_sponsors, so usage is inferable. However, no explicit when-to-use, when-not-to-use, or named alternative is given; the ACCESS block is about plan entitlements, not tool selection.

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 annotations (readOnly/idempotent/openWorld=false) by disclosing the critical epistemic caveat that 'not_observed IS NOT VACANT', that rows carry evidence tier and freshness, and that the tool is free. These are the exact behavioral traits an agent needs to avoid misinterpreting an empty result.

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

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

Front-loads the two-direction mental model, then the per-direction returns, then the one-claim check, then the caveat. Dense but every sentence carries load, including the one-word 'Free.' cost 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?

No output schema exists, and the description compensates by enumerating the returned fields (tenant name, dfx_id, occupancy class, leased area, share, lease expiration) plus evidence tier and freshness. With annotations covering safety, nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: direction is inferred from the object rather than a flag, address and company must be used together, and a company name alone is refused. It adds actionable semantics beyond the schema text.

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

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

States a precise verb+resource pattern ('Two directions from one call') and enumerates exactly what each direction returns (tenant name, dfx_id, occupancy class, leased area, share, lease expiration). An agent can distinguish this from get_property_record or resolve_address 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?

Clearly states when to use each mode: dfx_id for a property's tenants or a company's locations, and `company`+`address` for a single one-claim check ('company name alone is refused'). It gives strong in-tool routing but never names a sibling tool as the alternative when a different question is asked (e.g. get_property_record).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses the entitlement gating model (first 5 rows in full plus locked.count/locked.by_type, record names subject and 3 related names per section), that contact values and decision-maker names are suppressed to types and counts, and that entitlement/locked fields report what was withheld. This is exactly the kind of paywall, redaction, and return-shape behavior 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?

The content is largely substantive, but it is packed into one enormous run-on sentence that is not front-loaded: the reader must reach the middle to learn what the card actually contains. The enumeration is dense and could be grouped or bulleted, so structure is a clear weakness even though little is truly wasted.

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

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

There is no output schema, so the description must carry the return-value burden, and it does so exhaustively: it lists every section returned, the entitlement behavior, the locked/withheld reporting, and the cross-graph same_as links. For a complex, high-fanout entity tool, nothing an agent needs to call it correctly appears to be 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 well documented, so the baseline is 3. The description adds value by specifying that the id is polymorphic (person, fund, or company) and that the returned card matches that subject, which is meaning beyond the schema's simpler 'private equity graph id' phrasing.

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 the full card for a private equity firm) and enumerates the exact contents: identity, classification, funds, team, portfolio, counterparties, scores, events, and same_as links. It also carves out a distinct scope from siblings by naming the family office, sponsor, and venture graphs it links to, so an agent can tell it apart from get_family_office, get_pe_fund, or search_pe_firms.

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 notes it also accepts a dfx:pe person, fund, or company id, which is a partial usage hint, and implies it is the single-entity counterpart to the search_ tools. But it never states when to use this versus search_pe_firms, get_pe_fund, or get_sponsor_portfolio, nor any prerequisites for choosing it. Usage is 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 already cover the read-only/idempotent safety profile, and the description adds a great deal beyond them: entitlement gating behavior (list returns first 5 rows plus locked.count/locked.by_type, never full rows), record-level truncation to 3 related names per section, hard exclusions (contact values and decision-maker names never returned, only types/counts), and that every response reports what was withheld via `entitlement` and `locked`. That is exactly the kind of non-obvious behavior an agent must know before calling.

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

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

Purpose is front-loaded, which is good, but the description is a dense run-on sentence stuffed with parentheticals, followed by a long ACCESS block that is part behavioral disclosure and part promotional copy ending in a pricing URL ('7 days free at https://dfxintel.com/data-factory/plans'). The entitlement explanation earns its place; the sales pitch does not.

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 has to describe return shape, and it does reasonably well (list vs. record behavior, locked counts, per-section name truncation, entitlement metadata). It stops short of describing the exact field set or grain of the reporting tape, but an agent can call it correctly.

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

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

Schema coverage is 100% and the single dfx_id parameter is fully specified in the schema (format dfx:pe:<uuid> plus the search tools that produce it). The description adds no further syntax or format detail beyond that, 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 and resource (retrieve one PE fund) and enumerates the payload: manager, vintage and basis, per-amount bases, Form ADV reporting tape, LP commitments, relationships, events and evidence. It explicitly distinguishes itself from the sibling get_pe_firm ('use get_pe_firm for the manager') and from the search tools by declaring it 'refuses an id that is not a fund'.

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 routing guidance: use get_pe_firm for the manager, and the id must be a real fund id (reinforced by the schema's note that ids come from search_pe_firms/search_pe_funds). It does not, however, state when to prefer a search_* tool over this one or what to do on a refused id.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuine domain behavior beyond that: sales carry BOTH the instrument total and this parcel's allocated share, and it explains why (a deed repeats its full price on every parcel it covers), which warns the agent against double-counting. It does not describe output shape or failure behavior for an invalid id.

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

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

Purpose and payload are front-loaded, and the parcel-lookup clarification is emphasized where it matters. It is slightly padded — the standalone 'Free.' fragment and repeated restatement of the property/parcel duality both in the description and schema — but no sentence is truly wasted.

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

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

With no output schema, the description carries the burden of describing returns and does so well by enumerating every result category. The one-parameter, read-only shape is fully covered; only edge cases such as an unrecognized id are left unaddressed.

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

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

Schema coverage is 100% and the parameter description already spells out both accepted forms and the property-or-parcel duality, so the tool description largely restates it ('both come back in full'). Baseline 3 is appropriate when the schema does the heavy lifting; the description adds little new parameter-level meaning.

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

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

States a specific input (a DFX id) and enumerates the concrete payload: current state, dated events, ownership/management relationships, debt with maturity dates, recorded sales with consideration and registry book/page, plus provenance. It also explicitly resolves ambiguity against sibling tools by declaring 'THIS IS ALSO THE PARCEL LOOKUP', which separates it from search_parcels and search_property_events.

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 for use — fetch by id after obtaining a dfx_id from an address resolution object or a parcel search row — and notes the call is free, which matters for selection. It stops short of explicitly naming the alternatives (search_parcels, resolve_address, search_property_events) or stating when not to use it, leaving some 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?

Far beyond the readOnly/idempotent annotations, it discloses the entitlement model in detail (5-row lists with locked.count/by_type, records naming only subject plus 3 related names per section, contact values and decision-maker names never returned), the GAV definition and its exclusions, the quarantined-reading rule, and the 2011-onward tape with coverage_live. This is exactly the extra context annotations cannot carry.

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

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

The first ~90 words are a single run-on sentence listing a dozen returned sections, so it is not front-loaded with purpose and is hard to scan. Most content does earn its place given the breadth of the payload and the access caveats, but the structure is weak rather than concise.

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

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

With no output schema and a single documented parameter, the description carries the full burden and does so: it describes every returned section, the identifier forms, data-coverage limits, and the entitlement/locked contract for every answer. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and the single dfx_id parameter is already documented as a dfx:ref uuid or CRD string, so the description's restatement ('Accepts a dfx:ref: id or the manager's CRD') adds nothing new. 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?

The name and title establish this as a single-resource fetch for one real estate fund manager, and the description enumerates exactly what comes back (card, ten largest vehicles, family by vintage, bindings, lenders, maturities, Schedule A people, cross-graph records). It is distinguishable from the sibling search_re_fund_managers by being 'one ... in full', though the description never states that contrast explicitly.

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

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

Usage is implied rather than stated: the exhaustive content list implies 'call this when you have an identifier and want everything about one manager'. There is no explicit when-to-use/when-not, and no sibling (search_re_fund_managers, get_re_fund_vehicle, get_re_fund_trends) is named as an alternative. The coverage notes (2011 ADV tape, only a few hundred managers with passing bindings) do give useful interpretive 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 already cover the safe-read profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond that: feeders and quarantined readings are excluded from GAV, the tape starts in 2011 with a partial current year, output is explicitly non-predictive, and the free-tier withholding rules (first 5 rows, count-only, contact values never returned, entitlement/locked reporting) are spelled out.

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

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

It is dense and front-loads the series enumeration before the access caveats, so an agent gets the core purpose immediately. The entitlement/plan promotion at the end is somewhat long but is materially relevant to what data comes back.

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

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

With no output schema and only 3 params, the description carries the return-shape burden well by explaining exclusions, date coverage, and locked/entitlement behavior. It does not explain the row/count semantics of limit or ordering of top_managers, 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 only 33%, but the description compensates by describing each view value in prose that maps to the enum (vehicles_by_year, managers_by_year, gav_by_year, vintages_by_year, drops_by_year, top_managers), and min_gav_usd is documented in the schema. The limit parameter (1-60) is not explained, keeping it short of a 5.

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

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

The description names a specific resource (derived real estate fund series by year) and enumerates the exact series produced: vehicles by year, first-time managers, GAV by year, vintages, drops, and top managers. This is clearly distinct from sibling record tools like get_re_fund_manager or get_re_fund_vehicle.

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 the tool is for aggregate/trend views rather than individual records, and the enumerated series make that use case inferable. However, it never states when to pick this over get_re_fund_manager, search_re_fund_vehicles, or the other RE fund siblings, and gives no explicit exclusions or prerequisites for selection.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context beyond them: the gap-in-history semantics, the definition of gross asset value, the 2011 start of the ADV tape and quarantine rule, and the entitlement/locked withholding behavior. This is exactly the kind of behavioral detail annotations cannot express.

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

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

The return content is front-loaded and most sentences carry real data semantics. However, the passage is very long and ends with promotional plan/pricing text ('7 days free at https://dfxintel.com/data-factory/plans') that does not help an agent invoke the tool correctly.

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

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

With no output schema, the description must carry the burden of describing return values, and it does so thoroughly: section contents, coverage caveats, quarantined readings, and the locked/entitlement withholding model. Nothing an agent needs to call this tool and interpret its output appears missing.

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

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

Schema description coverage is 100% and the single parameter's accepted id formats are already documented in the schema. The description restates the same formats without adding syntax, validation, or format-specific behavior, 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 and resource ('the vehicle card with its reporting history year by year as filed') and enumerates the sections returned (owners, family, commitments, holdings, events). The phrase 'in full' for a single vehicle clearly separates it from the sibling search_re_fund_vehicles, which lists many.

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 tells the agent which identifier formats are accepted (dfx:ref, 805- ADV fund id, 021- Form D number), which is useful routing context. But it never states when to reach for this tool versus search_re_fund_vehicles, get_re_fund_manager, or get_re_fund_trends, leaving the selection to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavioral context: freemium returns first 5 rows plus locked.count/locked.by_type counts, records name subject and 3 related names per section, contact values and decision-maker names are never returned, and every answer reports withholding in `entitlement` and `locked`.

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: return fields first, then limitations, then ID formats, then access tiers. Nearly every sentence carries information an agent needs, though the trailing promotional sentence with the free-trial URL is marketing rather than functional content.

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

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

With no output schema, the description fully carries the burden of describing the return shape, the withheld fields, and the entitlement-dependent result structure. Nothing material to calling or interpreting the tool is left unexplained.

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

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

Schema description coverage is 100% and the single dfx_id parameter is fully documented in the schema itself (uuid or CRD string). The description restates the same dual-acceptance rule without adding format, validation, or edge-case detail, so the schema does the work — 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?

The description states a specific verb and resource ('One IAPD-registered advisor') and enumerates the exact fields returned — name, current firm with class/tenure, dated employment spans, firm changes, teams, exams, designations, industry start, events. This is clearly distinct from get_ria_firm and get_ria_practice, though it never names those siblings explicitly to route the agent.

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

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

It tells the agent how to call it (dfx:ria: id or CRD number) and extensively covers what happens at each entitlement tier, but gives no when-to-use guidance versus resolve_ria_advisor, search_ria, or get_ria_practice. Usage context is implied by the field list rather than stated.

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

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

Goes well beyond the readOnly/idempotent/no-side-effect annotations by disclosing that free-tier calls return only the first 5 rows plus locked.count/locked.by_type, that a record shows its subject and the first 3 related names, that contact values and decision-maker names are never returned, and that precision by basis is unsampled while a name is never a basis. This is exactly the kind of entitlement and edge-case context an agent cannot get 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?

The purpose and the routing question are front-loaded before the access caveats, and most sentences carry real information. It is dense and run-on in places, and the trailing promotional plan link is less essential, keeping it short of a 5.

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

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

For a complex tool with no output schema, the description covers the return shape (links with their printed basis), the identifier substrates, and the full entitlement/locking story. The only real gap is the limit parameter's semantics, which is minor against the otherwise thorough behavioral disclosure.

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 50%; the dfx_id schema already documents the dfx:ria:<uuid> and CRD forms the description repeats, adding little. The limit parameter is undocumented in both schema and description, though 'the 200 largest funds are checked' loosely hints at its ceiling. Baseline 3 for a half-covered schema.

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

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

States a specific verb and resource: it returns every link from an RIA firm (or one private fund) to the PE, VC, family office and sponsor graphs written on a shared identifier, and even names the question it answers. The scope is unusually precise, but it never explicitly names a sibling tool it should be chosen 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?

'Answers which PE or VC graph entities hold vehicles this wealth manager advises' implies a use case, and the accepted identifier forms (dfx:ria: firm or fund id, or a firm CRD) imply when the tool applies. There is no explicit when-not guidance or pointer to an alternative such as get_capital_paths or get_ria_firm.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds substantial context beyond them: entitlement gating (first 5 rows, locked.count/locked.by_type, withheld contact values), data provenance classes (reported/fact_from_registration/derived), RAUM affiliate double counting, and survivor bias before 2026-09-15. These are genuinely useful caveats, though the framing is marketing-tinged.

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 content is dense and mostly earns its place, but it is delivered as one undifferentiated paragraph, and the closing sales pitch ('7 days free at https://dfxintel.com/...') is promotional rather than functional. A sectioned layout would serve the reader better.

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 returned sections, explains pagination/entitlement behavior and locked structures, defines fact classes, and notes data-quality caveats. An agent knows what it will get and what may be withheld.

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's id format (dfx:ria:<uuid> or CRD) is already documented in the schema. The description repeats the same id acceptance without adding syntax or resolution behavior, so it meets the baseline but does not exceed it.

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

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

States a specific verb+resource (get one RIA firm's full card) and enumerates the exact sections returned: people flows, growth, offices, owners, affiliates, funds, teams, events, same_as links. That enumeration distinguishes it from siblings like get_ria_advisor, get_ria_practice and get_ria_trends 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?

It specifies accepted identifiers ('dfx:ria: ids or a CRD') and implies this is the full-record counterpart to list/search tools, but it never states when to choose this over get_ria_advisor or search_ria, nor any exclusion conditions. Usage is inferable 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?

With annotations already declaring readOnly/idempotent/non-destructive, the description goes far beyond them: it discloses entitlement gating (first 5 rows in full plus locked.count/locked.by_type on the free tier), that contact values and decision-maker names are withheld and only typed/counted, and that every response reports its own withheld data via `entitlement` and `locked`.

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 two usage modes, then return shape, then access limits and the upsell line. Dense but each clause carries information; the trailing plans URL is slightly promotional but short.

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 explain returns, and it does thoroughly: entry types, dimensions, dated change kinds, disclosure_status semantics, registry fields, and entitlement-truncation 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% and the schema already defines both parameter formats, so the baseline would be 3. The description adds value by tying each parameter to a distinct result shape (advisor record vs company record) and by enumerating the disclosure_status values, clarifying what an agent gets from each identifier.

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 and explicitly separates two modes: an advisor (dfx:ria id or CRD) returns reviewed outside-business entries, measured dimensions and dated changes, while a company_id returns the company, registry status and its disclosing advisors. An agent can distinguish this from sibling lookups like search_ria_outside_business 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 maps each input to a distinct use case and points to search_ria_outside_business as the source of a company_id, giving clear context for which identifier to supply. It does not state explicit when-not conditions or name a directly competing tool, 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?

Goes well beyond the readOnly/idempotent annotations: it discloses the entitlement model (first 5 rows plus counts when unentitled, only first 3 related names per section, contact values never returned), that anomalies are leads not conclusions with data-quality rows separated, and that book size/revenue are marked UNKNOWN and never estimated. These are exactly the behavioral traits an agent needs before relying on results.

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 content is front-loaded but delivered as one enormous sentence with nested parenthetical inventories, and much of it is an item-by-item catalogue rather than decision-relevant guidance. It is information-dense yet hard to scan, so it is only moderately well structured.

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 return-value disclosure and does so thoroughly: section-by-section contents, the entitlement/locked reporting contract, and the UNKNOWN policy. For a single-parameter read tool with annotations covering safety, nothing an agent needs to call and interpret it is missing.

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

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

Schema description coverage is 100% for the single dfx_id parameter, and the schema already documents the dfx:ria:<uuid> or CRD forms. The description repeats the accepted identifier types without adding format, validation or fallback semantics, so the baseline 3 applies.

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

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

The description states a specific resource and enumerates its contents precisely (Form ADV fields, derived metrics, archetypes, anomalies, retention, contact path) and names the accepted identifiers. It is clear what the tool returns for one practice, but it never distinguishes itself from close siblings like get_ria_firm, get_ria_advisor or search_ria_practices, leaving the agent to infer the boundary.

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

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

Usage is only implied by the content inventory and the note that it accepts a dfx:ria: id or CRD; there is no explicit 'use this when you need X, use Y otherwise' guidance and no alternatives named. The access-tier paragraph explains what happens on a free plan, which is helpful context, but it is not selection 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 read-only/idempotent/non-destructive. The description goes far beyond that: it explains entitlement gating (first 5 rows plus locked.count/locked.by_type without a paid plan), that contact values and decision-maker names are never returned, that counts exclude bulk re-registrations, and that RAUM sums double-count affiliates. This is exactly the behavioral context an agent needs.

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

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

Front-loads the three view definitions, then layers the access/entitlement constraints. Dense but every sentence carries information an agent needs; the access and caveat clauses could be tightened slightly 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?

With no output schema, the description must describe returns, and it does: per-view contents, the entitlement/locked response shape, and the aggregate caveats. An agent has enough to call the tool and interpret results correctly.

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

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

Schema description coverage is only 13%, so the description must carry the load, and it substantially does: it maps the view enum, describes sort dimensions for flows/growth, and notes state, class and size filters. It leaves limit bounds and a few sort values (cagr_3y, employees, net_gain/net_loss) implicit, so it compensates well but not completely.

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 (derived views over the RIA lane's aggregates) and enumerates exactly what each of the three views — state_stats, flows, growth — contains, matching the view enum. An agent can tell this aggregate/trend tool apart from entity-level siblings like get_ria_firm or search_ria without opening the schema.

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

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

The description clarifies what each view returns, which implicitly guides the view choice, but it never says when to use this tool versus the many sibling lookups (get_ria_firm, search_ria, rank_*). No when-not conditions or explicit alternative routing are provided, so selection is left to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond them: exactly what an unentitled caller sees (first 5 rows in full plus locked.count/locked.by_type, never the rows), how much of a record is exposed (subject plus first 3 related names per section), that contact values and decision-maker names are never returned, and that withheld material is reported in `entitlement` and `locked`. This is unusually thorough disclosure of a non-obvious access model.

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 resource identity is front-loaded, which is good, but the body is a single sprawling colon-delimited enumeration followed by a long ACCESS block and a promotional line with a signup URL. The content is useful, yet the wall-of-text form makes the key facts harder to scan than they need to be.

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

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

With no output schema, the description carries the return-shape burden and does so: it lists each section returned, the entitlement-truncation behavior, and the fields that are always suppressed. For a two-parameter lookup tool, nothing an agent needs in order 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 the baseline is 3, and the description adds provenance the schema lacks: the dfx_id is a dfx:isi:<uuid> sourced from rank_service_providers, and `name` is the fallback when no id is at hand. It does not say whether name is fuzzy-matched or what happens on ambiguity, so it is slightly above baseline rather than fully 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?

The description names a specific resource (a law firm, bank, accounting or diligence firm as seen through the independent sponsor graph) and enumerates exactly what the record contains: deal counts, role mix, served sponsors, capital providers, named professionals, engagements, and dated signals. An agent can distinguish this from rank_service_providers (a ranked list) and search_service_provider_sponsors without opening the schema.

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

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

It tells the agent where the identifier comes from ('Give the dfx:isi: id from rank_service_providers or a name'), which is real routing guidance to a sibling tool. It does not state when to prefer this over search_service_provider_sponsors or what to do if multiple providers match a name, so it stops short of full when/when-not coverage.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive, closed-world), while the description adds substantial behavioral detail: the basis-resolution via origin_record, that a pair inherits its weakest basis, the deal_party vs BDC-schedule distinction, and the exact free-tier truncation behavior (5 locked rows, count-only answers, withheld contact/decision-maker values surfaced in entitlement/locked). This is well beyond what the structured fields convey.

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

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

The content mostly earns its place, but it is delivered as one dense run-on paragraph that mingles returned fields, input resolution, and access rules without clear structure. Front-loading is reasonable, though a bulleted separation would be more scannable.

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

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

There is no output schema, so describing the returned metrics and the entitlement/locked structure is essential and mostly delivered. Combined with the read-only annotations, the definition is close to complete, with the main gap being the undocumented sort/limit/min_borrowers parameters.

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

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

Schema description coverage is 25% (only dfx_id documented), so the description has to compensate. It does clarify dfx_id's accepted id forms and the resolution path, but says nothing about sort, limit, or min_borrowers, leaving three parameters undocumented except by their enum/defaults.

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 (sponsor-by-lender pairs with borrowers, facilities, principal held and related stats), and the title reinforces what it returns, so an agent can tell it produces a ranked lender list for a sponsor. It never names the near-identical sibling search_sponsor_lender, so differentiation from alternatives must be inferred.

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 explains input id forms and entitlement behavior but gives no when-to-use guidance, no exclusions, and no routing to siblings like search_sponsor_lender or get_sponsor_portfolio. An agent gets no help deciding when this tool is the right call versus alternatives.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond them: the entitlement-gated response shape (first 5 rows in full plus locked.count/locked.by_type), the guarantee that contact values and decision-maker names are never returned, and that every answer reports what it withheld via `entitlement` and `locked`.

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 field list and fingerprint lead, then usage, then access rules. Every sentence carries information, though the closing plan promotion is promotional filler rather than tool-relevant guidance.

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 the return payload (holdings, sector/state/control counts, current totals) and the gating. Combined with rich annotations, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is only 50%, so the description must carry weight, and it does for the two key inputs: it specifies the dfx id forms (dfx:pe:/dfx:isi:) and the identity-layer linkage, and the name alternative. The status and limit parameters are covered only implicitly by '(current and exited)', leaving the enum and cap undocumented in prose.

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

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

States a precise verb and resource (a sponsor's current and exited portfolio holdings), enumerates the returned fields, and names the specific scenario it answers ('which companies fit this sponsor's strategy'). It is clearly distinguishable from siblings like get_pe_firm or search_sponsor_deals.

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

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

Explicitly frames itself as 'the first read' and prescribes ordering ('read what it owns before searching for lookalikes'). This gives clear context for when to reach for it. It stops short of naming the specific alternative sibling tools to use afterward, so it is not a full 5.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses free-tier truncation (first 5 rows, locked.count/locked.by_type), that contact values and decision-maker names are withheld as types/counts only, and that every answer reports what it withheld in `entitlement` and `locked`. This is unusually rich behavioral disclosure for a read tool.

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

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

The return-content inventory is front-loaded and informative, but the entitlement paragraph is repetitive ('never the rows', 'are never returned') and the closing marketing line with a plans URL is promotional filler for a tool-selection document.

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

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

With no output schema, the description carries the full burden of describing returns, and it does so comprehensively: per-entity-type contents, related relationships/events/evidence/cross-graph links, plus truncation and withholding semantics. An agent knows what it will and will not get back.

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 a single required parameter, so the schema already documents the id format thoroughly. The description's 'Accepts dfx:vc: ids' adds nothing and is actually narrower than the schema, which accepts fo/isi/vc/pe/ria/al/pc/ref ids and bare UUIDs.

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 concrete verb+resource ('the full card for any entity on the venture graph') and enumerates what each entity type returns (firm with investments/co-investors/funds, person with board seats, fund amounts, portfolio company investors). It does not, however, distinguish itself from sibling getters like get_pe_firm, get_family_office, get_ria_firm or get_entity, which appear to do the analogous thing for other graphs.

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 explains access/entitlement tiers at length but never says when to choose this over a sibling such as search_vc_firms, get_entity, or find_vc_investors, nor what prerequisite (a dfx:vc id obtained elsewhere) is required. Usage is only inferable from 'Accepts dfx:vc: ids'.

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

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

Annotations already declare read-only, idempotent, non-destructive, but the description adds substantial behavioral context beyond them: entitlement/locked gating (5-row lists, names/counts only, contact values never returned), the reasons/failed/gaps output structure, and the default 'family capital only' scope. This is exactly the extra disclosure annotations cannot carry.

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

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

Front-loaded with the core purpose and mostly dense with signal; the filter semantics and access rules each earn their sentence. The trailing sales line ('Full access: DFX Intelligence, 7 days free at...') is promotional filler that does not help an agent invoke the tool correctly.

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 highly complex 35-param tool with no output schema, the description supplies the missing return-value contract (reasons/failed/gaps, envelope coverage counts, entitlement/locked) and the filter model. An agent has what it needs to call it and interpret results without a schema.

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

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

With 35 params at 54% schema coverage, the description compensates well conceptually: it explains require as hard filters, prefer as making geography soft, geography/class as default hard filters, and gives canonical industry codes. It still leaves a number of individual params (contact_tier, min_identity_confidence, counterparty_min) unexplained in prose, so it does not fully close the coverage gap.

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

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

Opens with a specific verb+resource claim ('THE tool for any family office question with criteria') and enumerates the criteria dimensions it ranks on. It is clearly distinguishable from siblings like search_family_offices and get_family_office, which fetch rather than rank against a buyer's weighted criteria.

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?

States the selection condition clearly ('any family office question with criteria') and defines the hard-vs-soft filter model plus the role of require and prefer. It does not explicitly name the alternative sibling tools (search_family_offices, explain_match) or state when NOT to use it, so it falls short of the full when/when-not/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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is free. The description goes well beyond that by disclosing the entitlement gating: unentitled lists return only 5 rows plus locked.count/locked.by_type, records expose only the first 3 related names per section, and contact values and decision-maker names are never returned. It does not describe pagination semantics for cursor beyond the schema, but the access disclosure is unusually rich.

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

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

Front-loads the resource and the row contents, then the trigger questions, then the exclusion and access terms. It is long, but nearly every clause carries load; the trailing plans/URL marketing sentence is the only 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 carries the full burden of explaining the return shape, and it does: it enumerates every row field (deal counts, sponsor-side counts, repeat sponsors, 6/12-month activity, first/last deal, verticals, states, role mix, top sponsor). It also documents the entitlement/locked response contract, which an agent needs to interpret results correctly.

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

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

Schema description coverage is 80%, so most parameters (sort, cursor, active_since, sponsor_focused_only, vertical, state) are already documented in the schema. The description's family glosses ('legal = law firms', 'qoe = quality of earnings') largely restate the enum descriptions, so it adds little meaning beyond what the schema provides. 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 (rank) and resource (service providers on independent sponsor transactions) and enumerates the exact families covered, mapping each to its internal enum value. It explicitly distinguishes itself from rank_sponsor_capital, so an agent can separate it from its nearest sibling without reading 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 concrete trigger questions ('top 10 law firms by independent sponsor deal count', 'which QoE providers work with independent sponsors') and an explicit exclusion with the correct alternative ('Not for capital providers or lenders: use rank_sponsor_capital'). Both when-to-use and when-not-to-use 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?

Beyond the readOnly/idempotent annotations, the description discloses a lot an agent would otherwise have to discover: entitlement truncation rules (first 5 rows plus locked.count/locked.by_type), permanent withholding of contact values and decision-maker names, EBITDA sizing confidence (0.45-0.55) and the fact no deal states EBITDA, DEAL_NOT_FOUND fallback behavior with no guessed sector, and the dfx:isi: return-id convention.

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 prose is dense and long, but it is front-loaded by group mode and every sentence carries a distinct rule (mode behavior, filter semantics, access limits, error handling). The trailing plans URL is the only clearly promotional, non-functional sentence.

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

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

For a 13-parameter, output-schema-less tool with no required params, the description covers the three result shapes, the comparable-deal path, filter semantics, error mode, return identifiers, and access/entitlement behavior. An agent could invoke it correctly and interpret the locked/entitlement fields 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 description coverage is 54% across 13 params, and the description compensates substantially: it maps group enum values to their behaviors, explains min_deals is pair-only with default 2, defines what role_class=debt and equity include, clarifies that the EBITDA filters bind to the target's estimated band, and gives deal_sponsor/deal_company matching semantics. It leaves state, vertical, sponsor_dfx_id and provider_dfx_id to the schema, so it is not exhaustive.

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 precise verb+resource (rank the capital parties named on announced independent sponsor deals, aggregated) and then enumerates the three output shapes (group=provider, group=pair, group=deal) plus the deals-like-one-deal variant. An agent can see exactly what this tool returns and how it differs from sibling search/get tools without opening the schema.

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

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

It gives explicit when-to-use examples: 'which capital providers are most active in independent sponsor deals', 'who lends to IS deals of $10M to $50M EBITDA', and 'which sponsors and lenders work together repeatedly', and it dictates when to pass deal_sponsor/deal_company. It does not explicitly name the sibling tools to use instead (e.g. search_sponsor_capital_providers or get_sponsor_lenders), so routing is strong but not fully disambiguated.

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

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

Annotations already cover the safe/idempotent read profile, yet the description adds substantial behavioral context: results are truncated by entitlement, lists return only first 5 rows plus locked.count/locked.by_type, records cap related names at 3 per section, and contact values/decision-maker names are never returned. It also names the fields that disclose what was withheld (entitlement, locked).

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 hop/no-match semantics are well front-loaded, but the ACCESS paragraph is long and blends genuine withholding disclosure with a commercial upsell ('7 days free at https://...'), which does not help an agent decide or call the tool. It is informative but not tight.

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 by describing return structure (entitlement, locked, locked.count, locked.by_type) and result limits. Combined with the id-format detail in the schema, an agent has enough to call it correctly; only finer details like pagination or full field list are absent.

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 67%, with the two dfx_id parameters heavily documented in the schema itself (all graph prefixes and bare UUID). The description adds the meaning of max_hops (hop budget) and confirms the default, but max_hops has no schema description, and the description does not expand on hop semantics beyond that. 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: an evidence-backed path between two DFX ids across every graph, with each hop defined as a published relationship or SAME_AS identity link. This is clearly distinguishable from the sibling search_relationships (which lists relationships rather than connecting two entities) and from the get_* entity 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?

Explains the search is bidirectional and bounded by max_hops, and gives crucial interpretation guidance (NO_MATCH means no observed path within budget, not that they are unconnected). It does not, however, name an alternative tool or state explicit when-not-to-use conditions, so it stops short of the top tier.

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

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

Annotations already cover readOnly/idempotent/destructive/openWorld, and the description adds real value beyond them: it explains the returned object types, that match basis and ambiguity are surfaced, that property and parcel are barely-overlapping populations that may return one/both, and that the call is free.

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

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

Core action is front-loaded and sentences are dense and purposeful. There is mild redundancy between 'canonical DFX object ids' and the closing sentence restating that the ids are canonical across the server, but overall it reads tightly.

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

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

With no output schema, the description carries the return-value burden and does so well, naming the typed objects, the ambiguity signal, and the two populations. It stops short of describing no-match behavior or the shape of the ambiguity field, but is largely complete for a resolver.

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 address, city, state, and limit in detail. The description adds nothing parameter-specific, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Turn a street address into canonical DFX object ids') and clarifies the two output populations (property vs parcel). It clearly separates this resolver from the search_* siblings by describing it as an address-to-id resolution step, though it never names a specific alternative tool.

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

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

The use case (given an address, get canonical ids) is implied clearly, and 'Free' signals cost. But there is no explicit when-to-use/when-not guidance or reference to alternatives like search_parcels, verify, or get_property_record, leaving the agent to infer routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavioral context beyond them: match ranking (exact, prefix, word), one-row-per-entity de-duplication, typical latency under 200ms, and a detailed entitlement model (5 rows + counts when locked, contact values withheld, entitlement/locked fields). The remaining gap is that the `locked`/`entitlement` return shape is asserted but not illustrated.

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

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

The core behavior is front-loaded and dense, but the run-on identity sentence is hard to parse and the closing 'DFX Intelligence, 7 days free at https://...' line is promotional rather than operational, padding the definition.

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

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

For a read-only lookup with no output schema, the description covers matching semantics, cardinality (one row per entity), roles, latency, and the full access/withholding model. An agent has everything needed to call it and interpret a truncated 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?

With 75% schema coverage the baseline is already 3, and the description adds real meaning: `name` matches aliases/former names/dbas/legal names and accepts a partial word, `domain` enumerates the graph verticals, and the role-merging behavior explains why one entity may surface across graphs. Only `limit` goes unaddressed.

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

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

States a specific verb+resource ('Resolve a ... name to canonical dfx ids') and pins the scope to the Data Factory name/alias index across named graph verticals. It also pre-empts confusion with the nearest sibling by stating real estate organisations are resolved by resolve_organization instead.

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

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

Explicitly positions itself as 'the first call before get_entity' and routes a competing case (real estate organisations) to resolve_organization. That is a clear when-to-use plus an exclusion with a named alternative.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world). The description adds value beyond them: it is free, it returns all candidates rather than a best guess, and it declines person lookup. Return-shape behavior is disclosed even without an output schema.

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

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

Four short sentences, front-loaded with the core purpose, then the key semantic caveat, then cost and scope. No filler or repetition.

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

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

For a read-only 2-param resolver with no output schema, the description covers purpose, semantics, cost, and scope exclusions adequately. It leaves slight ambiguity about how it relates to search_entities for the same name-to-id task.

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 are fully documented in the schema, so the baseline is 3. The description's blocking-key explanation largely restates what the schema already states for both 'name' and 'limit'.

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

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

States a specific verb (resolve), resource (organization name), and output (canonical DFX entity ids), and explicitly distinguishes itself from person lookup. An agent can tell it apart from search_entities/get_entity 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 use (owner, manager, lender or servicer names) and an explicit exclusion ('Person lookup is deliberately not offered'), which implicitly routes to search_people. It does not explicitly name when to prefer this over search_entities or get_entity, so it stops short of full when/when-not guidance.

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

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

Annotations only declare it a safe, idempotent read; the description adds the substantive behavior an agent cannot infer: name-only resolution never collapses to one person, entitlement gating truncates lists to 5 rows plus counts, records expose only 3 related names per section, and contact/decision-maker values are suppressed and only reported as types/counts via `entitlement` and `locked`.

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 resolution rule, then behavior, then access limits — a good information hierarchy. The closing promotional block ('DFX Intelligence, 7 days free at https://...') does not help tool selection and is pure overhead, though it is short.

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

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

With no output schema, the description carries the return-value burden and does so well by describing the card, candidate lists, and the entitlement/locked fields. The only unexplained surface is how `limit` interacts with the 5-row entitlement cap, which an agent might reasonably want to know.

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 83%, so the baseline is 3. The description lifts it by explaining the asymmetry the schema only hints at: a firm *name* searches current and prior registrations while firm_crd is current-only, and name-only input produces a candidate list rather than a record. It says nothing about `limit` or `state`, leaving a small gap.

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

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

States a specific verb (resolve), its exact inputs (name + firm name or CRD, or individual CRD) and its output unit (one person card). It explicitly contrasts its behavior with the sibling get_ria_advisor ('the same as get_ria_advisor's summary; call get_ria_advisor(dfx_id) for the history'), so an agent can pick between them 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?

Explicit when/when-not guidance: a name alone is never resolved to one person and instead returns labelled candidates with `resolved` false, and the firm-then-prior-registration fallback order is spelled out. It also names the alternative tool and the exact argument (dfx_id) needed to reach 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing the entitlement model: free tier returns only the first 5 rows plus locked.count/locked.by_type, records name only their subject and first 3 related names, and contact values/decision-maker names are withheld but reported as types and counts. It also flags that 13F covers only US-listed long equity, so private holdings are absent.

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 purpose and return fields, followed by input guidance and access constraints. Every sentence earns its place, though the trailing plan/pricing pitch is slightly promotional rather than functional.

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly (field-by-field), plus covers access restrictions and the 13F coverage limitation. For a 6-parameter, no-required, no-output-schema tool this is complete enough to call correctly.

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

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

Schema coverage is high (83%), so the baseline is 3, but the description adds real meaning: it supplies example SIC codes (3674, 6021/6022, 1311, 2834, 7372), explains that a sector word is matched against the SEC SIC description, and clarifies the CUSIP→ticker→CIK→EDGAR SIC chain behind sector assignment.

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

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

States a specific verb (search) plus resource (family office / 13F filers holding a sector) and enumerates exactly what is returned per office (value, positions, share of book, top five, class, state, filing). It also implicitly distinguishes itself from sibling list tools by scoping to sector holdings on the 13F graph.

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 explains the family_capital_only toggle and how to express a sector (SIC codes or a sector word), which is usage context, but it never names an alternative tool or states when to prefer search_family_offices / search_family_office_investments over this one. Usage is implied rather than prescribed.

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 readOnly/idempotent annotations, it discloses substantial behavior: the tiered entitlement model (5 rows plus counts when unentitled), that contact values and decision-maker names are withheld, and that every answer reports withholdings in `entitlement` and `locked`. This is exactly the kind of access and data-suppression context an agent cannot get 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?

The row definition is front-loaded and information-dense, and most clauses earn their place by adding field or filter semantics. It is a very long run-on construction with a trailing promotional line about the paid plan, which slightly hurts readability but does not bury the core purpose.

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

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

With no output schema, the description correctly takes on the burden of describing the returned row structure and the entitlement-suppression behavior, and it covers filter/sort semantics for a 13-param tool. Minor gaps remain around pagination/ordering defaults (only `cursor` is schema-described), preventing a 5.

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 54%, but the description compensates by mapping the lower-documented filters (bucket, status, re_ups_only, first_time_only, since, sort) to their meaning and by clarifying that status values COMMITTED vs DISCLOSED_HOLDING carry different semantics. The dfx_id params are already well described in the schema, so a 4 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 opens with a concrete definition: 'One row per line of a plan's own disclosure' and enumerates the returned fields (allocator, fund, manager, bucket, amount, status, vintage, etc.), making the resource and granularity unambiguous. It never explicitly names the sibling it is distinct from (get_commitments, search_vc_lp_commitments), so an agent must infer differentiation, keeping it below a 5.

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

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

It lists the filterable dimensions and sort keys, which implies when the tool is useful, and adds semantic guardrails ('a target is never an actual', 'a disclosed holding is never an approval'). However, it never states when to prefer this over get_commitments or the LP-commitment sibling, so usage selection 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?

The description goes well beyond the read-only annotations by disclosing access tiers, exactly what is withheld without a paid plan (locked counts, contact values, decision-maker names), and the entitlement/locked response fields. It also states important data caveats: targets are not actuals, disclosed holdings are not approvals, commitment dollars repeat, re-ups are the plan's own words, and estimates are labelled.

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-loads what the graph contains, but it runs long and packs access restrictions, caveats, and a marketing URL into one paragraph. Much of the content is useful, yet the structure could be tighter and more scannable.

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

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

Given 14 parameters, no output schema, and only partial schema coverage, the description provides strong context on data semantics, entity_type behavior, and access limitations. It still leaves several filter parameters unexplained, but the behavioral and entitlement coverage is unusually complete.

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

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

Schema description coverage is low at 29%, so the description must compensate for many of the 14 parameters. It adds meaning for entity_type and query (alias-aware, CalPERS resolves), but most filters such as sort, state, min_assets_usd, with_policy, allocator_class, consultant_class, with_commitments, include_components, and min_private_markets_target_pct are not explained beyond the schema.

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

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

The description identifies the resource as the capital-owner graph and enumerates the allocator types it covers, along with how entity_type changes the target set. It distinguishes itself from sibling search tools by scope, though it does not explicitly use the verb 'search' in the description text itself.

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

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

It explains how to use entity_type variants and what a bare query does, which implies when each mode is useful. However, it never names alternatives or states when not to use this tool versus siblings like get_allocator or search_entities.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description still adds substantial behavioral context beyond them: the guidance is 'QUOTED, NOT APPLIED' and uses an equity-based proxy rather than total risk-based capital, every row states its quarter, and 'no person appears in this data'. This discloses data provenance and proxy limitations the agent would otherwise misread.

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

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

Dense but front-loaded: purpose and dataset scope lead, then a separate paragraph for the critical proxy caveat. The first paragraph is a long run-on, but nearly every clause carries distinct information and the caveat paragraph earns its place given the ambiguity it resolves.

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 9 optional parameters and no output schema, the description carries the full burden and meets it: it describes the returned fields, the 4,313 vs 4,242 coverage split, percentile rank availability, the proxy caveat, and that 'matched' reports the true total. An agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description's filter list (state, name, CRE-to-equity, guidance screen, minimum assets/noncurrent) and its mention of the default sort largely restate what the schema provides, adding little beyond it. 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 (Search) and resource (4,313 FDIC-insured banks by commercial real estate book) with the exact data vintage (June 2026 call report). It enumerates the measures returned (total CRE, construction, multifamily, noncurrent, charge-off, ROA, guidance screens) so an agent knows precisely what this resource covers and how it differs from the finance-domain 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?

The description implies usage by listing the available filters (state, name, CRE-to-equity range, guidance screen, minimum assets, minimum noncurrent) and sorting options, and flags that it is 'Free'. However, it never states when to prefer this over an alternative or any prerequisite/context for choosing it, so guidance is 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 already cover safety (readOnly, idempotent, non-destructive, closed-world), but the description adds substantial non-obvious behavior: entitlement-gated returns (first 5 rows full, rest only as locked.count/locked.by_type), never-returned contact values and decision-maker names, and the `entitlement`/`locked` output fields. It also clarifies that a refreshed number surfaces as numbers_updated rather than as a change — a semantic caveat the 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?

The purpose and return-shape content is front-loaded and dense with useful specifics, but the ACCESS paragraph plus the promotional plan link ('DFX Intelligence, 7 days free at...') is marketing filler that dilutes an otherwise efficient description.

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

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

With no output schema, the description does the work of describing returns: comparison verdict, added/removed/rewritten counts, clipped sentences, both filings cited, plus entitlement/locked metadata. Combined with the explicit hand-off to search_documents, an agent has enough to call and interpret it, though the exact response envelope is still only loosely specified.

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 80%, so the schema already documents most parameters. The description adds some meaning for `term` ('software, tariffs, AI... or any word') and implies recency via 'latest 10-K or 10-Q', but does not explain section, filed_from, or changed_only behavior 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 precise verb+resource: every active BDC whose latest 10-K/10-Q names a term, compared sentence-by-sentence against the prior filing, with added/removed/rewritten sentence counts. It also explicitly differentiates from the sibling search_documents ('For the passages themselves use search_documents'), 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?

Gives a concrete when-to-use framing ('The answer to "which BDCs added language about software risk this quarter"') and routes passage retrieval to search_documents. It lacks explicit when-NOT-to-use conditions beyond that single alternative, so it falls just 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.