tengu-firm

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

With no annotations provided, the description conveys that data is fetched in parallel and returned as a single bundle, listing the exact data categories. However, it does not explicitly state that this is a read-only operation with no side effects, nor does it disclose potential limitations like partial data availability for illiquid tickers. Still, the behavioral traits disclosed (parallel fetch, bundle composition) are useful and go beyond the name.

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

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

Two sentences: the first enumerates the bundle contents and the parallel fetch behavior, the second delivers the primary-use directive. Every word earns its place, no filler, and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 one parameter and no output schema, the description covers the essential context: what data is included and when to use it. It could mention that the response is read-only or that some bundles may lack data for certain tickers, but given the simplicity and list of components, the description is nearly 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?

The input schema already documents the single 'ticker' parameter (100% coverage), so the baseline is 3. The description only reiterates 'for a ticker' and adds no extra meaning about formatting (e.g., ticker symbol vs. company name), case sensitivity, or accepted exchanges. It essentially relies on the schema's minimal 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 states a specific action ('One-shot fundamentals bundle for a ticker') and enumerates exact included components (metrics snapshot, TTM income, balance sheet, cash-flow, company facts, insider trades, institutional holders). It clearly distinguishes itself from sibling tools that fetch individual pieces, making the purpose unambiguous.

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

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

Explicitly identifies the primary use case: 'PRIMARY tool for "give me the full fundamental picture of X"' and instructs to call it instead of assembling pieces individually. This provides clear when-to-use guidance and implicitly excludes scenarios where only a specific data slice is needed.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It explains that the tool returns a 'single TTM row'—indicating a bounded, read-only result—and describes the content as 'valuation and quality ratios,' giving the agent a clear expectation of what to deliver. However, it omits potential edge cases like missing data or symbol validation, but these are not critical for such a simple read operation.

Agents need to know what a tool does to the 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 two concise sentences. The first sentence defines the tool's output clearly and the second provides usage and alternative. Every sentence earns its place with no fluff or repetition. Highly front-loaded with the essential 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 the tool's simplicity—one parameter, no output schema, no annotations—the description is remarkably complete. It states the exact output structure ('a single TTM row'), the content type ('valuation and quality ratios'), and gives concrete examples ('P/E, profitability'), while also covering when to use it vs. the alternative. An agent can confidently select and invoke this tool based on this description alone.

Complex tools with many parameters or behaviors need more documentation. 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 has one parameter 'ticker' with 0% description coverage, so the description must compensate. It does mention 'for a ticker' in the first sentence, which minimally clarifies the parameter's role, but it does not add format details (e.g., uppercase, exchange suffix) or constraints. For a single self-explanatory parameter, this is adequate but does not go beyond what the schema suggests.

Input schemas describe structure but not intent. Descriptions should explain 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 with a specific verb and resource: 'Latest financial-metrics snapshot for a ticker — a single TTM row of valuation and quality ratios.' It explicitly differentiates itself from the sibling tool 'fundamentals_metrics' by contrasting snapshot vs. per-period history, making it distinguishable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: 'Call this for a quick "what's the P/E, how profitable is X right now?" check.' It also names the alternative tool to use for different needs: 'use fundamentals_metrics when the user needs the per-period history.' This fully meets the usage guideline criteria.

Agents often have multiple tools that could apply. Explicit usage 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 no annotations, the description carries full transparency burden and succeeds. It discloses the critical ambiguity that several crypto symbols are also US-listed equity tickers, warns that a bare ticker returns the equity, and instructs the agent to 'Check is_stale before using the price'. These are substantial behavioral details not present in the schema.

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

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

The description is front-loaded with the core purpose and then flows into usage triggers, history alternative, crypto handling, and staleness check. Every sentence earns its place with high signal and no repetition or filler.

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

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

Given no annotations and no output schema, this description is complete: it explains what the tool returns, when to use it, which alternative covers history, how to avoid the crypto/equity trap, and what to check before trusting the price. An agent has everything needed to select and 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 0%, but the description compensates exceptionally. It explains the asset_class parameter with examples ('pass asset_class=crypto for BTC/ETH/SOL/LTC/LINK'), and clarifies the default equity behavior of bare tickers, adding crucial meaning to both ticker and asset_class beyond the raw enum/default.

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

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

The description opens with 'Latest quote for one ticker — last trade plus the current daily bar', which clearly identifies the resource (one ticker), the action (quote), and the return content. It also distinguishes itself from history-related siblings by explicitly sending those requests to /fundamentals/prices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides direct usage triggers: 'Call this when the user asks what the price is now or how the stock is moving today' and names the alternative for history. It also includes crypto-specific instructions, telling the agent to pass asset_class=crypto and never use an equity price for a crypto asset.

Agents often have multiple tools that could apply. Explicit usage 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 no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context by distinguishing a 'realtime cross-ticker feed' from a 'bulk alternative-data feed' and noting the default provider. However, it does not discuss output format, pagination, data coverage limitations, or any potential side effects, leaving gaps for an agent to discover at runtime.

Agents need to know what a tool does to the 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 two sentences, with the main subject and scope front-loaded. Every clause adds value: data source, provider options, default, ticker filter, and explicit usage context. No fluff or 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 has no annotations and no output schema, the description reasonably covers purpose, usage, and two of three parameters. Yet it omits the meaning of 'limit' and does not describe the shape of the returned trade records (e.g., fields like date, amount, party), which would be useful for an agent to set expectations. It is adequate for selection but slightly incomplete for full invocation understanding.

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

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

The input schema has no property descriptions (0% coverage), so the description must compensate. It does so by explaining the provider parameter with its enum values ('options_flow' realtime, 'alternative_data' bulk) and by clarifying that ticker is an optional filter. However, the limit parameter is not explained in the description, leaving its purpose to be inferred from the schema's min/max/default values.

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

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

The description clearly states the tool returns congressional stock trades from two named coverage sources, with an optional ticker filter. It identifies the specific resource (congressional stock trades) and implicitly the function (retrieval), distinguishing it from sibling tools like tengu_v3_intel_politicians by focusing on trade transactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 says 'Call this when the user asks what Congress members have been buying or selling, market-wide or in a specific name.' This gives a clear trigger condition. However, it does not mention when not to use it or name alternative tools for related queries (e.g., political contribution data), so it lacks explicit exclusions or alternatives.

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

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

With no annotations, the description carries the transparency burden. It discloses several key behaviors: returns recent snapshots, limits to roughly 10k rows, supports substring matching on ticker and fund, and provides alternative-data institutional ownership. It does not mention pagination or ordering, but that is a minor gap for a simple lookup tool.

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

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

The description is two sentences, front-loaded with the core purpose and output fields, followed by a concrete use-case and filtering guidance. Every phrase adds value with no filler or restatement of the tool 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?

Despite no output schema, the description compensates by listing returned fields and explaining row-cap and filtering semantics. It does not discuss how this tool relates to sibling sec13f tools or the exact behavior of the limit parameter, but the core query scenario is well covered and sufficiently complete for an agent to use 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?

The schema has no parameter descriptions, so the description adds meaning by explaining that ticker and fund are filters with substring matching. While the limit parameter is not elaborated, its name and schema constraints (default 50, max 500) make it self-explanatory, and the description covers the two most behaviorally important filters.

Input schemas describe structure but not intent. Descriptions should explain 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 retrieving recent 13F position snapshots and enumerates the output fields (fund, ticker, shares, value_usd, report_period). It differentiates from related tools by emphasizing 'cross-fund/cross-ticker' and 'last ~10k rows', and ties the purpose to concrete user queries like 'which funds hold X?' and 'what does fund Y own?'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage triggers with natural-language examples, making it clear when to invoke this tool. It does not explicitly name alternative tools such as sec13f_changes or sec13f_history, but the focus on 'recent snapshots' and 'cross-fund/cross-ticker' implicitly differentiates its scope.

Agents often have multiple tools that could apply. Explicit usage 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 one behavioral disclosure: 'Warm means requested, not provider-confirmed,' implying the data may be unconfirmed. However, with no annotations, it fails to state whether the operation is read-only, cached, or has side effects, and it does not explain the nature of the 'heartbeat' or 'readiness' metrics.

Agents need to know what a tool does to the 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 two sentences with no filler. The first sentence is dense with domain terms but efficient, and the second sentence clarifies a key concept. It is front-loaded and 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?

With no output schema and no annotations, the description is the sole guide. It lists the main data areas but leaves terms like 'capacity' and 'effective readiness' undefined, and it does not differentiate from adjacent status/universe tools. It is minimally adequate for a no-argument status tool.

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

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

There are zero parameters, and the schema is empty, so the baseline is 4. The description correctly does not attempt to explain parameters that do not exist.

Input schemas describe structure but not intent. Descriptions should explain 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 providing a 'warm-set catalog' plus producer heartbeat, research-universe count, capacity, and readiness, but it lacks an explicit action verb like 'get' or 'report.' It avoids being a tautology and is richer than the name alone, yet it does not clearly distinguish itself from sibling tools such as `tengu_v3_universe_scan` or `tengu_v3_stream_universe_status`.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 is given on when to use this tool versus alternatives, and no use cases or exclusions are mentioned. The only additional sentence defines 'warm' but does not help with tool selection.

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

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

With no annotations, the description carries the transparency burden and adds valuable behavioral details: the tool has a 60s TTL, uses a minutes parameter defaulting to 60, and is meant only as a drill-down. It doesn't cover rate limits or output format, but for a read-only news fetch the disclosed constraints are sufficient.

Agents need to know what a tool does to the 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 front-loads the critical warning 'DRILL-DOWN ONLY' and packs purpose, usage, parameters, default, and TTL without waste. Every clause earns its place.

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

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

Despite having no output schema and only two simple parameters, the description fully covers what the tool does, when to use it, how to use it (drill-down only), and operational specifics (TTL, default). It is complete for the tool's complexity level.

Complex tools with many parameters or behaviors need more documentation. 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 0%, so the description compensates by explaining that 'one ticker' is the subject and 'minutes param' is a lookback window with a default of 60. It doesn't restate min/max (already in schema) and adds contextual meaning to 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 clearly states the tool returns 'Raw newswire headlines for one ticker over a lookback window', which is a specific verb+resource. It also distinguishes itself by explicitly warning 'DRILL-DOWN ONLY — never a first-round call' and names the sibling tengu_v3_news_summary, so it is not confused with similar 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 explicitly states when to use the tool ('when the summary's stories are insufficient or you need a tighter time window') and when not to ('never a first-round call and never alongside tengu_v3_news_summary'). This is exceptional guidance with a named alternative.

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

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

With no annotations provided, the description carries the transparency burden. It discloses that the tool performs a 'single parallel fetch', has a '90s TTL', and returns specific content categories. It also admits the possibility of returning 'nothing useful'. While it doesn't detail failure modes or rate limits, these disclosures add meaningful 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 two sentences and front-loaded with the core purpose. Every phrase earns its place: 'one-shot', content list, TTL, primary tool status, and the explicit warning against stacking tools. 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 tool with one parameter, no output schema, and no annotations, the description fully covers what the tool returns (stories, sentiment, trending, events, analyst actions) and how to use it. It effectively resolves ambiguity among numerous sibling news tools, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for the single 'ticker' parameter, and the schema already describes it as a required path parameter. The description adds no additional format or usage detail, but none is needed given the parameter is self-explanatory and fully documented in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'One-shot news intelligence for a ticker'. It enumerates the content areas (recent stories, sentiment stats, trending status, structured events, analyst actions) and explicitly distinguishes it from siblings by calling it 'THE primary tool' for single-ticker news questions.

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

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

Guidelines are explicit: use this tool for 'what's the news on X?', and directly instructs the agent to not stack other news tools unless this one returns nothing useful. This provides clear when-to-use and when-not-to-use guidance, including a fallback condition.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the data scope thoroughly and clearly implies a read-only profile lookup, but says nothing about auth, rate limits, or cost of the call. Given zero annotation support, this is good but not exhaustive.

Agents need to know what a tool does to the 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 returned-data inventory is front-loaded and the routing hint follows, with no filler. It is dense but every clause adds usable information; a slightly tighter structure would earn a 5.

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

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

With no output schema, the description does the heavy lifting by enumerating returned fields (financials, financing history, classification, contacts, hierarchy, tickers), so an agent knows what it gets. It stops short of confirming read-only semantics and identity/type constraints on company_id, leaving a small gap.

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

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

Schema coverage is 100%, so both companyid/company_id and the alias behavior are already documented in the schema. The description only restates 'by company_id' and adds no format, sourcing, or resolution detail beyond what the schema provides. Baseline 3.

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

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

States a specific verb+resource ('FULL private-company profile by company_id') and enumerates exactly what the payload contains (financials, financing history, classification, HQ/contact, hierarchy, cikcode/ticker). This clearly distinguishes it from the search/list siblings that return lighter records.

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

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

Explicitly prescribes the workflow: resolve the id first via search_suggest, then call this for the 'deep dive on one company.' That gives an agent a clear when-to-use trigger. It only names one alternative and gives no explicit when-not guidance, so it stops short of a 5.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses the newest-first ordering and the scope of returned data, but says nothing about permissions/auth, rate limits, or how pagination pairs with limit. Adequate but incomplete for a read tool with zero structured hints.

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

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

Two sentences, front-loaded with the resource and data scope, then the routing rule. Zero filler; every clause earns its place.

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

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

With no output schema, the description correctly enumerates the return fields and ordering, which is what an agent needs to judge relevance. The only gap is behavior around limit/pagination, a minor omission for this simple 3-parameter 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 coverage is 67% and the schema itself documents company_id, its companyid alias, and limit bounds/defaults. The description adds no parameter detail at all — the listed fields (deal size, type, valuation) are outputs, not inputs — so it neither compensates for the coverage gap nor repeats the schema.

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

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

States a specific resource (private-company funding-round and M&A deal history) with the fields returned (deal size, type, VC round, pre/post-money valuation) and sort order, and explicitly contrasts itself with a sibling (/investors). An agent can distinguish this from tengu_v3_private_markets_company without opening a schema.

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

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

Gives explicit trigger phrasing ('when did X last raise / at what valuation / who acquired it') and names the alternative tool (/investors) with the condition that selects it ('who participated'). Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does well: money ships as both a raw '_musd' float and a formatted '_display' string, every series is sorted ASCENDING for charting, the hero valuation badge is computed server-side, and 'blocks degrade independently' signals partial-failure behavior. It omits auth/permission requirements and error semantics, but the disclosed traits go well beyond anything in the schema.

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

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

Dense but front-loaded: the payload contents come first, then data-format guarantees, then the routing rule. Every sentence conveys distinct information. The em-dash-heavy list is slightly expensive to parse but nothing is filler.

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

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

For a tool with no output schema, no annotations, and only 40% param coverage, the description does substantial work describing the returned blocks and their independent degradation. However, it leaves the tab/team/deals parameters unexplained, which is a meaningful omission for an agent choosing arguments.

Complex tools with many parameters or behaviors need more documentation. 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 40% and the description never explains the five parameters. The 'tab' selector, the 'team' and 'deals' caps (defaults 60/200, max 500), and the company_id/companyid alias — which the schema does cover — receive no added meaning. Only 'team roster' obliquely hints at what 'team' controls. This is a real gap for a 5-param tool.

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

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

States a specific verb+resource — 'The private-company DETAIL PAGE in ONE call' — and enumerates the concrete blocks returned (identity, key facts, tapes, financing-in-progress, team roster). It differentiates itself from the analytical fan-out and live overlay routes, though it names endpoint paths ('/dossier', '/realtime') rather than the sibling tool names, leaving a small mapping gap for the agent.

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

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

Gives an explicit use-this/not-that rule: 'Use this for a company PAGE; use /dossier for the analytical fan-out … and /realtime for live overlay.' That is clear routing guidance with alternatives named. It stops short of stating prerequisites or when the tool is a poor fit for a nonexistent company_id, and the alternatives are paths rather than tool identifiers.

Agents often have multiple tools that could apply. Explicit usage 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 no annotations provided, the description takes on full responsibility for behavioral disclosure. It reveals important traits: prefix matching, case-insensitivity, relevance ranking, brand/AKA awareness (with concrete examples), and the behavior of type=all and detail=full. However, it doesn't mention rate limits, pagination, or the exact output shape, which would further improve transparency.

Agents need to know what a tool does to the 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 serves a purpose. It starts with the search scope and behavior, then gives usage guidance, then clarifies key parameter options. No redundant or tautological content; it's well-structured and efficiently worded.

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

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

Given the lack of output schema and annotations, the description is fairly complete for a search tool: it covers the entity types, search fields, ranking behavior, and the downstream workflow. The `fields` parameter and exact return columns are not described, but the tool's role as an entity-resolution first step is clear enough for an agent to use it effectively.

Complex tools with many parameters or behaviors need more documentation. 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 0%, so the description must compensate. It explains q via 'by name (prefix, case-insensitive), ticker, or CIK,' clarifies type=all, and explains detail=full. However, `limit` and especially `fields` receive no explanation in either the schema or description, missing an opportunity to fully cover all 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 clearly states the tool's purpose: searching private companies, investors, funds, people, and LPs by name, ticker, or CIK, with relevance ranking. It also differentiates itself from siblings by positioning it as the FIRST-step entity resolution tool, explicitly noting to 'resolve the entity id' before calling company/dossier/realtime 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?

Explicit guidance is provided: 'Use this FIRST for any private-company question' and 'then call the company/dossier/realtime tools.' This tells the agent exactly when to use this tool and how it fits into the workflow, distinguishing it from the many sibling private market tools.

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