DFX Real Estate Intelligence

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

Annotations already cover read-only/idempotent/non-destructive, so the bar is met by adding non-obvious behavior: the first cursorless call returns ZERO events by design, learn-time ordering means old facts arrive in today's delta, and full pages set complete:false. 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?

Front-loaded with the core concept and cursor behavior, and every sentence carries information. The all-caps emphasis block is slightly shouty and partially repeats the learn-time-ordering point made in the opening 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 7-parameter read feed with no output schema, the description covers cursor lifecycle, ordering semantics, pagination, cost, and the historical-backfill gotcha — everything an agent needs to call it 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% and the parameter descriptions are unusually rich (cursor semantics, pagination, complete:false). The description's 'filter by event type, state, or a specific property or parcel id' only restates what the schema already documents, so baseline 3 applies.

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

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

The description states a specific resource and mechanism ('a feed of what is NEW since a cursor, ordered by when DFX learned it') and explicitly contrasts it with the search-style siblings ('It answers what is new, not what exists'). An agent can distinguish it from search_events/search_property_events 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 gives clear usage context: first call without a cursor, subsequent calls with the returned cursor, and that frequent polling is cheap ('Deterministic and indexed'). The 'new, not what exists' line functions as an implicit when-not, but no sibling is named as the explicit alternative for state queries.

Agents often have multiple tools that could apply. Explicit usage 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 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?

Beyond the readOnly/idempotent annotations, it discloses that the call is free, queries no underlying data, and derives its verdict from a coverage registry so NOT_COVERED is measured rather than inferred. This is meaningful behavioral context, though return formatting/pagination is not covered (and no output schema exists).

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

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

Front-loaded with the two operating modes and reasonably tight, with no wasted sentences. It is somewhat dense (registry explanation, empty-vs-absent distinction) but each sentence carries value.

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

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

With no output schema, the description carries the return-value burden and does so: it explains the grid shape and the single-slice verdict plus its basis. Adequate for a free, read-only lookup, though slightly more on the exact verdict payload would be ideal.

Complex tools with many parameters or behaviors need more documentation. 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 already documented in the schema. The description only restates that state/event_type narrow the answer to a single slice, adding the verdict semantics but no new syntax or format detail beyond the schema.

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

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

The description states a specific verb+resource: it reports measured coverage of served sources, object types and gaps, returning a grid or a COVERED/NOT_COVERED/UNKNOWN verdict. It is clearly differentiated from search-type siblings, though it does not explicitly contrast with the similarly-named 'what_can_dfx_answer'.

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

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

It gives explicit usage modes: no arguments returns the full grid, while state/event_type yields a direct verdict on one slice. It also implies when to prefer this over searching ('separates an empty result from an absent market', 'queries no data'), but names no explicit alternative tool.

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

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

Annotations already establish safety (read-only, idempotent, non-destructive), so the bar is lower. The description adds meaningful behavior: it accepts the two IDs in either order, returns the computed match only conditionally ('if the graph has one'), includes a confidence label, and explicitly commits to returning facts rather than a score. No statement contradicts the annotations.

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

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

The description wastes no words; the opening scope clause is front-loaded and the enumerated sections carry the burden of explaining outputs. The ALL-CAPS headings are slightly telegraphic but each item adds a distinct piece of information, and the closing one-liner reinforces the tool's nature.

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

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

With no output schema, the description must carry the return-value burden, and it does: it names all major output sections and even supplies sub-details such as 'dated investments in the same sector, with sources' and 'a path on the graph if one exists.' It doesn't cover edge cases (e.g., invalid pairings) or the exact shape of the computed match/confidence label, but those are minor against the level of detail provided.

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

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

The schema fully documents the ID formats for both parameters, so baseline is 3. The description adds semantic value by assigning roles (one is an investor, the other an opportunity) and by stating that order does not matter. This is information the schema alone does not convey.

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

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

The description defines the tool's scope precisely: it takes an investor-opportunity pair and enumerates the exact content returned — match reasons, blockers, supporting observations, comparable history with dates and sources, relationships, recent events, computed match (when present), and confidence label. The phrase 'Facts, not a score' clarifies what the tool deliberately does not provide. Though the verb is implied by the name/title rather than written out, the purpose is unambiguous.

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

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

There is no explicit guidance on when to choose this tool over the many related siblings, such as relationship_path, get_capital_paths, or find_opportunities_for_capital. The intended use is strongly implied by the title and parameter semantics ('for an investor and an opportunity'), but the description doesn't state exclusions or alternatives. This keeps it at implied rather than explicit 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 already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail beyond that: results are not paired or ranked, company-to-sponsor pairs are withdrawn, first-time capital providers are not recommended, and every row carries a basis label (observed_behaviour, computed_match, observed_investments, derived). This gives an agent useful expectations about output semantics and limitations.

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

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

The description is dense and front-loaded, opening with the core 'Investors for a company or described opportunity' framing. Every sentence adds distinct information: investor types, exclusion criteria, and row basis. It is long but not bloated; a slightly more structured layout could improve scannability, but nothing is wasted.

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

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

For a 12-parameter tool with no output schema, the description covers the main use cases, result types, output row semantics, and a key exclusion (no first-time capital providers). It does not explain all optional parameters and does not explicitly differentiate from inverse siblings like find_opportunities_for_capital, but the core information needed to invoke the tool correctly is present.

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

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

Schema description coverage is only 25%, so the description must compensate. It does map several parameters (sector, state, deal_size_usd, stage, control) to the concept of a 'described opportunity' and partially explains investor_types via the listed investor categories. However, it leaves other parameters unexplained: vertical, asset_class, check_size_usd, sponsor_involved, and limit. The compensation is partial, not complete.

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

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

The description states the exact purpose: find investors for either a company (dfx_id) or a described opportunity (sector, state, deal size, stage, control). It enumerates the investor types returned and distinguishes itself from siblings by noting that sponsors are 'listed, not paired or ranked' and that company-to-sponsor pairs are withdrawn. This makes the tool's job unambiguous.

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

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

The description gives clear context for when to use the tool: when you need investors for a company or an opportunity described by sector/state/deal size/stage/control. It explains which investor types appear and in what circumstances, such as venture firms 'when the opportunity is venture-shaped.' It does not explicitly name alternatives or exclusions, but the guidance is concrete enough to route an agent correctly.

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

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

Adds substantial behavioral context well beyond the readOnly/idempotent annotations: the exact scoring weights (comparables 35%, recency 20%, etc.), refusal conditions (stale comparable, book under 0.85, passive holds under $2M), size semantics ('lower bounds... never the commitment'), and the data-coverage caveat on state filtering ('about one comparable in six today'). No contradiction with annotations — the readOnly and idempotent hints are consistent with a deterministic ranked computation.

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

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

The description is dense but every sentence earns its place — core ranking logic first, then scoring weights, refusal rules, caveats, and routing. It front-loads the essential mechanism before nuances and uses compact formatting (backticks, parentheticals) to pack operational detail without padding.

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

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

For a 9-parameter tool with a weighted scoring model, refusal conditions, and data-quality caveats, this description is remarkably complete. It covers ranking basis, score composition, exclusions, size semantics, state-filter behavior, the geo_coverage output signal, and sibling routing. With no output schema, the only minor gap is the literal shape of the ranked list, but the scoring model makes the output predictable.

Complex tools with many parameters or behaviors need more documentation. 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 67% schema coverage, the description meaningfully deepens several parameters: industry is 'as the filer wrote it' with concrete example terms, states is explained as DFX-held GLEIF headquarters with a coverage caveat, and size parameters are clarified as lower bounds never the commitment. However, limit, size_max_usd, and band_max_usd receive no added meaning in either schema or description, leaving a modest residual gap.

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

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

The description states a specific verb and resource — 'Lenders ranked on the comparable facilities they CURRENTLY HOLD on BDC schedules' — and gives a concrete scenario it answers ('find lenders for a $60M unitranche for a sponsor-backed healthcare services business'). It explicitly differentiates from the sibling search_private_credit by naming it and describing the difference in industry-filter semantics.

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

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

Provides explicit when-to-use guidance: 'This is the answer to... use it before search_private_credit, whose industry filter lists borrowers.' This both names the alternative and states the ordering between the two tools, leaving nothing to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful output behavior: computed matches with reasons and blockers, transition-signal companies, sponsors seeking capital, raising companies, and the behavior it reasoned from. No contradiction with annotations.

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

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

The audience and core behavior are front-loaded, and each clause contributes a distinct output category or constraint. However, the first sentence is long and run-on, and the 'then' sequence could be misinterpreted as temporal ordering rather than additional categories.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 what is returned: matches with reasons/blockers, transition-signal companies, sponsors seeking capital, raising companies, and the behavior reasoned from. It stops short of describing result shape, pagination, or how limit applies, but the key essentials for a read-only discovery tool are present.

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

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

The description adds no parameter-level meaning. The schema documents dfx_id's accepted ID formats well, and limit has numeric bounds/default, but with 50% schema coverage the description does not compensate for the limit parameter's missing semantic description. Still, the schema provides enough for correct invocation.

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

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

The description clearly states the tool's direction: for an investor entity, return opportunities DFX knows that fit the entity's demonstrated behavior, with specific output categories. It is distinguishable from inverse sibling tools like find_capital_for_opportunity and find_pe_buyers_for_company, though it does not explicitly name a sibling or alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 opening 'For a family office, sponsor, capital provider or venture firm' gives an explicit audience and use context, reinforced by dfx_id's accepted graph types. It does not explicitly explain when to prefer this tool over alternatives or state exclusions, but the intended use case is clear enough for correct 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?

Beyond the readOnlyHint, idempotentHint, and non-destructive annotations, the description adds meaningful behavior: the matches are computed, the matcher fields are returned verbatim, and NOT_COVERED is explicitly explained as meaning the matcher scored nothing, not that no add-on fits. This is valuable context that annotations do not provide and prevents misinterpretation of empty or sparse 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 description is compact and front-loaded: the core purpose is stated first, followed by the output contents and the critical NOT_COVERED caveat. There is no filler or redundancy, and every sentence adds useful information.

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

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

Given that there is no output schema, the description does a strong job of enumerating the returned fields and explaining the one tricky result state (NOT_COVERED). It also identifies the required input and its source. For a read-only computed lookup, this is complete enough for an agent to select and call the tool correctly.

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

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

The description adds useful meaning to dfx_id by specifying it is a platform company id from search_pe_platforms. However, the optional limit parameter is not described beyond its schema default/min/max, and schema coverage is only 50%. The description partially compensates but does not fully explain both parameters.

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

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

The description states exactly what the tool does: it returns computed add-on matches for a single platform company, listing the candidate, matcher's reasons, blockers, why_now, comparable add-ons, owner, score, confidence, and computed date. It also names the expected input source (a dfx:pe: company id from search_pe_platforms), which distinguishes it clearly from sibling tools that handle buyers, firms, or funds.

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

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

The description gives clear usage context: use it for one platform company identified by a dfx:pe: id from search_pe_platforms. It does not explicitly enumerate alternatives or exclusions, but the input source and singular-platform scope make the intended use reasonably obvious. The NOT_COVERED caveat also helps the agent interpret empty results correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's additional behavior details are valuable. It discloses that results are precomputed matcher output, lists exactly which fields are returned verbatim, and explains the NOT_COVERED sentinel with population count.

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

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

Three sentences each carry distinct and necessary information: what is returned, what NOT_COVERED means, and which sibling tool to use instead. The main functional statement is front-loaded, with no filler or repetition.

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

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

Since there is no output schema, the description carries the full burden of explaining return values. It enumerates the returned fields, including reasons, blockers, why_now, comparable transactions, score, confidence, and model version, and explains the special NOT_COVERED case. Nothing an agent needs to interpret the result is missing.

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

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

The schema already documents dfx_id fully, including the allowed namespaces, and limit has default/min/max constraints. The description reinforces the id format but adds nothing about the limit parameter or how it shapes results. It is adequate but does not meaningfully compensate for the 50% schema 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?

The description states a specific verb and resource: it returns computed buyer_for_company matches from the private equity matcher for one company, with exact accepted id namespaces (dfx:pe:, dfx:isi:, dfx:vc:). The title further clarifies the direction of the match — PE firms that could buy this company — making it easy to distinguish from reverse or adjacent search 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 explicitly gives an alternative: 'For sponsors, family offices and capital providers as well, use find_capital_for_opportunity.' It also clarifies when the result is NOT_COVERED: 'that means DFX has not computed buyers for it, never that no buyer exists,' preventing a critical misinterpretation.

Agents often have multiple tools that could apply. Explicit usage 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 annotations, the description reveals that results are pre-computed matches, enumerates the returned fields (reasons, blockers, why_now, comparables, score, confidence, computed date), and gives the critical NOT_COVERED caveat that absence of scores is not a claim that nothing fits. This adds real behavioral context and prevents an agent from overinterpreting the sentinel.

Agents need to know what a tool does to the 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 compact and front-loaded: the first sentence states action, scope, and return content, and the second sentence clarifies a semantically important sentinel. Every sentence earns its place with no filler.

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

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

With no output schema, the description successfully carries the burden of explaining return values: it lists the per-company fields and the NOT_COVERED sentinel. It also identifies the required identifier type. It could mention ordering or default limit behavior, but those are minor given the schema already covers the limit bounds.

Complex tools with many parameters or behaviors need more documentation. 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 already documents dfx_id's format and domain, and limit's bounds and default. The description reinforces the dfx:pe form but does not add meaningful semantics for limit, such as ordering or pagination behavior. Since schema coverage is partial and the description compensates only slightly, a mid-range score 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 specific verb and resource: 'Computed company_for_buyer matches for one private equity firm.' It clearly distinguishes this tool from inverse or sibling tools like find_pe_buyers_for_company by stating it returns companies for a buyer, and it names the required identifier domain (dfx:pe: id).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clearly scopes the tool to one private equity firm and explains the NOT_COVERED condition, which is important for interpreting empty or absent scores. It does not explicitly name alternatives or state when not to use this tool, but the scope is clear enough 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?

The annotations already declare this a safe read-only, idempotent operation. The description adds meaningful caveats beyond the annotations: that estimates are labelled, nothing predictive is published, and reported figures must not be conflated with approvals or approvals. This warns an agent against misinterpreting overlapping dollar figures or targets, which is valuable behavioral and output-interpretation context.

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

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

The description is long but dense: the main content is front-loaded and organized by entity type, and every clause adds a specific data category or caveat. It is structured enough for the tool's breadth, though the first sentence is heavy.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It covers the return categories for allocators, consultants, managers, and funds, names get_entity for same_as links, and adds data-quality caveats about estimates and estimates. The description is complete enough for an agent to understand what the call returns and how to interpret its contents.

Complex tools with many parameters or behaviors need more documentation. 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 only parameter, dfx_id, has a complete schema description including the ID format and search sources. The tool description adds little beyond the schema's own parameter documentation, so with 100% coverage the baseline of 3 is appropriate.

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

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

The description clearly defines the tool as returning a full profile for an allocator, consultant, manager, or fund and enumerates the major data categories returned for each. It is specific and unambiguous, and it names get_entity for same_as links, though it does not explicitly differentiate get_allocator from related sibling getters like get_entity or get_pe_firm.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 useful context about what data is included for each entity type, so an agent can infer when a full-entity lookup is appropriate. It does not state explicit when to use this tool versus alternatives or which sibling to choose for narrower lookups, leaving the choice mostly implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the description doesn't repeat those. It adds useful behavioral context beyond annotations: default 'debt only' (interpretable as include_equity=false), pagination at 25 items, and the default quarter-end selection. It also notes figures are 'in the filer's own figures,' which is non-standard but valuable. No contradiction with annotations.

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

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

The description is a single sentence that front-loads the core function ('Every position a BDC tagged at one quarter end') and packs the returned fields into a clear list. It is efficient with no filler or repetition of schema details (like types or defaults). The structure lets an agent quickly grasp the tool's output and key behaviors.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 6 parameters with 50% schema description coverage and no output schema, the description provides a strong foundation: it lists all returned fields, mentions default quarter-end, pagination, and debt-only default. It does not explicitly describe sort options or the exact format of as_of (though schema covers that), and it omits any note about error handling or rate limits. Still, for a read-only portfolio tool, this is quite 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 50% (dfx_id, as_of, cursor have descriptions; sort, limit, include_equity lack them). The description compensates for some gaps: it clarifies as_of's default, mentions pagination (implicitly covering limit and cursor semantics), and hints at include_equity via 'Debt only by default.' However, it does not explain the 'sort' parameter or its enum values, and the relationship between limit and pagination is only partially addressed. Overall, partial compensation but not complete.

Input schemas describe structure but not intent. Descriptions should explain 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 ('get') and resource ('BDC portfolio'), then enumerates the exact fields returned (borrower, instrument, kind, lien, principal, fair value, etc.). It also clarifies scope ('one quarter end') and default behavior ('latest unless as_of is given'). This clearly distinguishes it from sibling tools like get_borrower_capital_structure or get_credit_facility.

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

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

No explicit guidance on when to use this tool versus alternatives. Among many sibling tools (get_borrower_facilities, get_credit_facility, etc.), the description does not provide a comparison or exclusions. The only contextual hint is 'Debt only by default,' which is a behavioral note, not a usage guide. An agent has to infer when this is the right tool.

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

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

Even though annotations already mark it as read-only and idempotent, the description adds crucial interpretive guardrails: fact classes are explained, marks are not impairments, maturity changes are not amendments, and non-accrual/default are never inferred. This goes well beyond the annotations and prevents misreading of sensitive fields.

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

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

The description is dense and run-on, but every clause contributes meaningful constraints or clarifications. It is front-loaded with the main return scope before moving into fact-class semantics and caveats. Slight structural improvement would be easier scanning as separate sentences.

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

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

With no output schema, the description carries the full burden of conveying the shape and semantics of results. It specifies every data category, the meaning of fact classes, and explicit boundary conditions. An agent has enough context to call this tool and interpret its output correctly.

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

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

The only parameter, dfx_id, is fully documented in the schema with format and provenance guidance. The description adds no additional parameter semantics, but since schema description coverage is 100%, the baseline of 3 is appropriate.

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

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

The description precisely enumerates what the tool returns: the borrower group, facilities, BDC pieces, tape, sponsor attributions, and events. It clearly distinguishes this from sibling tools like get_borrower_facilities by signaling it is the full consolidated capital-structure view from BDC lenders' perspective.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 title and description make it clear this is for the comprehensive borrower capital structure as BDC lenders see it, including derived, carried, and inferred data. It does not explicitly name alternatives or say when not to use it, but the scope is strongly implied by the exhaustive component list.

Agents often have multiple tools that could apply. Explicit usage 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/non-destructive annotations, the description discloses important caveats: principal is only the sum of BDC pieces and a lower bound, never the commitment, and lenders that file no schedule are omitted. It also signals historical holdings via 'quarters it held,' giving realistic expectations about data completeness.

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

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

The description is dense but front-loaded with the core resource and contains no filler; every clause carries output or caveat information. It could be restructured into a clearer list, but it remains appropriately sized for the breadth of returned fields.

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

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

With no output schema, the description carries the burden of explaining return values and does so thoroughly: facility fields, lender-level fields, historical quarters, credit manager, and principal semantics. The remaining defaults and id source are already supplied by the input schema, so nothing essential is missing.

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

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

The schema documents dfx_id and held_only, covering two of three parameters, but the prose adds no parameter-level meaning and the limit parameter still has no description beyond its constraints. Since schema coverage is 67% rather than high, the description neither fully compensates nor needs to for the tool to be usable.

Input schemas describe structure but not intent. Descriptions should explain 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 perspective: every facility a borrower group has on the BDC tape, with the lender group on each. It clearly differentiates this from sibling entity-lookup and capital-structure tools by naming the data source and the lender-group detail.

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

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

The scope is unambiguous: use this for a single borrower group's BDC-tape facilities and the lenders on each, including historical holders. It does not name alternatives or exclusions, but the context is clear enough for an agent to select it without being misled.

Agents often have multiple tools that could apply. Explicit usage 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 adds meaningful behavioral detail beyond the read-only/idempotent annotations: paths are built only from identity-grade or measured links, candidate links carry confidence below 0.5, and NOT_COVERED specifically means the layer has not computed the path rather than no relationship existing. This clarifies result semantics and data quality 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?

The description is three sentences, front-loaded with the core purpose, then detailing path components and finally clarifying confidence and NOT_COVERED semantics. It is dense but each sentence earns its place, and the structure flows logically from function to interpretation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 path components, confidence, data quality, and the critical NOT_COVERED interpretation. It does not explicitly explain limit behavior or ordering, but overall it provides sufficient context for an agent to invoke the tool and interpret results correctly for a read-only operation.

Complex tools with many parameters or behaviors need more documentation. 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 descriptions for dfx_id and kind; limit has constraints but no description. The description reinforces the kind concept through examples but does not enumerate valid values or explain how limit affects result pagination, so it adds only marginal value 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 explicitly states the tool publishes capital flow paths through one institution and gives three concrete scenarios (allocators, lenders, properties). This distinguishes it from siblings like relationship_path by focusing on capital flows with specific path components and confidence, making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when the agent needs to trace capital flows through a specific institution, but it never explicitly contrasts with similar sibling tools like relationship_path or search_relationships, nor does it provide when-not conditions. The context 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 already mark this as read-only and idempotent, and the description adds substantial behavioral context: default dated commitments, the include_holdings toggle for value-only holdings, and the important caveat that commitments are the plan's number and repeat across reports. This goes well beyond the structured annotations.

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

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

The description is dense and front-loaded with the core purpose, and every clause carries useful information. It is somewhat long with nested parentheticals, but the detail is necessary for domain-specific semantics.

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

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

With no output schema, the description enumerates the key returned fields and clarifies the distinction between dated commitments and holdings, which is enough for most calls. The only notable gap is the undocumented limit parameter and lack of explicit pagination or result-shape details.

Complex tools with many parameters or behaviors need more documentation. 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 33%, so the description needs to compensate. It adds meaningful semantics for dfx_id ('any id they reference') and include_holdings ('value-only holdings... only with include_holdings'), but it does not explain the limit parameter beyond what the schema already provides through constraints.

Input schemas describe structure but not intent. Descriptions should explain 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 clearly states the tool returns commitment tapes for an allocator or manager/fund, with specific fields and scope. It is more specific than a simple restatement, but it does not explicitly distinguish itself from the sibling search_allocator_commitments, so it stops short of a 5.

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

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

The description explains what the tool returns and how parameters behave, but it gives no explicit guidance on when to choose this tool over alternatives such as search_allocator_commitments. There are no stated exclusions or conditions for using this versus a sibling tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context: it explains that size is 'the sum of BDC pieces with its basis, pricing modal and ranged across pieces, maturity with basis', and that the lender group includes 'every BDC that holds or held a piece, each row the lender's own figures, plus lenders named on a deal'. This goes beyond the annotations by clarifying the aggregation and scope semantics, though it does not describe return format or pagination.

Agents need to know what a tool does to the 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 a single dense sentence that packs in a lot of information, but it is somewhat run-on and could be better structured. It front-loads the core definition ('one borrower group in one instrument class') and then lists components, but the long parenthetical chain makes it harder to parse than necessary. It earns its place but could be split into clearer sentences.

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

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

For a single-parameter read-only tool with 100% schema coverage and no output schema, the description is fairly complete. It explains what the facility is, how size is computed, what the lender group includes, and that history is covered. The main gap is that it doesn't explicitly describe the return shape, but with no output schema and a read-only annotation, the description carries enough context for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the dfx_id parameter. The description adds context by specifying the id format ('dfx:pc:<uuid>') and valid sources (get_borrower_capital_structure, search_credit_maturities, or an event), which is useful. However, the description itself does not explain the parameter beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description states a specific verb ('get') and resource ('one facility') and enumerates the content: size, pricing, maturity, lender group, and history. It distinguishes itself from siblings like get_borrower_facilities and get_borrower_capital_structure by focusing on a single facility with lender group and history, though it does not explicitly name those 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: call this when you need a single facility's full detail including lender group and history. It does not explicitly state when to use it versus alternatives like get_borrower_facilities or search_credit_maturities, but the input schema's dfx_id description references get_borrower_capital_structure, search_credit_maturities, or an event, providing some routing 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds data provenance context (10-K, Form ADV) but does not describe response structure, pagination, or other runtime behavior; there is no contradiction with annotations.

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

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

The description is dense with relevant detail and every clause contributes information, but it is structured as one long run-on paragraph with no bullet points or clear visual separation between the two entity types. It is effective but not well organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 explaining the return contract, and it does so by enumerating fields for both credit managers and BDCs plus accepted identifiers. A few terms such as 'classes with basis' could be clearer, but the essential information for invoking the tool is present.

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

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

The single parameter dfx_id is fully documented in the schema (100% coverage) with the accepted formats. The description repeats the same identifier forms without adding meaning beyond the schema, 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 clearly identifies both supported resources (a credit manager and a BDC) and enumerates what is returned for each, plus the accepted identifier forms. It does not explicitly contrast with focused siblings such as get_bdc_portfolio, but the content makes the 'full record' purpose evident.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 comprehensive profile of a credit provider or BDC, which implies when to use it. However, it does not explicitly state when to prefer this over more targeted sibling tools, nor does it mention any exclusions or conditions.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description reveals what the response contains: published relationships with sources and dates, evidence rows, cross-graph same_as links by shared identifier, candidate matches on other graphs, and pointers to deeper views. That is meaningful behavioral context beyond the annotations.

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

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

The description is a single dense sentence, but each clause adds a distinct data category and the tool's purpose is front-loaded. It could be split for readability, but there is no filler or redundant restating of the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 explaining the return contents and does so at a category level. It is missing details on limit semantics and how the 'deeper views' are referenced, but it is adequate for a broad lookup tool whose annotations already cover safety and idempotency.

Complex tools with many parameters or behaviors need more documentation. 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 dfx_id format and the include choices are documented, and the description maps to those categories. However, schema coverage is only 40% and three limit parameters (event_limit, evidence_limit, relationship_limit) have no defaults or behavioral notes beyond their names, so the description only partially compensates for the schema gap.

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

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

The description clearly defines the tool's scope: one DFX id and the complete set of data DFX holds about it—card, relationships, events, evidence, same_as links, and name candidates. It distinguishes itself from the many narrow get_* and search_* siblings by framing it as 'One answer to show me everything on X'.

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

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

It states the entry condition ('For any DFX id') and the intended use case ('show me everything on X'). It does not explicitly name alternatives or say when to prefer a specialized search/get tool, but the use case is clear enough for an agent to route general entity lookups here.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful detail beyond those flags: financial figures are kept separate with as-of dates, contact points are deliberately withheld, and same_as links are based on shared CRD/CIK/EIN identifiers. This is valuable behavioral context for an agent.

Agents need to know what a tool does to the 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, front-loaded with 'full card', and organizes a long list of return sections with commas. The opening phrase restates the title somewhat, but overall the length is justified by the amount of content the tool returns.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 one-parameter read tool with no output schema, the description inventories the response sections and explicitly notes an important omission (contact points). The small mismatch between the description's ID scope and the schema's accepted ID scope is a minor gap, but an agent can still invoke and interpret the result correctly.

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

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

The single parameter dfx_id is fully documented in the schema with 100% coverage, listing all accepted ID prefixes. The description only adds 'Accepts dfx:fo: ids', which is narrower than the schema's broader list and adds no new meaning, so the schema carries the semantic weight.

Input schemas describe structure but not intent. Descriptions should explain 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 clearly states the verb-resource pair: 'full card for one family office' and enumerates the returned content (profile, AUM/RAUM/13F, people, investments, relationships, events, links). It is specific, but it does not explicitly differentiate itself from sibling get_* or search_family_offices tools beyond the singular 'one' and the ID hint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when to use the tool: when you have a known DFX ID and want the complete family-office record. It also gives an exclusion ('Contact points are withheld over MCP'), but it never names alternatives such as search_family_offices or search_family_office_investments, nor states when those should be preferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds substantial behavioral context by detailing the output contents: verification status, counts, reasons, transactions, capital relationships, fund size, SBIC status, strategy, transition signals, and more. No contradiction with annotations.

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

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

The description is lengthy but dense and well-structured, front-loading the main purpose ('The full card for any entity on the sponsor graph') followed by specific entity details in parentheses. Every sentence provides relevant information, and the structure aids readability.

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

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

For a single-parameter read-only tool with no output schema, the description covers the output scope comprehensively, listing entity types and included fields. It lacks error behavior or pagination details, but these are less critical for a read tool with a clear id input. Overall adequate 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?

Schema description coverage is 100% for the single parameter dfx_id, which is fully documented. The description's mention of 'Accepts dfx:isi: ids' is redundant with the schema and adds no new meaning. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool returns 'the full card for any entity on the sponsor graph' and enumerates three entity types (sponsor, capital provider, private company) with specific details for each. It distinguishes itself from search_independent_sponsors (search vs get) and get_entity (specific vs generic) by scope and content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 mentioning it accepts dfx:isi: ids and is for the sponsor graph, but it does not explicitly state when to use it over alternatives like get_entity or search_independent_sponsors. No exclusions or alternative conditions are provided, leaving the agent to infer the context.

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

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

Goes well beyond the 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it returns a comprehensive card, accepts multiple id types, and separates stated criteria from observed behavior. It does not mention pagination or response size, but the annotations carry the main safety burden.

Agents need to know what a tool does to the 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 information-dense, and the main purpose is front-loaded. Every clause adds a distinct piece of content about the card's sections. It could be slightly tightened, but the length is justified by the tool's broad scope.

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

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

For a read-only retrieval tool with one well-documented parameter and no output schema, the description covers the input format, accepted id types, and the full scope of the returned card. It does not describe the output structure, but the absence of an output schema and the tool's read-only nature make this acceptable.

Complex tools with many parameters or behaviors need more documentation. 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 dfx_id is well described in the schema. The description adds value by specifying the accepted id forms (dfx:pe:<uuid>) and the source tools that return such ids, which goes beyond the schema's generic description.

Input schemas describe structure but not intent. Descriptions should explain 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 specific verb and resource ('The full card for a private equity firm') and enumerates the card's sections in detail. It also explicitly states that it accepts person, fund, or company ids and returns the same card, which distinguishes it from sibling get_* 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 clearly states the input requirement (a dfx:pe: id as returned by specific search tools) and the accepted id types. It does not explicitly say when to prefer this over get_pe_fund or get_entity, but the detailed scope and the id-source note provide enough context for an agent to select it.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial beyond-annotation context: the tool refuses non-fund ids, clarifies that adv_gross_asset_value is reported gross assets rather than fund size or dry powder, and notes LP commitments are only included where disclosed.

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

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

One dense, front-loaded sentence conveys the full data scope, followed by one sentence covering refusal behavior and the sibling alternative. Every item earns its place and there is no repetition of schema 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?

For a one-parameter read-only tool with no output schema, the description thoroughly enumerates content categories, data semantics, caveats, and sibling routing. An agent has enough context to call it correctly and interpret what comes 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 coverage is 100% with a precise dfx_id format and source tools listed. The description adds the acceptance constraint that the id must be a fund and reinforces the manager-vs-fund distinction, slightly extending the schema's 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?

Description opens with 'One fund:' and enumerates exactly what is returned: manager, vintage, basis, Form ADV reporting tape, LP commitments, relationships, events and evidence. It also distinguishes itself from get_pe_firm by explicitly refusing non-fund ids, making tool selection unambiguous.

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

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

It clearly frames the use case as retrieving a single private equity fund in full. It states an explicit exclusion ('Refuses an id that is not a fund') and routes manager lookups to 'get_pe_firm', naming the relevant sibling 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 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?

Beyond the annotations (readOnly, idempotent), the description discloses important behavioral and data semantics: GAV is defined as assets on a filing date and excludes fund size/commitments/dry powder, quarantined readings are omitted, data only covers 2011–2024 so no 2025 facts exist, and holdings/properties/loans appear only when a binding passed blind labels. These are nontrivial caveats that help the agent interpret results and avoid mis-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 description is a dense single paragraph; the first sentence is a very long enumeration of contents separated by commas, which is hard to scan. Though every sentence carries relevant information (input format, GAV definition, temporal range, filtering), the structure could be improved with bullets or shorter sentences. It is not excessively long, but not well organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool returning a large aggregate with no output schema, the description covers the input options, the major data components, key definitions, the data time range, and filtering constraints. It doesn't explicitly mention return format or error behavior, but given the annotations already establish safety and the description is detailed, it is largely complete 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?

The schema already describes dfx_id as 'A dfx:ref:<uuid> manager id, or the manager's CRD as a string' with 100% coverage. The description simply repeats this in prose ('Accepts a dfx:ref: id or the manager's CRD') without adding examples, value formats, or additional parameter nuances, so it stays at the baseline for full schema coverage.

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

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

The description states a clear, specific verb-and-resource: it returns the complete record for a real estate fund manager, enumerating the manager card, vehicles, family, bindings, properties, loans, events, Schedule A, and cross-graph records. The title 'One real estate fund manager in full' and the comprehensive enumeration distinguish it from siblings like get_re_fund_vehicle and search_re_fund_managers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 via its comprehensive scope and the acceptances of dfx:ref id or CRD, and it adds temporal guidance ('sworn tape runs 2011 to 2024'). However, it does not explicitly name alternatives, state when not to use this tool, or contrast with search_re_fund_managers or get_re_fund_vehicle, leaving usage guidance partly implicit.

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

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

Annotations already cover read-only/idempotent/non-destructive behavior. The description adds useful behavioral context: the data is derived from the sworn tape, starts in 2011 and ends with 2024 filings, excludes feeders/quarantined readings for GAV, and is explicitly non-predictive. This goes beyond annotation payload and helps 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?

The description is a single, long, dense sentence with a colon-separated list. It packs a lot of information but lacks structural breaks; it's not as scannable as it could be, though every clause does carry meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with no output schema and three parameters, the description explains the data's provenance and limitations, but leaves ambiguity about whether all series are returned at once or selected via view, and is silent on limit. The agent could still call it, but might mispredict output shape.

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

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

Schema coverage is only 33%, with only min_gav_usd described. The description's list of series maps loosely to the view enum values, but never states that the view parameter selects one of these series, nor explains the limit parameter. Since schema coverage is low, the description should compensate but only partially does.

Input schemas describe structure but not intent. Descriptions should explain 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 explicitly states this returns derived trend series over the sworn tape and enumerates six specific series (vehicles by year, managers by year, GAV by year, vintages, drops, top managers). That differentiates it clearly from sibling get_ria_trends and search tools, which focus on individual records or other asset classes.

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

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

No explicit when-to-use or alternative guidance. The description implies it is for annual trend analysis of real estate fund activity and mentions data range caveats, but never says 'use search_re_fund_* for current individual records' or similar. Siblings like get_re_fund_vehicle and search_re_fund_managers are left unaddressed.

Agents often have multiple tools that could apply. Explicit usage 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=true and idempotent=true, but the description goes far beyond them by disclosing non-obvious behavioral semantics: a gap is non-reporting, never zero assets; GAV is filing-date assets, never fund size, commitments, or dry powder; quarantined readings add no sum; nothing reflects 2025 facts; and holdings appear only when a binding passed blind labels. These are exactly the kind of traps an agent would otherwise fall into.

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

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

Although the description is longer than average, every sentence earns its place: the first sentence front-loads the return contents, then each subsequent sentence clarifies a distinct interpretation risk (gaps, GAV, tape range, holdings visibility). There is no filler or repetition of annotation data.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 is responsible for explaining return values, and it does so thoroughly: reporting history, family sequence, commitment disclosures, holdings, events, accepted id types, data coverage period, and caveats. An agent has enough information to call the tool and correctly interpret the response for a read-only lookup.

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

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

Schema description coverage is 100%: the schema already documents dfx_id as accepting a dfx:ref:<uuid> vehicle id, an 805-ADV fund id, or an 021-Form D file number. The description merely repeats these accepted id forms without adding syntax details, constraints, or examples beyond what the schema provides, so baseline 3 applies.

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

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

The description opens with 'The vehicle card with its reporting history year by year' and then enumerates the exact contents: GAV, owners, minimum investment, fund type/name, family sequence, public plan commitments, validated holdings, and events. This clearly distinguishes get_re_fund_vehicle from siblings like search_re_fund_vehicles and get_re_fund_manager by naming a specific resource and its scope.

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

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

The description provides useful context—accepted identifier formats, the 2011–2024 tape range, and the meaning of gaps—but it never explicitly tells an agent when to choose this tool over alternatives such as search_re_fund_vehicles or get_re_fund_trends. There is no when-to-use / when-not-to-use guidance, leaving the routing decision partly 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 far beyond the readOnlyHint/idempotentHint annotations by disclosing exactly what is included, how employment history is ordered, how firm changes are represented, and what is withheld (book size, disclosure flags, outside business text, street addresses). It also states a plain factual limitation: no book size is public or estimated. This is rich behavioral context.

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

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

The description is dense but every clause carries information: return fields, ordering rules, inclusions, exclusions, and accepted input. It is front-loaded with the core subject and content list, then caveats, then parameter guidance. No filler or repetition; the length is justified by the lack of an output schema.

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

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

With no output schema, the description carries the full burden of explaining the return value, and it does so thoroughly. It covers the main fields, the unusual employment-history formatting, labeling of bulk re-registrations and departures, team movement, and data exclusions. Nothing critical is missing for an agent to understand what it will get and what it will not get.

Complex tools with many parameters or behaviors need more documentation. 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 fully documents the single dfx_id parameter. The description repeats the same accepted-id formats without adding examples, formatting rules, or clarifications beyond the schema. This meets the baseline but adds little parameter-level value.

Input schemas describe structure but not intent. Descriptions should explain 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: retrieving one IAPD-registered advisor with the full set of returned fields. It distinguishes itself from sibling firm-level or search tools by emphasizing 'one' advisor and listing the exact record contents. An agent can tell this is the dedicated advisor-detail tool without opening another schema.

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

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

The context is clear: use this tool to get a complete profile for a single advisor, and the input requirement is explicit — a dfx:ria id or individual CRD number. It does not explicitly name alternatives or exclusion criteria relative to search_ria or resolve_ria_advisor, but the intent is unambiguous enough for correct 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?

Beyond readOnly/idempotent annotations, the description discloses concrete behavior: the 200-largest-fund scope, that links are identifier matches only, that precision by basis is not yet sampled, and that a name is never a basis. This materially improves the agent's ability to trust and interpret 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 description is a single dense paragraph with multiple embedded clauses, making it harder to scan. Every sentence adds content, but the structure could be broken up for readability.

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

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

With no output schema, the description does a good job explaining the output concept (links, bases, CRD/CIK, SEC fund id), the input forms, and a key limit (200 funds). It leaves some ambiguity about the exact result shape (e.g., whether it's a list of entities) but is adequate 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?

The schema describes dfx_id as an RIA graph id or CRD; the description reinforces and expands this by explaining accepted forms (dfx:ria:<uuid> from search_ria, resolve_name or search_entities) and the firm CRD. With 50% schema coverage, this compensation is useful, though 'limit' semantics are only indirectly addressed via the 200-fund check.

Input schemas describe structure but not intent. Descriptions should explain 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 function: returns identifier-based links from one RIA firm/fund to PE/VC/FO/sponsor graph entities, with the basis printed per link. The 'Answers...' sentence gives the concrete question it resolves, which distinguishes it from generic get_ria_firm or search 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?

Clearly scopes to 'one RIA firm (or one private fund)' and specifies accepted inputs (dfx:ria id or CRD). However, it doesn't name alternative tools or say when not to use it, so it lacks explicit exclusions relative to siblings.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive, closed world), the description adds substantial behavioral caveats: fact classes (reported vs derived), RAUM double counting affiliates, survivor bias before 2026-09-15, and 'Nothing here is predictive.' This is exactly the kind of disclosure that 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 description is long but extremely information-dense and each sentence contributes a distinct fact: content overview, page-per-section behavior, fact-class semantics, known data quirks, and input format. There is 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 single-parameter read-only tool with no output schema, the description covers the return structure at the necessary level, communicates important data caveats, and explains what the tool is not (non-predictive). There are no obvious gaps that would prevent 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?

The schema covers the parameter at 100%, so baseline is 3. The description adds value by specifying both accepted forms (dfx:ria:<uuid> or CRD string) and by naming the source tools that produce valid ids, which helps the agent construct a correct call.

Input schemas describe structure but not intent. Descriptions should explain 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 a specific verb and resource: returning 'the full card for one registered investment adviser' and enumerates the exact content sections (people flows, growth, offices, owners, affiliates, funds, teams, events, same_as links). This distinguishes it clearly from sibling tools like get_ria_trends or get_ria_practice by emphasizing completeness for a single firm.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clearly states the acceptable inputs (dfx:ria ids or CRD) and even tells the agent where those ids come from ('from search_ria, resolve_name or search_entities'). It implies usage when a full RIA firm record is needed, but it does not explicitly contrast with alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it explains that anomalies are 'a place to look, never a conclusion', that data quality rows are kept apart, that book size and revenue are never estimated, and that each derived metric comes with its formula. It also discloses the source, date, and rights class for contact data. This is substantial behavioral transparency, though it doesn't describe pagination or output size limits, which would be the only remaining gap.

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

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

The description is information-dense and front-loaded with the core purpose, but it is a single very long sentence (over 150 words) that packs many items into a comma-separated list. It is not poorly structured, but it would benefit from breaking the content into a short summary sentence followed by a bulleted list of what is included. Every item earns its place, but the lack of visual structure makes it harder for an agent to parse quickly.

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

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

For a read-only, single-parameter tool with no output schema, the description is remarkably complete: it enumerates the full set of returned content categories, explains the derivation of metrics, flags data quality handling, and specifies input formats. The only missing context is the output shape (e.g., whether results are returned as a single object or a nested structure) and any pagination behavior, but with no output schema and a single id input, the description covers nearly everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter dfx_id with its format and examples. The description adds value by explaining that the id can be either a dfx:ria:<uuid> or a CRD number as a string, and by naming the source tools (search_ria, resolve_name, search_entities) that produce valid ids. This goes beyond the schema's basic type/description, though the schema itself is already quite clear, so a 4 is appropriate rather than 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 opens with a clear, specific verb phrase ('What a practice looks like from what it filed') and enumerates the exact resource: one adviser's practice profile built from Form ADV fields, derived metrics, archetypes, peer group, anomalies, offices, retention, and public contact path. It distinguishes itself from siblings like get_ria_firm, get_ria_advisor, and search_ria_practices by focusing on the single-practice profile with derived analytics and anomalies. The title reinforces the scope, and the description's specificity leaves no ambiguity about what the tool returns.

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

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

The description states the input format explicitly ('Accepts a dfx:ria: id or a CRD') and names the source tools for obtaining that id ('from search_ria, resolve_name or search_entities'). It also clarifies what the tool is not for: it is a single-practice profile, not a search or a list tool, and it explicitly says advisor book size and revenue are marked UNKNOWN and never estimated, which prevents misuse. However, it does not explicitly name sibling alternatives or state when to prefer get_ria_firm vs get_ria_practice, 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.

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

Annotations already establish read-only, idempotent, non-destructive behavior; the description adds genuinely non-obvious caveats: counts are registration-date based, bulk re-registrations are excluded, RAUM sums double count affiliates, and the data is explicitly not predictive. This goes well beyond what annotations alone 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 description is front-loaded with the key concept and then packed with useful detail; every clause contributes meaning. It is dense and could be slightly easier to scan if broken into bullets, but it earns its length given the three-view complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 8-parameter tool with no output schema and no required parameters, the description covers view definitions, ranking semantics, filters, defaults, and data-quality caveats. It does not describe the response envelope or pagination/limit behavior, but an agent has enough to safely invoke and interpret a first call.

Complex tools with many parameters or behaviors need more documentation. 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 schema coverage at only 13%, the description rightly compensates by explaining what sort values and filters do in each view, and reveals the $100M RAUM default exclusion relevant to min_raum_usd. It does not explicitly map limit, min_advisors, or wealth_only, but the view text and self-descriptive enum values make most parameters inferable.

Input schemas describe structure but not intent. Descriptions should explain 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 aggregate-statistics resource and enumerates three concrete views (state_stats, flows, growth) with the metrics each contains. This clearly distinguishes the tool from entity-level get_ria_* and search_ria_* siblings without opening any schemas.

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

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

The description gives strong context for selecting among the three views and notes important exclusions and defaults, which implies when each view is appropriate. However, it never explicitly contrasts this tool with siblings like search_ria_changes or get_ria_firm, so when-to-use-vs-alternatives 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 convey readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds valuable behavioral context: the 'counted once per borrower held' deduplication, the resolution of PE ids through the credit graph's cross-reference, and the handling of inference-based attribution ('A pair whose weakest basis is an inference is an inference'). This goes beyond what annotations provide.

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

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

The description is dense and front-loaded with output metrics, but the opening sentence is a long run-on listing many fields with commas, making it harder to parse. It packs a lot of information into a few sentences, but a bulleted or more structured format would improve clarity without adding length.

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

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

With no output schema, the description must explain the return shape; it lists metrics but not their types, units, or how they relate to the parameters. It also omits semantics for 3 of the 4 parameters (sort, limit, min_borrowers). For a complex report tool with multiple configurable options, this leaves meaningful gaps for an agent trying 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?

Only dfx_id receives meaningful description in the schema, but the tool description does mention it accepts 'a private credit sponsor id or a private equity id' and explains resolution. However, sort, limit, and min_borrowers have no description in either the schema or the tool description, and with only 25% schema coverage, the description fails to compensate for these undocumented parameters.

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

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

The description states the tool returns 'Sponsor by lender pairs counted once per borrower held' and lists the exact metrics (borrowers, facilities, principal, quarters, etc.), making the purpose clear. It does not explicitly distinguish itself from sibling tools like search_sponsor_lender, though the 'get' vs 'search' naming and the report-style output imply a distinct role.

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

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

No guidance on when to choose this tool over alternatives such as search_sponsor_lender or search_sponsor_capital_providers. The description focuses on accepted inputs ('private credit sponsor id or a private equity id') and internal resolution, but never states the use case or exclusions, so an agent must infer when this report is appropriate.

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

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

Annotations already carry read-only and non-destructive signals, so the description adds useful behavioral/content context: 'all seven fund amounts kept apart and its lifecycle state', plus relationships, events, evidence, and cross-graph links. It does not contradict the annotations and does not need to repeat their safety profile.

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

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

The main purpose is front-loaded and the parenthetical breakdown is dense but useful. The final 'Accepts dfx:vc: ids' sentence is short but redundant/conflicting with the schema, preventing a perfect score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool, the description does a good job enumerating the returned card sections and accepted id type. However, it leaves the input-scope mismatch unresolved and gives no guidance on behavior for invalid or non-venture ids.

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

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

The schema covers the sole parameter thoroughly (100% coverage), so the baseline is 3, but the description asserts 'Accepts dfx:vc: ids' while the schema explicitly allows many graph id types. This contradicts rather than adds to the schema and could mislead an agent into rejecting valid inputs.

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

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

The description states a clear verb and resource: it retrieves 'the full card for any entity on the venture graph' and enumerates firm, person, fund, and portfolio company. This goes beyond the name and title, though it does not explicitly contrast with search/get siblings or resolve the dfx:vc-only scope.

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

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

The description implies usage when an agent has a dfx:vc id and needs the full entity card, and enumerates what that card contains. It never names alternatives or gives a when-not-to-use condition, which matters given the large sibling set of singular getters and search tools.

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

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

The description directly contradicts the openWorldHint=false annotation. The annotation indicates a closed-world assumption, meaning 'no result' is definitive, but the description says 'NO_MATCH means no observed path within budget, not that they are unconnected,' which is an open-world caveat. This inconsistency could mislead the agent about the certainty of negative results, making the tool's behavior unclear.

Agents need to know what a tool does to the 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 concise and well-structured: three sentences that front-load the core purpose, then provide hop-level details, and conclude with result interpretation. Each sentence adds distinct value without redundancy. There is no filler, and the most important information (purpose and scope) appears first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 graph-path tool with no output schema, the description covers the essential behavioral aspects: hop types, search direction, depth limit, and the meaning of NO_MATCH. However, it does not specify the exact return structure (e.g., ordered list of nodes/edges, whether multiple paths are returned, how sources are attributed). The absence of an output schema means the description should include more detail about the response format, but the given information is largely sufficient for basic 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?

The schema already provides detailed descriptions for from_dfx_id and to_dfx_id (covering the DFX graph types), and max_hops has default/min/max constraints. The description adds minimal meaning by clarifying that max_hops is the search depth ('Bidirectional search up to max_hops') and reiterating the default value, but it does not substantially enhance understanding of the parameters beyond the schema. With 67% schema coverage, the description partially compensates but not fully.

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

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

The description clearly states the tool's purpose: finding an evidence-backed path between two DFX IDs across all graphs. It specifies the hop types (published relationships with sources, SAME_AS identity links) and mentions the bidirectional search, which distinguishes it from siblings like search_relationships (which likely returns relationships for a single entity) and get_capital_paths (which focuses on capital flows). The verb and resource are specific and the scope is unambiguous.

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

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

The description implies the use case (finding connectivity between two known DFX IDs) and provides interpretation guidance for the NO_MATCH result. However, it does not explicitly mention alternatives or conditions for choosing this tool over siblings, nor does it state when not to use it. There is no exclusion or comparison with tools like search_relationships or verify, leaving the agent to infer when this tool is appropriate.

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

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

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 readOnlyHint, idempotentHint, and destructiveHint, so the description need not repeat those. It adds valuable behavioral context: ranking order (exact, prefix, word match), one row per entity, typical sub-200ms performance, and role consolidation across graphs. These details go beyond the annotations and help the agent anticipate 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 description is lengthy but information-dense, with the core action front-loaded and supporting details (graphs, ranking, performance, alternative) following logically. Every sentence adds value, though it could be slightly tightened without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 resolution tool with no output schema, the description covers the essential context: what it resolves, the graphs, ranking, performance, ordering vs get_entity, and the alternative for real estate. It doesn't describe the exact return structure, but that's acceptable given the absence of an output schema and the richness of other details.

Complex tools with many parameters or behaviors need more documentation. 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 75%, so most parameters have descriptions in the schema itself. The description adds minimal parameter-specific detail; it implies the 'name' parameter accepts partial words, but the schema already covers that. It does not explain 'limit' or enrich 'domain' beyond the schema's enum list. Baseline 3 is appropriate since the schema does most of the work.

Input schemas describe structure but not intent. Descriptions should explain 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 clearly states it resolves a firm, fund, person or company name to canonical dfx ids from a specific index, lists the covered graphs, and explicitly differentiates from resolve_organization for real estate. It names the resource (name to dfx ids) and the action (resolve), making it distinct from siblings like search_entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explicitly states 'The first call before get_entity', giving a clear ordering context, and names the alternative 'resolve_organization' for real estate. This provides both when-to-use and when-not-to-use guidance, leaving no ambiguity.

Agents often have multiple tools that could apply. Explicit usage 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 already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral detail beyond those flags: name-only resolution produces labeled candidates with resolved=false, firm matching tries current registration before prior ones, and the returned card matches get_ria_advisor's summary. This clearly sets expectations for the operation's edge cases and return behavior.

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

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

The description is compact and efficiently structured: it front-loads the primary purpose in the first sentence, then covers the critical caveat (name alone), the disambiguation order, and the relationship to get_ria_advisor. Every sentence adds value and there is no redundant or filler 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?

Given the rich annotations and high schema coverage, the description covers all essential behaviors needed to call the tool correctly: the matching logic, the name-only failure mode, the returned card format, and how to get history. No output schema exists, but the description adequately explains the return concept and the alternative for deeper detail.

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

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

Schema coverage is high at 83%, and the description adds meaningful interpretation of parameters: crd resolves directly, firm can be a name or CRD and is matched against current then prior registrations, and name alone is insufficient. This goes beyond the schema's short descriptions, though limit and state receive no additional clarification.

Input schemas describe structure but not intent. Descriptions should explain 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 and resource: 'Resolve an advisor by name AND a firm ... or by individual CRD, to one person card.' It distinguishes itself from siblings by explicitly noting that a name alone is never resolved, and by tying the output to get_ria_advisor's summary card, so an agent can tell it apart from related search and resolve 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 gives clear context for when to use this tool: it requires firm or CRD for one-person resolution and warns that name-only returns labeled candidates with resolved=false. It also recommends get_ria_advisor(dfx_id) for history, providing an alternative. It does not explicitly name sibling tools like resolve_name or search_people as alternatives, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so safety is covered. The description goes far beyond that by disclosing qualitative behaviors: 'commitment dollars repeat across reports' (data duplication), 're-ups are the plan's own words' (subjective labeling), 'estimates are labelled' (data quality), and 'nothing predictive is published' (no forward-looking statements). It also explains status semantics (COMMITTED vs DISCLOSED_HOLDING) and that 'a target is never an actual' – all non-obvious traits an agent must know.

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

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

The description is long but information-dense, with no filler. It front-loads the row contents and filters, then appends caveats. While it is a single run-on block rather than bulleted, every clause adds value. The structure is moderately scannable for an agent, though it could be split into short sections for clarity. Given the amount of domain-specific detail, this is appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 search tool with no output schema, the description covers return contents comprehensively, all key filters, sort options, and critical data-quality caveats. It explains status semantics and the meaning of 're-up' and 'first-time'. Pagination (cursor, limit) is only in the schema, but that's acceptable since it's a mechanical detail. The description sufficiently equips an agent to select and call the tool correctly, including knowing what factors to be cautious about when interpreting 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 54%, so many parameters lack inline descriptions. The description compensates by enumerating all filter dimensions (allocator, manager, fund, consultant, status, bucket, re-ups only, first-time only, since date) and clarifies semantics that the schema leaves ambiguous, e.g., manager is 'who backs this manager', and statuses carry specific date meanings. It also explains the sort options. Though it doesn't mention every parameter (limit, cursor) explicitly, it gives enough context that an agent can map its listed filters to 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 opens with a precise enumeration of what each row contains ('allocator, fund as printed, manager and fund resolved to the pe / vc graphs...'), the statuses and their meanings, and the filterable dimensions. It clearly identifies the tool as returning raw commitment rows from plan disclosures, distinguishing it from aggregated commitment tools like get_commitments. The verb 'search' plus resource 'allocator commitments' is explicit and matches the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 lists many filter options and explicitly states the data granularity ('One row per line of a plan's own disclosure'), but it never says 'use this when...' or names an alternative (e.g., get_commitments for aggregated totals). The sibling tool get_commitments likely provides aggregate commitments, but no explicit 'instead of' guidance is given. The caveats at the end ('A target is never an actual...') are more about data interpretation than usage conditions.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints, and the description adds valuable behavioral caveats: 'a target is never an actual, a disclosed holding is never an approval, commitment dollars repeat across reports... nothing predictive is published.' This materially informs the agent about data reliability and interpretation, going well beyond the structured annotations.

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

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

The description is dense but not bloated; every sentence contributes, with the core dataset definition front-loaded and entity_type behavior following naturally. It is long for a tool description, but the complexity of the tool warrants it, and the later caveat sentence earns its place by conveying important data-provenance warnings.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with 14 parameters and no output schema, the description is notably complete: it names the result shape (compact cards with dfx:al: ids, assets, funded status, targets, commitment counts), explains default query behavior, and warns about data semantics. It does not explain sort options, pagination, or filter behavior beyond entity_type, but those are partially self-evident from the schema and sibling patterns.

Complex tools with many parameters or behaviors need more documentation. 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 29% schema description coverage ablutions, the description compensates for the most important parameter, entity_type, by explaining the semantic difference between consultant, manager, and fund modes, and for query via alias-aware search. However, it leaves many other parameters (sort, state, allocator_class, with_policy, min_assets_usd, etc.) without added meaning, so the description only partially covers the parameter space.

Input schemas describe structure but not intent. Descriptions should explain 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 clearly identifies the tool as a search across the 'capital-owner graph' and explicitly enumerates the entity types it covers: allocators, consultants, managers, and funds. It goes beyond the tool name by specifying data sources (Census, Form 5500, IRS) and the meaning of each entity_type mode, making it immediately distinguishable from siblings like get_allocator or search_entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides clear internal routing guidance: it defines what happens with a bare query versus each entity_type value, so an agent knows which mode to choose. It does not explicitly contrast this tool with sibling search/get tools, but the entity_type distinctions supply strong contextual direction.

Agents often have multiple tools that could apply. Explicit usage 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 declare readOnly, idempotent, and non-destructive. The description adds valuable behavior: the 'first sight' ordering semantics, the exclusion of seeded rows unless include_seeded=true, and the use of next_since for polling. This goes beyond the annotations and clarifies the pagination model, which is essential for correct usage.

Agents need to know what a tool does to the 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 verbose with a long list of example change types ('Commitments and re-ups...', 'facilities marked down...') which adds color but is not essential for calling the tool. The core concept is front-loaded in the first sentence, but the subsequent examples and caveats could be trimmed. It's structured but not tightly 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?

There is no output schema, so the description should explain the return value. It mentions 'next_since' and lists change types, but does not describe the response structure (e.g., fields per row, pagination format). It also doesn't clarify the event_type parameter's allowed values or the limit's effect. For a tool with 6 parameters and no output schema, the description is moderately complete but leaves some operational details uncovered.

Complex tools with many parameters or behaviors need more documentation. 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 descriptions cover 4 of 6 parameters (graph, since, dfx_id, include_seeded), but limit and event_type lack descriptions. The tool description does not explain these parameters either, so the gap remains. The description mentions next_since but doesn't map it to the since parameter. Since the schema covers the main parameters and the description adds no new parameter semantics, a baseline score of 3 is appropriate.

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

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

The description identifies the tool as a change tape for three specific capital graphs (allocators, private credit, real estate funds) and explains it returns rows by first-seen date. This clearly distinguishes it from general search tools, though the purpose is implied rather than stated as a direct verb like 'retrieves changes'. The resource and scope are explicit, but it doesn't explicitly say 'returns a list of changes'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 context for polling ('Poll with the next_since the answer returns') and notes that seeded rows are excluded by default. However, it does not compare this tool to sibling alternatives like search_private_credit_changes or changes_since, nor does it state when NOT to use it. The usage is implied for polling changes on these graphs, but lacks explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it explains that principal held is a lower bound, that a BDC tagging no maturity contributes nothing, and that results are ordered by date. It also discloses the default window. This goes beyond the annotations without contradicting them.

Agents need to know what a tool does to the 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 a single dense paragraph that front-loads the core purpose and default window, then lists output fields and filters. Every sentence earns its place: no filler, no repetition of schema details, and the key behavioral caveats (lower bound, no-maturity exclusion) are included without bloating the text.

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

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

For a read-only search tool with 7 optional parameters and no output schema, the description covers the essential semantics: what is searched, what is returned, the default window, and the filters. It does not describe pagination behavior or the exact format of the cursor, but those are standard and the schema covers cursor. The main gap is that it doesn't explicitly state the relationship to debt_maturity_schedule, but the description is otherwise complete enough for an agent 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 description coverage is 43%, so the description must compensate for undocumented parameters. It does: it explains the window concept (months, from), the filters (sponsor, lien, minimum principal), and the meaning of the output fields. It does not explicitly explain cursor or limit, but those are pagination parameters whose semantics are standard and partially covered by the schema (cursor has a description). The description adds real meaning beyond the schema.

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

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

The description states a specific verb ('search') and resource ('debt facilities on a BDC schedule whose maturity falls inside a window'), and clearly distinguishes it from siblings like debt_maturity_schedule by focusing on facilities still on a BDC schedule with tagged or written maturity. It also names the default window and the output fields, so an agent can tell exactly what this tool returns.

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

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

The description implies when to use it: when you need facilities maturing inside a window, with filters by sponsor, lien, and minimum principal. It does not explicitly name alternatives or exclusions, but the sibling list includes debt_maturity_schedule and get_borrower_facilities, and the description's specificity about 'still on a BDC schedule' and 'tagged or written maturity' gives enough context to select it. A clear when-not-to-use statement would push this to 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns compact cards with stable dfx ids and a per-domain coverage note, and it trades depth for breadth. It doesn't disclose pagination or default sort behavior, but the schema covers limit/cursor.

Agents need to know what a tool does to the 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 a single, information-dense paragraph that front-loads the core value proposition and then lists the filter categories. It is slightly long but every sentence adds context about scope, output, or trade-offs. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 broad search tool with 19 optional parameters and no output schema, the description gives a good sense of scope and output format, but it doesn't explain the semantics of the many optional filters or the pagination/response shape. The annotations cover safety, and the schema covers parameter names, but the description doesn't fully compensate for the 21% schema coverage.

Complex tools with many parameters or behaviors need more documentation. 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 21%, so the description must compensate. It does mention the key filter categories (entity_type, domain, state, sector) and the name query, but it doesn't explain the meaning of many other parameters (min_aum_usd, recent_activity_days, has_sponsor_relationships, etc.). The description adds some value by framing the filter groups, but the low coverage leaves a gap.

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

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

The description states a specific verb ('search') and resource ('every DFX domain at once'), enumerates the domains covered, and explicitly contrasts itself with the per-domain searches. This clearly distinguishes it from the many sibling search_* 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 clearly conveys when to use this tool: when you want breadth across all domains in one query. It also notes the trade-off ('fewer per-domain filters than the domain searches'), which implies when not to use it. It doesn't explicitly name a sibling alternative, but the contrast with 'domain searches' is sufficient.

Agents often have multiple tools that could apply. Explicit usage 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 communicate read-only, idempotent, and non-destructive behavior, so the description only needs to add context. It usefully adds that results are "Ordered and windowed by when events occurred" and that "Routine 13F position and fund-reporting noise is excluded unless asked for," which clarifies how the exclude_routine filter behaves.

Agents need to know what a tool does to the 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 one dense sentence but front-loads the core identity and uses the long list of event types to convey real scope. Every clause adds information; it is slightly list-like but not padded. It earns a high score because the detail replaces the missing output schema context.

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

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

There is no output schema and 10 parameters, so the description carries a heavy burden. It provides a solid orientation and covers most filter dimensions, but it omits value formats, event_type enumerations, output shape, and pagination behavior. It is adequate for initial selection but not fully complete for nuanced 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?

Schema description coverage is only 30%, so the description must compensate. It does map several parameters semantically — "domain, subject dfx_id, event_type, state, significance and window" — and the event-type list gives meaning to event_type. However, signal_family is never explained, and min_significance and window are only hinted at rather than precisely defined.

Input schemas describe structure but not intent. Descriptions should explain 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: "Dated events across family offices, sponsors, venture, private equity and real estate" and enumerates concrete event types. It distinguishes itself from the many domain-specific sibling change tools by emphasizing the cross-domain "change tape" scope and by noting the ability to filter by domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 broad usage: this is the general cross-domain event search, and it says "Filter by domain, subject dfx_id, event_type, state, significance and window." However, it never tells an agent when to prefer this over domain-specific siblings like search_private_credit_changes or search_capital_changes, and it offers no explicit when-not-to-use 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 already carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the data is 'observed' and 'dated', amounts are 'where disclosed (with basis)', and results include source quotes. It also warns that this is evidence-based rather than exhaustive. This context helps an agent calibrate reliability of results, which is valuable on top of the annotation safety flags.

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

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

Three sentences, each earning its place: the first defines the payload, the second lists filters, the third states the value proposition. The structure front-loads the core meaning. It is slightly list-heavy but not bloated; each field named is substantive. It could be tightened by trimming redundant filter names, but overall it is appropriately 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?

For a search/read tool with 8 optional parameters and no output schema, the description covers what an agent needs: it names the return fields (target, sector, asset class, structure, control, lead, amounts, board seats, exits, source quote), the filters, and the caveat on disclosed amounts. The schema fills in parameter details (enum options, id formats, include_candidates behavior), so the combination is sufficient to invoke correctly. It does not mention pagination or default limit, but those are minor for this tool type.

Complex tools with many parameters or behaviors need more documentation. 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 63%, so the schema already documents several parameters (since, state, office_dfx_id, investment_kind enum values, include_candidates behavior). The description reinforces the mapping by listing 'sector, asset class, state, kind or since-date' as filter options, which helps connect natural-language filter concepts to parameters. However, it adds little beyond the schema: 'limit' is unexplained (though self-evident) and no new semantics are introduced for the more opaque parameters like asset_class or sector.

Input schemas describe structure but not intent. Descriptions should explain 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 specific verb and resource: 'Dated investments family offices have been observed making' and then enumerates the data dimensions (target, sector, asset class, structure, control, lead/participant, amounts, board seats, exits, source quote). This clearly distinguishes it from siblings like search_family_offices (which would return office records) and search_vc_investments (venture-specific). The closing phrase 'The evidence behind "this office backs X"' crystallizes the tool's purpose.

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

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

Usage is implied rather than explicit: the description tells you what filters exist ('Filter by office, sector, asset class, state, kind or since-date') and the use case ('evidence behind this office backs X'), but it never states when to choose this tool over alternatives like search_vc_investments or search_allocator_commitments, nor does it mention exclusions or prerequisites. That is adequate but leaves the agent to infer the decision boundary from resource names.

Agents often have multiple tools that could apply. Explicit usage 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 the safe read-only, idempotent, non-destructive profile. With no output schema, the description carries the return-value burden and does so by enumerating the card fields and the dfx:fo: id format, plus disclosing the exclusion of people and individual investments. It stops short of describing pagination or limit behavior.

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

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

It is dense but front-loaded: card contents first, then filters, then the return id convention, then the exclusion. The card-field enumeration is long but earns its place given the absent output schema; there is no filler.

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

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

For a 14-parameter tool with no output schema, the description gives an adequate picture of returns and filters but leaves several filter parameters (cursor, sort, limit, asset_class) unexplained and does not address pagination. It is workable but not complete.

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

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

Schema coverage is only 43% across 14 parameters, so the description should compensate, and it partly does by naming the filterable axes (state, sector, direct investing, recent activity, AUM). But it omits city, sort, class, limit, cursor, query, asset_class, has_real_estate, and has_sponsor_relationships, leaving roughly half the parameters documented only in 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 the resource (US family offices) and specifies exactly what the tool returns — compact cards with class/confidence, direct-investing flag, sectors, check size, deployment, and relationship counts. It also implicitly separates itself from siblings by stating 'People and individual investments are not on these cards,' though it never names the alternative 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 lists the usable filters (state, sector, direct investing, recent activity, AUM) and draws one negative boundary by excluding people and individual investments, which hints at routing. However, it never names alternatives such as search_family_office_investments, search_people, or get_family_office, so the when-to-use guidance stays 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 declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to repeat safety. However, it adds behavioral context about the output format (compact cards, labelled research list), how unverified firms are handled, and the special behavior with 'sector' (observed deals first). It doesn't disclose potential latency or pagination, but the extra context justifies a 3.

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

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

The description is dense but not overly long. It front-loads the core purpose and output format, then covers edge cases. The sentences are packed with information, but every part is relevant. Minor redundancy with annotations (readOnly) but no waste.

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

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

For a search tool with no output schema, the description gives a rich picture of what is returned: fields like verification status, classification, mandate summary, principals, vehicle count, and similarity counts. It also explains the behavior with unverified and sector. The remaining gap is not explaining the 'sort' parameter's effect on relevance, but overall it is complete enough for an agent.

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

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

Schema description coverage is only 33%, so the description carries extra weight. It explains the meaning of the 'sector' parameter (maps to eight verticals, falls back to mandate summary), 'include_unverified' (returns research list), and 'kind' (though not fully detailed). This adds significant value beyond the bare 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 clearly states the tool searches for verified independent sponsor firms, with a specific resource type and scope. It distinguishes itself from siblings by explicitly excluding capital providers and target companies, and by mentioning the 'dfx:isi:' id prefix, which helps differentiate from other entity-related 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 explains when to use the tool: for verified sponsors, and when to use the research list (with include_unverified). It also clarifies that capital providers and target companies are not included, which prevents misuse. However, it doesn't explicitly name alternatives like get_independent_sponsor or search_sponsor_deals for more specific queries.

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

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

Adds substantial context beyond the readOnly/idempotent annotations: results always carry the true match count beside the sample, an empty result names the filter that emptied it, dfx_id is a cross-entity handle rather than a display label, and the call is free. These are non-obvious behaviors an agent could not infer from structured fields.

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

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

Front-loaded with purpose then scope then behavioral guarantees, and every sentence carries information. The all-caps dfx_id paragraph is heavy-handed relative to its content, which costs it the top mark.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 10-parameter, no-output-schema tool, the description compensates by enumerating the returned fields (assessed value, gross building area, value per square foot, annual tax, year built) and the handle semantics. Nothing critical for correct invocation is left unstated.

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

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

Schema description coverage is already 100%, so the baseline is 3; the description adds value by explaining that limit sizes only the SAMPLE while true match count is always reported, and by clarifying the dfx_id semantics and the owner-occupancy exclusion rule. It does not, however, add format or ordering detail beyond the schema.

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

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

States a specific verb (search) and resource (assessor parcel layer) and lists the exact filterable dimensions. Explicitly distinguishes itself from the address path (resolve_address) with 'instead of one exact address' and 'without an address in hand'.

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

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

Gives a clear when-to-use rule ('the way to ask a QUESTION of the parcel layer without an address') and a hard precondition ('At least one filter is required'), plus 'Free'. It stops short of naming the sibling resolve_address outright as the alternative, so the routing 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds critical behavioral context: it explains what is NOT included (funds, people, transactions, scores with components) and clarifies that reported gross assets are NOT fund size or dry powder, preventing misinterpretation. It also mentions the classifier's state and confidence, which is useful behavioral nuance. No contradiction with annotations.

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

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

The description is a single dense paragraph that is front-loaded with the key information (what the cards contain) and then covers filtering and exclusions. It is comprehensive but not overly long; the structure could be improved with separators, but the content is necessary and efficient. A 4 is warranted because it says a lot without redundancy.

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

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

Given the tool's complexity (9 parameters, many enums) and no output schema, the description is fairly complete: it explains the card contents, the filter options, the meaning of size bands and class states, and directs to get_pe_firm for deeper data. However, a few details are absent: it doesn't explain the 'basis' for size band, the confidence details of the classifier, or the exact format of the return (e.g., pagination via cursor). But the description handles the most critical usage scenarios. A 4 is fair.

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

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

The schema description coverage is 89%, which is high, so the schema already documents most parameters. The description does not add much beyond the schema, but it does clarify the meaning of size_band (UNSIZED means no evidence, not 'small') and that class CANDIDATE_PE is not yet ruled on. Since coverage is high, a baseline of 3 is appropriate; the description adds marginal value but does not duplicate the schema extensively.

Input schemas describe structure but not intent. Descriptions should explain 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 clearly states it searches private equity firms and returns compact cards with specific fields. It explicitly distinguishes from get_pe_firm (for funds, people, transactions) and names alternative tools for family offices, independent sponsors, and venture firms. The verb 'Search' plus the resource 'private equity firms' is specific and differentiates it from sibling search 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 provides explicit when-to-use guidance: it is for private equity firms (management companies and advisers), not for family offices, independent sponsors, or venture firms, for which it names alternative tools. It also clarifies the scope of returns (cards, not funds/people/transactions) and directs to get_pe_firm for deeper data. This is exemplary usage 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 already carry read-only, idempotent, and non-destructive hints, so the safety profile is established. The description adds a meaningful behavioral caveat: that the Form ADV gross asset value is the reported gross assets and not fund size, commitments, or dry powder, which prevents misinterpretation of 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 description is a single paragraph of three sentences, front-loaded with scope and then enumerating return fields and filter criteria. It is efficient, though the field list is dense and some repetition of filter concepts exists.

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

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

Whttps://annotations already cover safety, and the description explains the key return fields and their semantics, which matters because there is no output schema. It doesn't mention pagination, cursor, or default sorting, but these are standard search parameters likely implied by the schema. The description is sufficiently complete for the tool's complexity.

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

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

The schema already contains descriptions for 6 of 10 parameters (60% coverage), so the description doesn't need to fully compensate. It repeats the filter list (name, manager, ADV fund type, vintage, lifecycle, minimum GAV) but provides little additional param-level semantics beyond what the schema gives. It also mentions 'manager' which isn't a defined parameter, adding slight ambiguity.

Input schemas describe structure but not intent. Descriptions should explain 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 clearly states a specific verb ('search'), the resource ('Funds on the private equity graph'), and the core output (amounts under their own names and bases). It lists concrete return dimensions and filter types, which distinguishes it from related siblings like search_pe_firms or search_vc_funds.

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

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

The description provides clear context that this tool targets private equity graph funds and enumerates the available filters and fields. It does not explicitly name alternatives or exclusion criteria, but the scoping is specific enough for an agent to select it over VC funds or firm search tools.

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

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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint false, the description adds genuine behavioral detail: 'returns what changed instead' when changed_since is used, 'Not predictions', and the important caveat that proposed owners and percentages are not returned as fact. No contradiction with annotations.

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

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

The description is a single dense paragraph that leads with the core purpose and states, then enumerates the output fields and caveats. Every clause carries meaning, but the long enumeration makes it slightly less scannable than a more structured list; still compact with no filler.

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

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

The tool has no output schema, so the description carries the burden of return format and it does so well: fields, record classes, state stages, and source. It also tells the agent what is not returned. The gaps are semantic explanations for the 'view' enum and the 'limit' parameter, which are either self-evident or and supplied by schema defaults. Overall it is complete for a niche search tool.

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

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

Schema covers tag, query, and changed_since with descriptions, while view and state have enums without descriptive text. The description enriches changed_since by explaining the return-mode shift and lists the states, but it does not explain the 'view' enum (what 'effective' vs 'withdrawn' means) or limit behavior. Given 50% schema coverage this partial compensation lands at a 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 official state records of pending skilled nursing facility ownership changes before they take effect. It names the states, enumerates the return fields (facility, CCN, beds, operators, record class, dates, evidence tags), and explicitly disclaims predictions, clearly distinguishing it from any generic search 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?

Clear context is given: use it for official pending ownership-change records in Kentucky, New York, Rhode Island, New Jersey, and Maine. The 'With changed_since...' clause explains a different invocation mode, and 'Not predictions' sets expectations. However, no sibling is explicitly called out as an alternative and no 'when-not-to-use' guidance is given, which prevents a 5.

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