agentic-ai

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

With annotations already declaring readOnlyHint=true, openWorldHint=true, and destructiveHint=false, the description adds substantial context: SEC-verified citations versus caller-asserted context, $25/call pricing, and ~60s latency. These are meaningful behavioral details an agent needs before invoking an expensive, long-running analysis.

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 supplies the lens list, optional inputs, and commercial/runtime facts. It is appropriately sized for a flagship expensive tool, though the long lens enumeration and dense opening sentence keep it from being maximally 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 complex report-generation tool with no output schema and sparse parameter documentation, the description covers the report structure, provenance, optional inputs, cost, and expected duration. It does not describe the returned format or citation layout in detail, leaving a modest completeness 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 description coverage is 0%, so the description must compensate, and it does for the optional parameters: it gives a concrete market example and explains that context is caller-supplied deal material treated as unverified. Ticker is self-evident, though the market object's accepted keys and context string constraints are not fully specified.

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 a specific resource and output: an eight-lens institutional analysis of a US-listed company grounded in SEC-verified figures. It is unmistakably different from siblings such as sec_extract or validate_financials, but it never explicitly contrasts itself with those alternatives, 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 lens list and 'flagship' framing imply when this tool is appropriate, and it explains how optional market/context inputs extend the analysis. However, it gives no explicit when-not-to-use guidance and does not name sibling tools as alternatives for narrower tasks like raw SEC extraction or validation.

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 readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-recoverable context: the pricing model ('$2.00/call after free trial') and the fact that the call produces a risk register, thesis, and conditional rNPV band. It does not mention runtime, failure modes, or what a low-quality deal profile yields.

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

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

A single sentence with a front-loaded arrow chain that mirrors the actual processing order, plus parentheticals for the conditional case and the price. No filler and nothing repeated from the title or annotations.

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 high-complexity, paid, nested-object tool with no output schema, the description does well on deliverables and cost. However, the entire input contract for the deal profile is absent, and an agent cannot know whether a partial profile is acceptable or how scoring degrades without `indications`-type fields.

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% and the single `deal` parameter is an untyped nested object with additionalProperties=true, so the agent has no documented shape for the deal profile. The description contributes only one hint, that biotech deals carry an `indications` field. Required fields, accepted keys, and the effect of missing data are all left undocumented in both places.

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

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

The description names the operation (a full underwriting chain on a deal profile) and enumerates the concrete stages and artifacts produced: financial integrity, trend, industry position, stress tests, conviction score, risk register, investment thesis, and an rNPV band. That is far more specific than the title alone. It stops short of differentiating itself from the closest sibling, validate_financials, which plausibly overlaps with the 'financial integrity' stage.

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

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

Usage is only implied: the agent can infer this is the deep-dive tool for scoring a deal, and the parenthetical clarifies the biotech case where `indications` is present. There is no explicit when-to-use/when-not guidance and no routing to validate_financials or company_report, which are the obvious cheaper alternatives for a subset of this work.

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 context annotations can't carry: it is free with no API key, covers 93,000+ funds, and deliberately withholds firm names and contacts. That privacy constraint and the free/no-auth claim are exactly the traits an agent needs before calling. It doesn't mention rate limits or latency, keeping it off a 5.

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

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

Front-loads the free/no-key signal and the use case, then flows into mechanics, enum values, and the upsell path. Small inefficiency in restating 'asset_class is one of...' as a bare list, but no sentence is wasted.

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

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

With no output schema, the description correctly explains what comes back (match counts by investor type, no contacts), which is the key unknown. The gaps on industry/geography/ebitda_m are the only thing keeping it from 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 0%, so the description must compensate and it only partly does: it enumerates the ten valid asset_class values (absent from the schema) and gives units for target_raise_m. It says nothing about industry, geography, or ebitda_m, leaving three of five parameters undocumented anywhere.

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 (preview investor matches), the underlying engine and dataset (DEALITHIC, 93,000+ funds/family offices/angels), and the exact output shape (counts, no names or contacts). An agent can distinguish it from request_intro and lp_match_preview 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?

"Use when someone wants to be connected with investors for a raise" gives a clear trigger, and the closing sentence routes the agent to request_intro when the preview looks useful. It does not state when NOT to use it (e.g. versus lp_match_preview for LP-side queries), so it stops short of full routing coverage.

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

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

Beyond the readOnly/closed-world annotations, the description discloses that the call is free and needs no API key, that output is counts only with no names or contacts, and that counts are not yet scored against strategy or fund size. These are the limitations an agent most needs to represent the result honestly.

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 cost/free signal and the use case, then output semantics, then parameter notes, then the alternative. Every sentence adds information an agent can act on.

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

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

For a 3-parameter read-only preview with no output schema, the description fully covers return shape (counts per LP type, no contacts), the key caveat (unscored), units, and the escalation path. Nothing needed to invoke it correctly is missing.

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

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

With 0% schema description coverage, the description carries the burden and does well: it specifies target_fund_size_m is in USD millions, that lp_types optionally narrows types, and it enumerates the six LP type values that the schema lacks as an enum. It leaves fund_strategy's expected format unstated, keeping it just short of a 5.

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

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

The description states a specific action (preview LP matches) and precisely what is returned: counts of LP-type investors per LP type, no names or contacts. It also distinguishes itself from the follow-up tool request_lp_intro, so an agent can route correctly 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?

It names the exact triggering scenario (a GP raising a fund wants to find LPs) and an explicit alternative path (offer request_lp_intro for a demo where specific LPs are released). Both when-to-use and the next step are stated, not inferred.

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 this is a non-read-only, non-idempotent, open-world write. The description adds genuinely useful context beyond that: it is free with no API key, it results in a demo booking where matched investors are revealed, and it requires explicit consent. It does not state what happens on duplicate submissions or what the response contains, keeping it out of 5 territory.

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 tight sentences, front-loaded with the key practical fact ('FREE, no API key') followed by what the tool does and the consent condition. No filler, though the demo/matched-investor clause adds a little promotional framing.

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?

Covers the critical consent gate and the outward-facing effect, which is the most important thing for a mutation tool with openWorldHint. However, with no output schema and five required fields, the description says nothing about what is returned, error conditions, or duplicate handling.

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% and all five parameters are required, so the description must carry the burden. It explains the semantics of 'consent' well (only true when the person agreed to be contacted), but name, email, company, and deal_summary are left with no explanation of expected format or content beyond their titles.

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

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

States a concrete verb+resource: 'Records a request to be introduced to DEALITHIC and booked into a demo.' An agent can tell this creates a booking request rather than fetching a report or score. It does not explicitly distinguish itself from the sibling investor_intro_preview, 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?

Gives an explicit precondition ('Only call this after the person has explicitly agreed to be contacted by email about their raise') and ties it to a specific field value ('set consent=true only in that case'). This is unambiguous when-to-call guidance with an implied when-not.

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=false, idempotentHint=false and openWorldHint=true, so the mutation profile is known. The description adds useful context beyond that — free, no API key, records a request, and a consent-gating rule — but doesn't say what happens after submission or whether the caller gets a reference back.

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, zero padding, with the access constraint ('FREE, no API key') front-loaded and the consent rule last. Every sentence earns its place.

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

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

Covers purpose, cost, and the consent gate, which is the crucial operational detail for a 5-required-param mutation with no output schema. However, it leaves fund_summary's expected content and post-call behavior undefined, which an agent would want 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 0% across 5 required parameters, so the description must compensate. It clearly defines the semantics of 'consent' (only true with explicit email agreement), which is the riskiest field, but says nothing about what fund_summary should contain or expected formats for email/firm.

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: 'Records a fund manager's request to be introduced to DEALITHIC and booked into a demo about raising their fund from LPs.' This clearly separates it from read-only siblings like lp_match_preview or investor_intro_preview, though it doesn't explicitly name the closest alternative request_intro.

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 precondition: 'Only call this after the person has explicitly agreed to be contacted by email, and set consent=true only in that case.' This is a strong when-to-use rule. It stops short of naming alternatives (e.g., request_intro) for adjacent cases, so not a 5.

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

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

Annotations already establish readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered; the description adds genuinely new behavioral facts: every value carries filing/form/tag provenance, missing facts return null rather than 0, and each call costs $0.25 after a trial. It does not explain the shape of the returned payload (which statements, how many periods), which is a moderate gap given no 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?

Three short sentences, front-loaded with the resource and source, then the provenance/null guarantee, then price. Nothing is padding and the cost note is placed where an agent will see it before invoking.

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 lookup with no output schema, the description covers source, data guarantees, and cost. It falls short only on return structure (which statements or periods are included) and ticker format, both of which the agent would otherwise have to discover by calling.

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

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

There is one parameter and schema description coverage is 0%, so the description has to compensate. It clarifies that the ticker must be a US-listed symbol and that it maps to SEC EDGAR filings, but it never states the expected format (e.g. "AAPL" vs "NASDAQ:AAPL") or handling of delisted/ticker-changed symbols.

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 (extract) and resource (verified financial statements and derived metrics) plus the exact source boundary: US-listed tickers, SEC EDGAR XBRL filings. That source detail is enough to separate it from siblings like company_report or validate_financials without opening either schema.

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

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

Usage is implied by the source restriction (US-listed tickers), so an agent can infer when the tool applies, but there is no explicit when-to-use guidance and no statement of when to prefer a sibling such as company_report or validate_financials. The agent must reason from the surrounding toolset.

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 this is a safe read-only, non-destructive, closed-world operation, so the description isn't burdened with safety disclosure. It adds real value beyond that: the return shape (integrity score + severity-ranked flags) and, unusually, a pricing/rate-limit note ($0.50/call after free trial), which an agent needs for cost-aware invocation.

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 dense, front-loaded sentences: the check list first, then the return/cost note. No filler; every clause carries 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?

Annotations cover the safety profile and the description covers output shape and cost, but for a tool whose only input is an unconstrained nested object with no schema documentation and no output schema, the definition should describe the expected financials payload. That is the one material 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 0% and the sole parameter is a free-form nested object with additionalProperties=true, so the schema conveys nothing about its contents. The description partially compensates by naming check categories that imply needed inputs (tax rates, EBITDA/EBIT, historical CAGR, capex, working capital), but it never states required fields, expected granularity, or structure.

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 (validate) and resource (company financials) and enumerates the exact checks performed (tax-rate sanity, EBITDA/EBIT bridge, growth continuity, capex ratio, working-capital stability). This breadth of named checks makes it obviously distinct from siblings like company_report or deal_score without opening their 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 phrase 'institutional validation pass' implies the context (due-diligence-style integrity check) but there is no explicit when-to-use/when-not guidance and no reference to the sibling tools such as company_report or deal_score. Usage is inferable but not directed.

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