Deep Values

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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds real value beyond them: self-billing counts as 1 metadata call, the endpoint is free, and the auth requirement (connected account or dv_sk_ key). That is meaningful operational context an agent cannot get from 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?

Two tight sentences that front-load the returned data, then billing, then endpoint and auth constraints. The parenthetical endpoint/auth block is slightly compressed, but every element 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 parameters and no output schema, the description is the sole source of return-value detail, and it enumerates what comes back plus cost and auth requirements. Complete enough for a zero-arg read tool, though it could note the shape of the usage buckets.

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 tool takes zero parameters, so the schema carries nothing to interpret and the baseline is 4. The description correctly omits parameter discussion rather than padding it.

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

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

States a specific verb (Returns) plus the exact resources returned: the calling key, its scopes, environment, and today's usage across all 3 buckets. Clear and concrete, though it never differentiates itself from the closely related sibling keys_me.

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 useful prerequisite (needs a connected account or a dv_sk_ key) and notes the call is free, which implies when it can be invoked. It does not state when to prefer this over siblings like keys_me or credits_checkout, leaving usage largely implied.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses cost ('Bills 3 metadata units', '0.005 credits per call'), auth behavior ('works with no credentials up to 1 call(s)/day per address'), and the underlying endpoint. These are exactly the operational facts an agent needs before invoking, and none are available in 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 core purpose is front-loaded in the first sentence, with cost/auth/endpoint details compressed into one parenthetical. It is dense but every clause carries information; the endpoint URL is arguably redundant but harmless.

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 usefully characterizes the return value ('system prompt + structured context block') and adds cost and auth limits. It is nearly complete for a read-only, two-parameter tool, with the only real gap being the undocumented token_budget control.

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% for 2 parameters, so the description must carry the burden. It only implies the 'ticker' parameter via 'scoped to one ticker' and says nothing about 'token_budget' — its default of 6000, its 1000-16000 range, or what increasing it does. Half the parameters remain unexplained.

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 deliverable ('Returns a system prompt + structured context block, scoped to one ticker'), which is a distinct artifact no sibling tool produces. An agent can identify this as the LLM-grounding tool versus the raw data tools (news, fundamentals, filings) without opening the schema.

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

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

It gives a clear usage context: 'Drop it into OpenAI/Anthropic/any LLM SDK to ground your chatbot in current Deep Values data.' That tells the agent when this tool is the right choice, but it names no alternatives and no explicit 'when not to use' condition (e.g. for raw data retrieval, use fundamentals/news instead).

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses cost (0.001 credits per call) and the anonymous rate limit (25 calls/day per address), which an agent needs for planning and retry behavior. It stops short of describing result shape or pagination, but the added operational context is genuinely useful.

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 front-loaded sentence with the operation first, then endpoint, cost and limit. Nothing is padded, though the parenthetical packs pricing ahead of any semantic detail an agent would more urgently need.

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 parameter descriptions, the description leaves the two inputs and the result contents entirely unexplained. Cost and rate limits are covered, but for a search tool that will be invoked with a user-supplied query string, that omission is significant.

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% for two parameters, so the description must carry the burden — and it adds nothing. Neither 'q' (query syntax? ticker vs name?) nor 'limit' (maximum 100, default 20) is clarified beyond the raw JSON schema types.

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

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

The description gives a verb+resource ('Company search') and pins it to an explicit endpoint, which fixes the operation. But it never says what is searched (name, ticker, domain?) or how results relate to the sibling company_overview, so the agent cannot distinguish search from lookup on purpose alone.

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

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

No when-to-use guidance, no conditions, no mention of alternatives such as company_overview, filings, or fundamentals. The only routing signal is the pricing/rate-limit note, which is incidental rather than situational.

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

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

Annotations cover read-only/open-world, but the description adds genuinely useful non-schema context: the per-call cost (0.001 credits) and the unauthenticated rate limit (25 calls/day per address). It does not, however, describe what the 'overview' payload contains or any pagination/format 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?

A single compact parenthetical delivers endpoint, cost, and auth limit with no wasted words, and the resource name is front-loaded. It is dense and efficient.

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 covers operational essentials (cost, auth) but never says what the overview returns or how it differs from sibling data tools. An agent can call it but cannot confidently judge its output.

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% for the single required parameter, so the description must compensate. Showing '{ticker}' in the URL path does imply the parameter is a stock ticker symbol, which adds some meaning, but there is no detail on format, case sensitivity, or exchange qualification.

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 essentially restates the name/title 'Company overview' with no verb, so the purpose is implied rather than stated. The endpoint URL hints at the resource ('companies/{ticker}/overview'), but it gives no differentiation from siblings like fundamentals, filings, or intrinsic_value, which all return company-level data.

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 guidance on when to use this tool versus alternatives such as fundamentals or intrinsic_value. The only context is operational (cost and credential limits), not selection guidance.

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

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

Annotations only cover the generic safety profile (openWorld, non-idempotent, non-destructive); the description adds real behavior — one-time session, credits land on the balance only after payment completes, poll GET /keys/me, free with no quota consumption, and the auth prerequisite. This is well beyond what the structured fields disclose.

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

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

Front-loaded with the core action and outcome, then prerequisites. The trailing parenthetical repeating the endpoint URL and 'free' is mild redundancy, but nearly 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?

No output schema exists, and the description compensates by explaining what happens after payment and how to observe the result via GET /keys/me. An agent has everything needed to call it correctly and interpret the follow-up.

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

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

Schema coverage is 100% and the schema already explains the pack parameter with an example value and a pointer to credits_packs. The description's mention of 'credit pack' adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — creating a one-time Stripe Checkout Session for a credit pack — and scopes it to the calling live key's account. It is clearly distinguishable from credits_packs, which lists packs rather than creating a checkout.

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

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

Gives strong usage context: it is what a 402 topUp.checkoutEndpoint points at, and it requires a connected account or a dv_sk_ key. It also defers pack selection to credits_packs, though it never states an explicit when-not 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond the annotations: the operation is free, the auth requirement (connected account or dv_sk_ key), the pricing convention (1 credit = $1.00), and the underlying endpoint.

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 compact sentences with the core purpose front-loaded; the parenthetical endpoint/auth note is dense but earns its place. No filler 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?

For a zero-parameter read-only list tool with no output schema, the description covers purpose, cost, auth prerequisites, and endpoint, which is sufficient for an agent to call it correctly. Only the relationship to credits_checkout is 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?

The tool takes zero parameters and the schema is empty, so the baseline of 4 applies. No parameter detail is needed and none is missing.

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

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

States a specific verb and resource: lists the prepaid credit packs the current key can buy, with a clear scoping clause ('this key can buy'). It does not explicitly contrast itself with the sibling credits_checkout, so differentiation is implied rather than stated, keeping it just under 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?

Usage is implied (browse available packs, likely before checkout) and the auth prerequisite is noted, but there is no explicit when-to-use or when-not-to-use guidance and no reference to credits_checkout as the alternative. Adequate but with a clear gap in routing.

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

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

With annotations only covering readOnlyHint and openWorldHint, the description carries real behavioral load and delivers: exact endpoint, 0.001 credits per call, and the key auth fact that it works credential-free up to 25 calls/day per address. This pricing and rate-limit disclosure is exactly the kind of context annotations cannot express. It stops short of describing the response payload or limit/pagination 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?

A single tight parenthetical that front-loads the resource and packs endpoint, cost, and rate limit without filler. The nested-parenthesis run-on is slightly dense 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 simple read-only retrieval tool with no output schema and readOnlyHint already declared, the safety profile is adequately covered and cost/auth are disclosed. Still missing: what a returned filing contains, the meaning of limit, and any signal distinguishing this from adjacent company-data tools. Adequate but with clear gaps.

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%, so the description must compensate for all three parameters. It implicitly documents ticker via the URL path and hints at valid form values with "10-K, 10-Q, 8-K, etc", which is useful. But the limit parameter (default 10, max 50) is never explained, and neither the form filter semantics nor the default/cap behavior is covered.

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 ("SEC filings") and gives form examples (10-K, 10-Q, 8-K), so an agent knows the domain. But the phrasing is a verbatim restatement of the title with no verb explaining the operation (list vs. fetch a specific filing) and no differentiation from siblings like fundamentals, company_overview, or research that also surface company data. Vague on the actual action.

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 when-to-use guidance and no mention of alternatives. The nearest siblings (fundamentals, company_overview, company_search) all touch company financial data, and the description never says when filings is the right pick. Cost/auth info is present but that is availability, not usage 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 cover readOnly/openWorld, and the description adds genuinely useful behavioral facts: cost of 0.001 credits per call and an unauthenticated rate limit of 25 calls/day per address. It does not disclose pagination or the shape of the returned statements, but the auth/cost/limit disclosure is real added value.

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 dense parenthetical, front-loaded with what the tool returns before the endpoint/cost details. No wasted prose, though the parenthetical packs multiple unrelated facts (endpoint, price, rate limit) into one 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?

With no output schema, the description should ideally say what the returned statements look like; it does not. It compensates somewhat with cost and rate-limit context, but leaves the two optional parameters unexplained for a multi-parameter data-retrieval tool.

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

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

Schema description coverage is 0% for 3 parameters, so the description carries the full burden. It only implies the ticker via the URL template; 'limit' (default 5, max 20) and 'period' (annual/quarterly) are never mentioned or explained in either place.

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 exact data set returned (income statement + balance sheet + cash flow) and the underlying endpoint, which is specific enough to distinguish it from sibling fundamentals tools like company_overview or indicators_buffett. It lacks an explicit verb, but the resource 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 statement of when to use this tool versus the many sibling financial tools (company_overview, intrinsic_value, indicators_buffett, filings). The only context is the endpoint and cost, which helps decide whether to spend credits but not which tool to pick for a given question.

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/openWorldHint annotations, the description discloses cost (0.005 credits per call) and an auth/rate-limit profile (works with no credentials up to 25 calls/day per address), which is genuinely useful operational context. It does not describe the return shape, but this exceeds what the 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?

A single tight parenthetical: resource first, then endpoint, cost, and auth constraints. No filler sentences and the substantive constraint 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 read-only single-guru fetch with an enforcing annotation set and no output schema, the definition covers cost, auth, and scope adequately. The remaining gap is the undefined slug format, which an agent needs to invoke it successfully.

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% for the single `slug` parameter. The URL template embeds `{slug}`, implying it is a path identifier for the guru, but the description gives no format, source, or example of a valid slug value, so it only partially compensates.

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 payload: "One guru: bio + top holdings." The singular "One guru" implicitly distinguishes it from the plural `gurus` list sibling, but it does not explicitly contrast with `guru_portfolio` or `guru_moves`, which also operate on a single guru.

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 when-to-use guidance or routing to alternatives. An agent must infer from the sibling names whether `guru_portfolio` or `guru_moves` is the better choice for deeper holdings or transaction history; the description offers no 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 only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond that: the verdict is deterministic and identical for every caller, it never predicts a return or recommends an action, name is null rather than an echoed ticker for a reason, and rows missing an EDGAR date fall back and are flagged filed_at_known: false. These are exactly the non-structural traits an agent cannot get from annotations.

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

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

Long but front-loaded, opening with the feed's identity and materiality criteria before the verdict semantics, null handling, and access terms. Most sentences carry distinct information, though the verdict explanation and the name-null rationale are somewhat over-elaborated for the space they occupy.

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

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

There is no output schema, so the description must describe the returned rows — and it does: verdict line per row, legal name vs ticker with null semantics, and the filed_at_known flag fallback. Together with the cost/auth terms, an agent has enough to call correctly and interpret responses without further probing.

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 67%: slugs and filed_since are documented in the schema, but limit has none. The description explains the date-provenance fallback that underpins filed_since but adds no syntax, format, or range detail for any of the three parameters, so it does not meaningfully exceed the schema baseline.

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

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

States a specific resource (material 13F guru moves) with an explicit materiality definition (new position, full exit, 25% share-count move, or $100M+ position) and ordering rule (newest filing first). This distinguishes it from siblings like guru_portfolio, smart_money_changes, and filings 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 description gives operational context an agent needs before calling: the endpoint, 0.005 credits per call, and that it works unauthenticated up to 25 calls/day per address. It does not, however, name an alternative sibling or state when-not to use this feed versus guru_portfolio or smart_money_changes, so routing guidance is inferred 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 openWorldHint=true, so the safety profile is covered. The description goes beyond them with genuinely useful operational context: cost (0.005 credits per call) and an unauthenticated access tier capped at 25 calls/day per address. It does not describe the shape of the portfolio data returned, which is the main 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?

A single sentence with the core purpose front-loaded and the endpoint, price, and quota details relegated to a parenthetical. Nothing is redundant, though the parenthetical is dense enough to slow scanning slightly.

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 endpoint with no output schema and 0% parameter coverage, the description should clarify the return payload and the meaning of as_of. It covers pricing, auth, and quota well, but leaves an agent guessing about response contents and one of the two parameters.

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

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

Schema description coverage is 0%, so the description carries the burden and only partially meets it. The URL template reveals that 'slug' is a path identifier, but the 'as_of' date parameter is never mentioned, and neither parameter's format or semantics (e.g. which quarter, how as_of interacts with the snapshot) is explained.

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-ish resource: 'One guru's full portfolio at a quarter', which tells an agent it retrieves a single guru's holdings snapshot. It is distinguishable from guru_moves (changes) and gurus (listing), though it never explicitly names those siblings to sharpen the contrast. 'At a quarter' is mildly cryptic but interpretable as a quarterly snapshot.

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 no when-to-use guidance and does not mention alternatives like guru_moves or smart_money_holdings. The only conditional information is quota-related ('works with no credentials up to 25 call(s)/day per address'), which is rate-limit info rather than selection guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds genuinely useful context beyond them: per-call cost (0.005 credits), an anonymous access tier (25 calls/day per address with no credentials), and the underlying endpoint. Pricing and rate-limit disclosure are exactly the kind of traits annotations do not carry.

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

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

Two short sentences with the resource front-loaded, followed by a compact parenthetical carrying endpoint, cost, and access tier. No filler, and the most important identification comes 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 read-only list tool with no output schema, the description covers what is returned, how to filter, the cost, and the auth/rate-limit posture. The remaining gap is parameter-level detail, which is a meaningful but not fatal omission for a two-parameter 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?

Schema description coverage is 0%, so the description must compensate and largely does not. It notes that filtering is available by style but never explains the five enum values or what 'limit' controls (max 200, default 100), leaving both parameters under-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 states a specific resource ('60 hand-picked institutional investors', a curated guru roster) and its scope, so an agent knows this returns a collection rather than a single record. It stops short of explicitly differentiating itself from the singular 'guru' sibling, but the roster framing implies the list form.

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

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

The only usage guidance is 'Filter by style.' There is no statement of when to use this list versus 'guru', 'guru_moves', 'guru_portfolio', or the smart_money_* siblings, and no exclusions. The agent must infer the routing itself.

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 and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: pricing (0.001 credits per call) and unauthenticated rate limits (25 calls/day per address), which an agent needs to plan calls.

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 tight sentence carries the core definition and return shape, with pricing/auth metadata front-loaded in a parenthetical. No filler, though the param behavior is absent rather than omitted for brevity.

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 readOnly/openWorld annotations and no output schema, the description sufficiently conveys what the tool returns, its cost model, and its access requirements. The only meaningful hole is the undocumented history_years parameter.

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 parameter history_years (default 5, max 50) is never mentioned in the description. The description does not compensate for the gap by explaining the lookback window's effect on percentiles or zones.

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 exactly what the tool computes (US corporate equities ÷ GDP) and what it returns (zones and historical percentile), which is a specific verb+resource. It clearly differs in substance from the sibling indicators_shiller_pe, though it never names that sibling to make the routing explicit.

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 when-to-use or when-not guidance is given, and the closely related sibling indicators_shiller_pe is not mentioned. Usage is only implied by the general nature of a valuation indicator.

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 (readOnlyHint=true, openWorldHint=true), yet the description adds real behavioral context: the exact endpoint, 0.001 credits per call, and that it works without credentials up to 25 calls/day per address. That is meaningful rate-limit and auth metadata an agent can plan around, though it omits error/pagination 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?

One sentence, front-loaded with the metric being returned, followed by endpoint, cost, and quota in a compact parenthetical. Nothing is padded, though the terse parentheses style is dense rather than structured.

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

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

With no output schema and a single optional parameter, the description gives enough to make the call (cost, quota, endpoint) but leaves the one input's meaning and the composition of the returned percentile unexplained. Adequate for invocation, thin for interpretation.

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

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

Schema description coverage is 0% for history_years, so the description carries the burden and fails: it never explains what the parameter controls or what the resulting percentile is computed over. The max of 100 and default of 5 are only visible in the schema, leaving the unit and effect of history_years opaque.

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

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

The description identifies the resource (Shiller PE valuation with a historical percentile) clearly enough that an agent knows it returns a valuation indicator, and it distinguishes itself from indicators_buffett by the metric named. However, the text is essentially the title restated plus endpoint metadata, with no verb or explanation of what the returned percentile represents.

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 guidance on when to prefer this indicator over siblings such as indicators_buffett or intrinsic_value, and no stated prerequisites beyond implicit auth. The credit cost and 25-call/day unauthenticated limit are operational facts, not usage guidance for choosing the 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 only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the concrete endpoint, the cost (0.005 credits per call), and the credential-free limit of 25 calls/day per address. That cost and rate-limit detail is exactly the operational context an agent needs before spending credits, though nothing is said about latency or response shape.

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 tightly packed sentence with the value proposition front-loaded and the operational caveats in trailing parentheses. Nothing is wasted, though the parenthetical stacks three distinct facts (endpoint, cost, quota) without separating them.

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

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

With no output schema and only readOnly/openWorld annotations, the description should say more about what a caller receives from a valuation endpoint. Cost, endpoint, and quota are covered well, but return content and ticker format remain undefined.

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% for the single ticker parameter, so the description carries the burden. Showing '{ticker}' in the URL path confirms it is a path-style identifier, but no format guidance (bare symbol vs. exchange suffix) is offered, leaving the main semantic question unanswered.

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 is essentially the title restated ('DCF + Owner Earnings + Damodaran intrinsic value') with no verb or resource framing. An agent can infer it produces a valuation, but it never says what it returns (a number? a report? three figures?) or how it differs from siblings like fundamentals, company_overview, or verdict.

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 when-to-use guidance is given, and no sibling is named as an alternative. The closest thing to usage context is the quota/auth note, which explains access rather than when this tool is the right choice over fundamentals or verdict.

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/openWorldHint annotations, it discloses cost behavior ('free, consumes no quota'), authentication requirements, and the precise unit semantics of the returned balance. These are meaningful behavioral traits an agent cannot derive from the annotations or the empty 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?

One dense sentence that front-loads what is returned, followed by a compact parenthetical for cost, endpoint, and auth. No redundant or filler 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?

With no output schema, the description carries the return-value burden and does so fully: key identity, balance with unit conversion, quota buckets, and environment. Combined with auth and cost notes, an agent has everything needed 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?

The tool takes zero parameters, so the schema is trivially complete and the baseline is 4. The description correctly adds no parameter discussion because there is nothing to pass.

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

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

The description names a specific verb (returns) and enumerates the exact resources returned: the calling key, ledger balance, per-bucket quota remaining, and environment. It distinguishes itself from sibling tools like account, credits_checkout, and credits_packs by scoping to the caller's own key rather than account-level or purchase operations.

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 selection context — 'Free, and consumes no quota' tells the agent this is the zero-cost way to check balance/quota — and states the auth prerequisite (connected account or dv_sk_ key). It stops short of explicitly naming an alternative tool or a when-not condition, so it is clear context without exclusions.

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

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

Adds substantial context beyond the readOnlyHint/openWorldHint annotations: explicit content exclusions ('carries NO quantity and NO instruction', sizing reads 'not provided'), a disclaimer that it is not advice or a prediction, the transport (GET URL), per-call cost (0.005 credits), and an unauthenticated rate limit (25 calls/day per address). This is exactly the kind of operational detail annotations cannot supply.

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

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

Front-loads what the tool produces and its exclusions, then tucks endpoint/cost/auth facts into a parenthetical. Every sentence carries information, though the parenthetical is dense.

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 usefully sketches the returned content, but it omits any explanation of the `guru` and `quarter` inputs, including valid formats or the default period. For a 3-parameter tool at 0% schema coverage, that leaves a real gap an agent must guess at.

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 description only surfaces `ticker` via the URL template. The required `guru` parameter and the optional `quarter` (a date-formatted field with obvious ambiguity about which quarter) are left completely undefined, so the description does not compensate for the coverage gap.

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

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

States a specific output artifact (a flattened brief of one filed move) and enumerates exactly what it contains (what the investor did, when, price, value band, verdict sentence). It explicitly distinguishes itself from the sibling `verdict` by describing the relationship ('the same move as /verdict, flattened').

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 comparison to /verdict implies this is the lighter-weight alternative that omits sizing, but it never states when to choose one over the other or any preconditions for calling it. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful non-schema context: the HTTP endpoint, the exact cost of 0.001 credits per call, and the unauthenticated daily limit of 25 calls per address. It does not describe return format or pagination, but the annotations lower the 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 a single compact sentence with the resource front-loaded, followed by endpoint, cost, and rate-limit details. Every clause provides distinct operational value, and there is no wasted 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 3-parameter tool with 0% schema description coverage and no output schema, the description is incomplete. It supplies endpoint and quota context but omits parameter semantics, output expectations, and sibling differentiation, so an agent would need to guess about key invocation 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 0%, so the description must compensate for all three parameters. It only implies that 'ticker' is a path parameter from the URL template; it does not explain the 'since' date filter or the 'sentiment' enum values (bullish, bearish, neutral), leaving the schema to carry unsupported 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?

The description names a specific resource ('Sentiment-scored news') and gives the exact endpoint, so the agent can tell this retrieves per-ticker news with sentiment scoring. It does not explicitly distinguish this tool from the sibling 'sentiment' tool, which leaves some ambiguity about when to prefer one over the other.

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

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

The description mentions credential and rate-limit constraints, but it gives no guidance on when to use this tool versus siblings such as 'sentiment', 'research', or 'filings'. There is no explicit when-to-use or when-not-to-use 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 only cover readOnly/openWorld, but the description adds substantial behavior: quota (50/day at $99/mo, $0.10 overage), 3 credits per call, cached-only status, and auth requirements (connected account or dv_sk_ key). This is exactly the kind of cost/auth/state disclosure an agent needs.

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

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

Front-loads the value proposition well, but then crams pricing, quota, caching, URL, credit cost, and auth into one trailing parenthetical. The information is useful but the structure is dense and slightly cluttered rather than cleanly ordered.

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 what is returned, cost, caching state, and auth—enough for an agent to call it safely. The gaps are the unexplained 'language' parameter and the missing routing guidance versus sibling research tools.

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 2 params, so the description must carry the load and it largely does not. It mentions {ticker} only via the URL template and never explains the 'language' enum, so an agent gets no added semantic meaning for either parameter.

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

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

States a specific verb/resource ('full briefing, bull case, bear case, valuation, investment plan, fair-value range') and frames itself as 'The differentiated endpoint.' However it does not distinguish itself from close siblings like mirror_brief, verdict, or theses, so the agent still has to guess which briefing tool to pick.

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

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

There is no explicit when-to-use guidance or routing versus siblings (mirror_brief, verdict, intrinsic_value). The note that it 'currently returns cached results only' hints at a limitation but does not tell the agent when this tool is the right choice.

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

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

With readOnlyHint and openWorldHint already declared, the description adds real operational context: 0.001 credits per call, a free no-credential tier capped at 25 calls/day per address, and the HTTP endpoint. Cost and rate-limit disclosure is exactly the kind of value structured annotations cannot carry.

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

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

A single dense parenthetical with no filler — endpoint, cost, and quota are front-loaded after the one-line purpose. Efficient, though the nested parenthetical is slightly hard to parse.

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

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

No output schema exists, so the description should describe what sentiment data comes back, and it does not. Combined with 0% parameter coverage on two enum params, an agent knows the cost and endpoint but not what it receives or how source/window change the result.

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

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

Schema description coverage is 0%, so the description must compensate, and it does not. It only exposes the ticker via the URL template; the 'source' (reddit/stocktwits/combined) and 'window' (24h/7d/30d) enums are left entirely unexplained, along with their defaults.

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

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

The description names a specific resource (sentiment rollup for a ticker) and scopes it as value-investor-focused rather than WSB noise, which is a meaningful distinction. However, it never says what a 'rollup' actually contains (bullish/bearish score, post volume, etc.), so the purpose is clear at a high level but not precise.

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 when-to-use or when-not-to-use guidance, no mention of alternatives, and no prerequisites beyond the credential note. 'Not WSB noise' hints at positioning but does not tell an agent when to reach for this tool versus news, guru, or theses.

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

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

Annotations cover the safety profile (readOnly, openWorld), yet the description still adds real operational context: the concrete endpoint, 0.005 credits per call, and that it works credential-free up to 25 calls/day. That cost/rate-limit/auth disclosure is exactly the beyond-annotation value the rubric rewards.

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

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

Front-loaded and tightly packed: scope sentence first, operational metadata in a parenthetical. Dense but every clause earns its place; nothing is padded.

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

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

For a read-only list tool with no output schema, the description covers what rows qualify, the window semantics, cost, and auth limits. The only lightly covered area is return shape/pagination, which is minor given the annotations and lack of output schema.

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

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

With 50% schema coverage, the description compensates by expanding the materiality logic, mapping the OR conditions (new positions, full exits, ≥25% share-count shifts, ≥$100M size) onto the status/min_position_usd filters. The schema already documents 'since' vs 'filed_since' well, so this is additive rather than redundant.

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 ('13F position changes') and pins down the exact scope: entire 60-guru roster, requested window, materiality threshold. The 'changes' framing cleanly separates it from the sibling smart_money_holdings without needing to name it.

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 materiality definition (new/exits/≥25%/≥$100M OR) implicitly tells the agent what this tool surfaces, but there is no explicit when-to-use vs smart_money_holdings or guru_moves, and no stated exclusions. Usage is inferable but not guided.

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

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

Goes well beyond readOnlyHint/openWorldHint by disclosing the endpoint, per-call cost (0.005 credits), and the no-credential rate limit (25 calls/day per address) — exactly the operational facts an agent needs before invoking. Return fields (shares, USD value, % of portfolio, auto-classified delta) are also described.

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

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

Front-loads the core behavior, then appends the return fields and operational details in a tight parenthetical. Dense but every clause carries information; the endpoint/credit/limit parenthetical is slightly cluttered but 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?

Given two simple parameters, no output schema, and a read-only annotation set, the description covers scope, default-quarter behavior, returned fields, cost, and credential-free limits. Nothing needed to call it correctly is missing.

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

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

With only 50% schema description coverage, the description compensates by explaining that quarter_end selects a specific historical quarter and that omitting it defaults to the latest available, matching the schema's stated default. The ticker parameter's format is left to the schema pattern.

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 ('returns every guru ... who held') and resource (curated 60-name roster holdings for a ticker), scoping to the latest 13F-HR quarter by default. This cleanly separates it from siblings like guru_portfolio, guru_moves, and smart_money_changes, which cover portfolios, moves, and quarter-over-quarter changes respectively.

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 per-ticker framing makes the use context obvious: fetch who among the curated gurus holds a given stock, optionally for a historical quarter. It does not explicitly name when to prefer a sibling (e.g., smart_money_changes for deltas across names), so it falls short of the explicit when/when-not/alternatives bar.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the endpoint, cost (0.005 credits per call), and an anonymous rate limit (25 calls/day per address with no credentials). That is exactly the kind of auth/cost/limit context an agent needs. It stops short of describing pagination or ordering 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?

Two tight sentences with the core resource and metadata front-loaded, followed by filtering options and then operational details in a compact parenthetical. Nothing is padded, though the metadata list and filter list slightly overlap.

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 partially compensates by naming the fields a thesis carries (sentiment, conviction, price target, DVI run), and it covers auth/cost limits. It is a zero-required-parameter read tool, so the remaining gap — return shape/pagination — is modest but 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 0%, so the description must carry the load, but it only restates three parameter names (ticker, conviction, sentiment) without adding meaning — e.g., no explanation of the 1–5 conviction scale or the role/default of `limit`. It also omits the fourth parameter entirely, leaving the schema's bare types as the only documentation.

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 — public investment theses with structured metadata (sentiment, conviction, price target, DVI run) — which is a coherent, retrievable entity and clearly not the same as the aggregate `sentiment` or `research` siblings. It does not, however, explicitly name or contrast with any sibling, so an agent must infer the boundary.

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

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

The description tells the agent which fields can be used to filter (ticker, conviction, sentiment), which implies the intended usage, but gives no when-to-use vs. alternatives guidance and no exclusions. There is no signal about when to prefer this over `sentiment`, `research`, or `verdict`.

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

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

Annotations only declare readOnly/openWorld, so the description carries most behavioral burden and does add real context: the six deterministic states, the too_uncertain threshold (>3x spread or non-positive central estimate), the null value for non-call verdicts, and the rate limiting note (25 calls/day without credentials, 0.005 credits). It omits authentication requirements for higher volumes and error behavior, but supplies substantially more than 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?

Front-loads a rich purpose sentence, but then delivers dense explanatory prose including parentheses, embedded quotes of state semantics, and an endpoint/pricing parenthetical. Much of it is on-topic, yet a full-fledged parenthetical may not be needed for callable tool selection.

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-param read-only tool with no output schema, the description covers the returned shape (name, three dates, quarter-end close, current price, intrinsic value band, value, estimates, six states) so an agent can predict output structure and semantics without an output schema. Missing only explicit auth/error/edge-case 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% and only the quarter parameter is documented (defaulting to most recent). The description does not explain guru (presumably a guru identifier/key) or ticker format, so it misses compensating for the coverage gap beyond what the schema already states.

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

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

States a precise verb+resource: returns one guru's disclosed move in one ticker, enriched with Deep Values' published sentence and all supporting numbers. Easily distinguished from siblings like guru_moves (list) or intrinsic_value (pure valuation).

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?

Implicitly scoped to a specific guru-ticker-quarter combination, but no explicit 'use this when' guidance or routing away from alternatives such as filings, intrinsic_value, or guru_moves. An agent could infer, but not confidently.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond them: the HTTP endpoint, that the call is free, and the auth requirement (connected account or dv_sk_ key).

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 tight sentence with the purpose front-loaded and supporting details (endpoint, cost, auth) tucked into a parenthetical. 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 no-param, read-only list tool with no output schema, the description covers what an agent needs: what it returns conceptually, that it costs nothing, and what credentials are required. Only the shape of the returned subscription list is left unspecified.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter-level detail is needed or missing.

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 (List) and resource (webhook subscriptions), and even names the exact endpoint. No sibling tool overlaps with webhooks, so differentiation is trivially satisfied 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?

Usage is implied by the clear purpose (inspect existing subscriptions), but there is no explicit when-to-use/when-not-to guidance, no mention of prerequisites beyond auth, and no alternatives to weigh since no sibling handles webhooks.

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