CapitalSnitch

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds genuinely non-inferable facts: no account required, free, and it never consumes the daily limit. It also flags the service is live/commercial, which matters for interpreting the response, and signals that sign-up can be initiated in-chat.

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 identity, then a compact enumeration of contents and example queries. The middle sentence is a long run-on list, but every clause maps to something the agent may need to answer a question, so little is padding.

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

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

With an output schema present and zero parameters, the description covers everything left: what topic the tool answers, when to reach for it, and its cost/limit profile. An agent can decide to call it and set expectations without further information.

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 to disambiguate; the baseline is 4. The description correctly implies a no-argument call and does not waste words on nonexistent inputs.

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

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

States a specific resource (facts about the CapitalSnitch service itself) and enumerates exactly what it returns: plans, prices, daily limits, data coverage, payment methods, sign-up paths, supported AI apps, support email. This is clearly distinguishable from siblings like buy_plan, start_signup or get_my_account, which handle the transactional side.

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

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

Provides explicit trigger phrases ('what is CapitalSnitch?', 'how much does it cost?', 'how do I contact them?', 'can ChatGPT/Grok connect?'), which gives an agent a reliable routing signal. It does not explicitly name alternatives or exclusions (e.g. 'for your own plan status use get_my_account'), so routing is clear in the positive direction only.

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 declare openWorld=true, idempotent=false, readOnly=false, and the description adds real context beyond them: an external payment link is returned, an active card subscriber is switched immediately, and activation occurs automatically when paid. It also notes the call is free and requires the user's personal connection address. It stops short of describing failure modes (expired link, failed payment) or any rate/abuse limits on link generation.

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, then branch-specific behavior, then prerequisites and the alternative — a sensible ordering with no filler. The 'Card:'/'Crypto:' telegraphic style is compact but slightly dense to parse in a single block.

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

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

For a five-parameter, open-world payment tool with an output schema, the description covers the decision branches, side effects, cost, and auth requirement, which is most of what an agent needs. It omits what happens on a failed or abandoned payment and how a returned link's validity is bounded, which matters for a non-idempotent purchase flow.

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

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

Schema description coverage is 100% and all five parameters (including the three enums) are already documented in the schema, so the baseline is 3. The description reinforces the card vs. crypto branch and what a crypto response contains, but adds nothing about 'billing' or when 'user_accepted_terms' must be true that the schema does not already say.

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 specific verbs and resource: upgrade, renew or switch the signed-in user's plan without the website. It also distinguishes the two payment modalities and names a sibling (start_signup) for the public-preview case, so an agent can tell this apart from check_payment, confirm_signup and start_signup.

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

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

Explicitly scopes usage to the signed-in user's own plan and gives a when-not with the alternative: 'on the public preview use start_signup instead.' It also names the prerequisite (the user's personal connection address), which is a routing condition, not just a hint.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context: the call is free, crypto status progresses through waiting/seen/confirmed, and the card path returns the account's current plan.

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 key question and branch-specific instructions. Every sentence earns its place with no wasted prose.

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 one optional parameter, rich annotations, and an output schema, the description covers both payment paths and the cost of calling. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, and the order_id schema already explains that it comes from buy_plan/confirm_signup and should be omitted for card payments. The description reinforces this but adds no new syntax or format details beyond the schema, so baseline 3 applies.

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

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

States a specific status question: whether the payment arrived and the plan is active. It distinguishes crypto (pass order_id) from card (omit it) and names the observed crypto states, so an agent can identify it as a read-only payment/plan status check.

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

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

Gives clear usage branches: crypto requires order_id, card omits it, and the call is free. It does not explicitly name or exclude sibling alternatives such as get_my_account, so it falls short of a full 5.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, non-idempotent), and the description adds substantive context beyond them: the account is created or a session established, the plan activates automatically once payment lands, and the call is free. It does not disclose failure behavior for an invalid or expired code, which for a non-idempotent account-creating call is the 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?

One long sentence, but the flow position and the primary action are front-loaded and every em-dash clause carries distinct information (returned address, payment branch, activation timing, cost). Slightly run-on, yet no filler.

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

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

With annotations, a 100%-covered 2-param schema, and an output schema that handles return values, the description covers what the agent needs to invoke it correctly. The main omission is error handling for a bad code, which matters for a signup step but is secondary to the happy path it documents well.

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

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

Schema coverage is 100% and both parameters already document the 6-digit code format and the email-matching-constraint. The description adds nothing about the parameters beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb chain (checks emailed code, creates account or signs in) with its exact position in the flow ('Step 2 of 2') and its outputs (connection address, payment step). An agent can immediately tell this apart from start_signup, buy_plan, and check_payment.

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?

Makes the sequencing explicit ('Step 2 of 2', 'Same email used in start_signup') and notes 'Free to call', which is real guidance about cost. It does not explicitly name when to prefer buy_plan or check_payment instead, or what to do when the code fails, so it falls short of full when/when-not coverage.

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

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

Annotations already establish this as a safe, read-only, deterministic query. The description adds meaningful behavioral context beyond that: the <5-insider threshold, the crowded 5+ counterpart, and the fact that pace is measured by comparing recent activity with earlier activity. The only small gap is the meta-claim that it 'Explains exactly how rising is measured' without explaining that formula in the description itself.

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

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

The purpose and classification criteria are front-loaded in the first sentence, followed by usage examples. It is efficient overall, though the sentence 'Explains exactly how rising is measured' is slightly meta and does not itself deliver the explanation it promises.

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 an output schema present and full parameter documentation, the description need not explain return values. It supplies the key selection logic, the emerging-versus-crowded distinction, and usage intents, leaving no material gap for an agent to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters, including the relationship between recent_days and the earlier part of the window. The description adds only contextual framing ('in the window', 'recently than earlier') rather than parameter syntax or constraints beyond the schema.

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

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

The description states a specific verb and resource ('Spot insider buying') and defines the exact selection criteria: fewer than 5 insiders with a rising pace versus 5+ insiders for crowded companies. This lets an agent distinguish it from generic insider-buying or cluster tools without opening the schema.

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

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

It gives clear usage contexts with quoted example questions ('which stocks have early, increasing insider buying...', 'emerging insider signals'). It implicitly contrasts with crowded buying but does not name a specific sibling tool to use instead when the user wants crowded names.

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

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

Annotations already cover safety (readOnly, idempotent, closed-world), so the description's job is to add domain behavior — and it does, by restricting scope to 'open-market PURCHASES', which implicitly excludes grants, option exercises, and gifts. It adds no notes on data lag or coverage limits, but for a read-only scan that is a minor 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?

Two sentences: the first front-loads scope and the ranking modes, the second is a compact list of example queries. No filler, and every clause maps to a parameter or a selection decision.

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 an output schema present and full parameter documentation, the definition covers what an agent needs to invoke it. The one omission against a crowded sibling set (find_insider_clusters, find_emerging_insider_buying, get_insider_signal) is a routing rule that separates this market-wide scan from those narrower 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 coverage is 100%, so baseline is 3; the description earns above that by explaining the meaning behind two non-obvious parameters — sort_by is framed as total value / distinct insiders / recency, and min_insiders is glossed as 'cluster buying' with a worked example of 3+ insiders.

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 specific verb and resource (scan U.S. companies for insider open-market purchases) plus the ranking modes, and the phrase 'ALL U.S. companies' signals a market-wide scan rather than a single-company lookup. It stops short of naming the very similar siblings find_insider_clusters and find_emerging_insider_buying, which would have made the distinction airtight.

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?

Three concrete example phrasings ('which insiders are buying right now?', 'CEO purchases this month', 'companies where 3+ insiders bought') give an agent clear triggering contexts. There are no exclusions, so nothing tells the agent when to prefer find_insider_clusters or get_insider_activity 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?

Goes well beyond the readOnly/idempotent annotations by disclosing the analytical method itself: batch detection is same-day + similar modest amounts signaling a company program, and the 0–100 conviction score is defined by its components (independent buyers, C-suite participation, size, stake growth, multi-day spread, minus batch penalty). An agent knows what the output means and how to interpret it before calling.

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

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

Front-loaded with the core action, then the batch caveat, then the score definition, then trigger examples — good ordering. The middle sentence is long and clause-stacked, but essentially 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?

Six optional parameters, an output schema present, and a description that covers exclusions, methodology, scoring and typical queries. Nothing needed to call it correctly is missing; return shape is deferred to the output schema, which is appropriate.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning to two parameters that the schema only gestures at: it explains what a 'batch' actually is (for exclude_batches) and what the conviction ranking formula contains (for sort_by='conviction'), which the terse enum description does not.

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: finds companies where multiple distinct insiders made open-market purchases, and explicitly excludes option exercises, awards and sales. That scoping distinguishes it from the generic sibling find_insider_buying, though no sibling is named outright.

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

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

The 'Use for ...' clause gives three concrete trigger phrasings (3+ insiders in 60 days, real vs comp-plan buying, rank by conviction), which maps closely to the parameters. It lacks an explicit 'don't use this when X, use find_insider_buying instead' clause against the many sibling insider tools.

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

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

The annotations already disclose mutating, non-destructive, non-idempotent behavior. The description adds valuable traits beyond the annotations: private, single-use, valid for 15 minutes, works once, and requires no password or email code. These are exactly the behavioral details an agent needs before offering the link.

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

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

The description is three tight sentences and front-loads the core action. Every sentence adds useful information: what the link is, how long it lasts, how to hand it off, and that it is free to call.

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?

An output schema exists, so return values need not be explained. With annotations covering safety behavior and the description covering creation, validity, handoff, authentication bypass, and cost, the definition is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both plan and action in detail. The description mirrors some action semantics (checkout for upgrade/renew, account page for cancel/email/new connection address) but adds only marginal parameter-specific meaning beyond the schema.

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

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

The description gives a specific verb and resource: "Create a private, single-use link" that routes the user to checkout or account pages. It is clear what the tool does, though it does not explicitly name sibling alternatives such as buy_plan or get_my_account, so sibling differentiation is implied rather than stated.

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

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

It gives clear usage context: "Give it to the user to click; no password or email code needed" and "Free to call." However, it does not explicitly say when to prefer this over sibling tools like buy_plan or get_my_account, nor does it state exclusions.

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

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

Annotations already cover read-only, idempotent, closed-world, non-destructive, so the description is free to spend its words on behavior: it discloses that the response is a broad multi-domain composite and that the 'analysis' block is generated commentary requiring a disclaimer when shown to the user. It does not mention latency, payload size, or cost, which matters for a call that fans out across many data domains.

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 scope summary is front-loaded in the first clause and, given that the tool spans eight or more data domains, the length is justified. However, the body is one long run-on sentence with stacked parentheticals, and the financials/dilution content is tacked on with 'Also includes' as an afterthought rather than being structured into the enumeration.

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 an output schema present, the description needn't enumerate return fields, and it still does enough by listing domains and mandating how the 'analysis' text must be presented to the user. The main remaining gap is sibling routing guidance for the many narrower tools that overlap with parts of this response.

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

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

Schema coverage is 100% and both parameters are documented with ranges and a default, so the schema carries the load. The description only indirectly touches parameterization ('unusual vs history' implying the look-back window) and never mentions insider_days explicitly, adding little beyond structured data — baseline 3 is appropriate.

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

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

The opening line 'Everything that matters about one company in one call' plus the enumerated contents (insider signal, earnings countdown, volatility regime, trend vs moving averages, drawdown, analyst consensus, market backdrop, financials, dilution, written take) makes the resource and its composite nature unmistakable. It is clearly differentiated from narrow siblings like get_insider_signal, get_financials, and get_market_context because it explicitly bundles all of them.

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?

Example trigger phrases ('analyze X', 'should I look closer at X?', 'anything notable about X before earnings?') give concrete usage context, and the presentation instruction ('present it to the user, and say it is automated context, not investment advice') is actionable. It stops short of stating when NOT to use it, e.g. that a narrow question about insiders should go to get_insider_signal instead of this heavier aggregate call.

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

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

Even with annotations already marking it read-only and non-destructive, the description adds substantial context: free public data, no daily-limit consumption, reporting lag of up to 45 days, historical rather than live data, default no-filter summary behavior, and returned fields including late-reporting days and official filing links.

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

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

The description is dense but well front-loaded: purpose, returned data, no-filter behavior, data freshness caveat, example queries, and usage restrictions all appear in a logical order. Every sentence adds operational context rather than restating the name or schema.

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

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

With rich annotations and an output schema, the description supplies the remaining context an agent needs: data provenance, reporting delay, default behavior, example queries, and prohibited uses. Nothing material for correct tool selection or invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents all six parameters and their bounds. The description adds meaningful usage context by explaining what happens with no filters and by grounding the look-back window in the STOCK Act reporting delay, though it does not give parameter-specific syntax beyond the schema.

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

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

The description states a specific verb/resource—stock trades reported by U.S. House and Senate members under the STOCK Act—and lists the returned fields, making the tool clearly distinct from corporate insider-trading siblings. It also explains the no-filter behavior and the reporting-delay context.

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

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

It gives explicit use cases and exclusions: examples like 'which members traded NVDA?', 'what has Pelosi bought?', and 'congressional trades this week', plus a prohibition on credit decisions, fundraising, and solicitation. It does not explicitly name a sibling alternative for corporate insider queries, so it stops short of full when-to-use/when-not/alternatives 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value by disclosing the exact sections returned, which tells the agent this is a pre-composed aggregate rather than a parameterized query. It does not note freshness or whether a paid subscription is required.

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

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

Front-loaded with the purpose, then the content list, then usage triggers — a sensible ordering. The enumerated section list is long but each item is substantive content, not filler.

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

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

With no parameters, a present output schema, and full annotation coverage, the description supplies everything an agent needs: what is inside, and when to reach for it. Missing auth/freshness notes are minor against structured fields that already carry the rest.

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 baseline is 4 and the schema is trivially fully covered. Nothing further about argument semantics is needed here.

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 ('Ready-made daily briefing') and enumerates its contents: market backdrop, Fed odds, insider buys ahead of earnings, biggest purchases this week, CEO/CFO purchases, clusters. This lets an agent infer it aggregates what get_market_context, find_insider_buying and find_insider_clusters provide separately, though no sibling is named outright.

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

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

Gives explicit trigger phrases ('give me today's briefing', 'what's interesting today?') and a situational pattern ('start of a morning routine'). It stops short of stating when NOT to use it in favor of the granular sibling tools, so the routing back to get_market_context / get_insider_activity is left implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds useful substance about what is disclosed (update schedule, sources, known limitations), though it says nothing about response shape or any access constraints.

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, no filler: the first defines the payload, the second defines the triggers. Front-loaded and tightly scoped.

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?

An output schema exists to describe return values, and there are no parameters to explain. What remains for the description — scope, freshness/limitation disclosure, and when to call — is fully covered.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline applies. The description correctly implies a no-argument call.

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

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

Names a specific verb+resource: reports the dataset's coverage, freshness, update schedule, sources, and known limitations. That is distinct from the data-fetching siblings. It does not explicitly separate itself from about_capitalsnitch, the one sibling that plausibly overlaps, so it falls short of 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 concrete triggering contexts ('how current is this?', 'what data do you have?') and a proactive rule ('before making time-sensitive claims'). It stops short of an exclusion like 'use about_capitalsnitch for company/product info 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?

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond annotations, including that private Rule 144A deals announced only in an 8-K are included, that 8-K filings cover the last 30 days, and that price reactions are measured at day 1, day 2, 1 week, and 1 month versus the prior close.

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

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

The description is dense but front-loaded with the full scope of data returned and followed by practical example questions. The long enumerated list is justified by the complexity of the resource, though it could be slightly more scannable.

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

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

Given an output schema, four annotations, and full schema description coverage, the description is complete enough for correct invocation. It covers the return content, time windows, included filing types, and example use cases without needing to repeat parameter or output details already in structured 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 100%, and the schema itself documents both ticker and years. The description implies offering-history filtering but does not add meaning beyond the schema, such as clarifying how the years parameter interacts with the score or share-count trend, so the baseline of 3 is appropriate.

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

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

The description states a precise retrieval purpose: every stock offering, ATM program, convertible note, shelf registration, related 8-K filings, share-count trend, and dilution-risk score. It clearly distinguishes this tool from sibling tools focused on insider activity, financials, or market context, and an agent can identify the exact resource without opening the schema.

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

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

It gives explicit example questions such as 'has SOFI diluted shareholders?' and 'what happened to the price after the last offering?', which clarifies when to use the tool. It does not name alternatives or exclusions, but the use context is clear enough for correct selection.

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

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

Annotations already cover read-only/idempotent/non-destructive safety, so the description correctly focuses on substance: it discloses that results are joined with insider activity, include time-of-day (before open / after close) and a countdown, and that buying is limited to open-market purchases in the look-back window. Pagination and the effect of the limit cap are not mentioned, which keeps it at 4.

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

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

Three sentences, front-loaded with the core behavior, then the flag's payoff and the tickers variant. The 'rare and closely watched signal' clause justifies the flag's importance rather than repeating mechanics, so only minor trimming is possible.

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 rich annotations, an output schema, and 80% parameter coverage, the remaining burden on the description is small and it meets it; only the limit/result-cap behavior is unaddressed, which is minor given the 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?

Schema coverage is 80%, so the baseline is 3, but the description adds real semantic meaning: it explains what only_with_insider_buying=true selects and shows the tickers pattern for the single-company case. days_ahead and insider_lookback_days are left entirely to the schema.

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

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

States a specific verb+resource (companies reporting earnings soon) and the enrichment performed (joined with recent insider activity, date/time, countdown). The insider-join framing also separates it from pure insider tools like find_insider_buying, so an agent can tell what it uniquely returns.

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

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

Gives two concrete usage contexts: the only_with_insider_buying=true case ('which companies reporting soon have insiders been buying?') and the 'when does X report?' case with the exact parameter values to pass. It does not name sibling alternatives or state exclusions, so it stops short of a 5.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds meaningful context beyond that by disclosing the SEC filing source, the derived growth classifications (growing/flat/declining, accelerating/slowing), and the quarter-by-quarter table format.

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

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

The description is dense but front-loads the source and core contents, followed by example queries. Every sentence contributes useful information, though the long metric list is somewhat run-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?

Given the presence of an output schema and rich structured parameter definitions, the description is largely complete: it covers data provenance, return contents, and typical user questions. It stops short of noting data freshness or filing lag, which would be useful for an agent relying on SEC-derived data.

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

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

Schema coverage is 100%, so the ticker and quarters parameters are already fully documented. The description only implicitly references the quarters parameter via 'show the last 8 quarters' and does not add constraints or format details beyond what the schema provides.

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

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

The description states a precise resource—company fundamentals sourced from SEC 10-Q/10-K filings—and enumerates the specific metrics covered, including valuation, growth, margins, and quarterly trends. It is clear what the tool returns, though it does not explicitly name sibling tools like get_company_context or get_market_context to differentiate itself.

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

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

It provides concrete example questions ('is revenue growing?', 'what's the P/E?') that map directly to use cases. However, it does not state when not to use this tool or point to alternatives for adjacent needs such as market context or earnings timing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds some value beyond that: scope is limited to the *latest* filing plus a comparison against the immediately prior quarter, so the agent knows this is not an arbitrary historical range. It says nothing about 13F reporting lag (filings trail quarter-end by ~45 days), manager-name matching behavior, or coverage gaps – relevant for a data-lookup tool but not disqualifying given 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?

Front-loaded with the payload contents, then the change data, then intent examples – a sensible order with no filler. The opening sentence is long and runs the return contents and the comparison set together, costing a little readability.

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

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

An output schema exists, so the description needn't restate return shapes, and with 100% schema coverage the parameters are self-documenting. What's still missing for correct invocation is the freshness contract (13F filing lag) and any hint about how loosely 'manager' is matched, plus the boundary against get_institutional_ownership.

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%: both 'manager' and 'top' are already documented in the schema with bounds and examples. The description reinforces semantics implicitly ('top holdings with % of portfolio' explains what 'top' controls, and the example queries clarify what kind of string 'manager' accepts) but adds no format or matching rules beyond the schema.

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

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

Names a specific resource (a fund's latest SEC Form 13F portfolio) and enumerates exactly what it returns: total value, position count, top holdings with percentages, plus quarter-over-quarter changes (new, sold out, biggest adds/cuts). That is far beyond a restatement of the name. It stops short of 5 because it never distinguishes itself from the sibling get_institutional_ownership, which an agent could plausibly confuse with this.

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 three quoted example queries ('what did Berkshire buy last quarter?', 'top holdings of Bridgewater', 'did Ark sell Tesla?') map concrete intents onto this tool, which effectively tells an agent when to pick it. It gives no explicit exclusions or pointer to an alternative for overlapping ownership data.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description contributes the returned content shape (roles, amounts, filing links) but says nothing beyond annotations about pagination, rate limits, auth, sorting, or what happens at the 3650-day/100-trade caps.

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

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

Two sentences, front-loaded with the verb and resource, followed by an enumeration of return contents and illustrative queries. Every element earns its place; the example list is slightly verbose relative to the short body but still useful.

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

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

With an output schema present, the description needn't explain return values in detail, and annotations plus 100% schema coverage handle parameters and safety. It is close to complete for a read-only list tool; only ordering and result-size behavior are unaddressed.

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

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

Schema description coverage is 100%, so all four parameters including open_market_only's semantic distinction are documented in the schema itself. The description only loosely gestures at the time window ('this year') and adds no syntax or default rationale, so baseline 3 applies.

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

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

The description uses a specific verb-plus-resource pair ('List and summarize insider trades (SEC Form 4) for one company') and enumerates the returned fields (buyer/seller, date, amount, role, filing link). It never names or contrasts a sibling such as get_insider_signal, find_insider_buying, or get_insider_person, so the tool is clear on its own but not differentiated from the crowded insider-tool family.

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?

Concrete example questions ('are insiders buying or selling NVDA?', 'show Tesla insider trades this year') give an agent a reliable trigger condition. What's missing is routing guidance: there is no statement of when to prefer get_insider_signal, find_insider_clusters, or get_insider_person, and no exclusions.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral scope by specifying open-market trades only, across all companies, with totals, though it does not discuss authentication, rate limits, or pagination.

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

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

The description is two sentences and front-loads the core action. Examples follow immediately and every sentence earns its place without repetition.

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

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

With rich annotations, full schema coverage, and an output schema, the description provides enough context to call the tool correctly. The only meaningful gap is not clarifying how this differs from closely related sibling tools such as get_insider_activity.

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

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

Schema description coverage is 100%, so the schema already documents name, days, and limit. The description adds contextual meaning around insider roles and partial-name matching via examples, but does not add parameter-specific details beyond what the schema provides.

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

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

The description states a specific verb and resource: find an insider by name and list their open-market trades across all companies, with totals. It distinguishes the tool as person-centric, but does not explicitly name sibling alternatives such as get_insider_activity or find_insider_buying.

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

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

The description gives clear example use cases ('what has Warren Buffett bought recently?' and 'Jensen Huang stock sales'), which tells the agent when this tool is appropriate. However, it provides no when-not guidance or explicit comparison to sibling tools like get_insider_activity.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real substance beyond that: the 0–100 scale with 50 as neutral, the 5-year self-comparison baseline, and that output includes evidence trades and SEC links. It doesn't discuss data lag or what happens when history is too short.

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

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

Two sentences, front-loaded with the score-and-explain core, then the trigger queries. The factor list is long but each item carries distinct meaning; no filler is present.

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?

An output schema exists and annotations cover safety, so the description only needs to frame intent and interpretation — which it does, including how to read the score. Only minor gaps (data coverage limits, behavior on sparse insider history) remain.

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% — both ticker and days are documented in the schema with range and example. The description adds no further parameter semantics (e.g., how the days window interacts with the 5-year comparison baseline), 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 precise verb+resource+output: 'Score current insider behavior for one company (0–100, 50 = neutral) and EXPLAIN it', then enumerates the exact factors composing the score. That clearly separates it from raw-list siblings like get_insider_activity or find_insider_clusters, though no sibling is named explicitly.

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

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

Gives concrete trigger questions ('is insider activity at X bullish or bearish?', 'anything unusual about insiders at X?') that make the intended use unambiguous. It stops short of exclusions or naming which sibling to use for raw trade lists or individual insiders.

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 a safe, idempotent, closed-world read. The description adds genuine context beyond that: the data source and its $100M+ AUM reporting threshold, the quarter-over-quarter comparison basis, and a tier-gated output difference ('Analyst and Edge also get the lists of new funds, sold-out funds, biggest adds and biggest cuts'). It says nothing about data lag or filing latency, which matters for 13F data.

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

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

Front-loaded with the core answer ('Who owns a stock...') and then the return fields, with example queries last. The first sentence is long and clause-heavy but nearly every clause carries distinct information; the tier note is a minor digression mid-payload.

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 an output schema present, the description needn't explain return formatting, and it still covers source, scope, tier differences, and query intents. An agent has everything needed to decide to call this and pass a ticker correctly.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the 5–25 range and default 10 for 'top'. The description only references 'top holders' loosely and adds no syntax or nuance 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 ('Who owns a stock, from SEC Form 13F filings') and enumerates the exact data returned: holder count, ownership share, top holders with QoQ change, and open/add/cut/sold-out counts. It is clearly distinguishable from the inverse sibling get_fund_holdings, which looks up a fund's positions rather than a stock's owners.

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

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

Provides four concrete example phrasings ('who owns PLTR?', 'are funds buying or selling NVDA?', 'top institutional holders', 'did hedge funds add last quarter?') that map user intent to this tool. It does not, however, name an alternative or state when not to use it versus get_fund_holdings or get_congress_trades.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is fully covered. The description adds what data categories are computed (regime derived from S&P 500 trend and VIX) but says nothing about data freshness, update cadence, or source — the traits a market-data tool most needs to disclose. Additions beyond annotations are modest.

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 headline purpose, then the payload inventory, then example queries — good ordering with no filler. The payload enumeration is dense and slightly list-like, but every item is a distinct data category an agent would want to know is available.

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?

An output schema exists, so return values need not be explained, and the description nonetheless signals breadth of coverage. The remaining gap is operational context: no note on how current the data is or whether markets must be open — relevant for a 'backdrop' snapshot.

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?

Zero parameters, so the baseline of 4 applies; there is no parameter semantics to explain and the description correctly spends no words on inputs.

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

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

Specific verb+resource ('Current U.S. market backdrop in one call') with the exact contents enumerated: regime taxonomy, VIX level/percentile, Fed funds, 2y/10y yields, curve shape, and FOMC meetings with implied odds. Clearly distinguishes it from siblings like get_daily_brief or get_company_context, which are company- or brief-oriented rather than macro backdrop.

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

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

Provides three concrete trigger phrasings ('what's the market backdrop?', 'when is the next Fed meeting?', 'odds of a rate cut?') that make the intended use obvious. It stops short of naming an alternative or stating when NOT to use it, so it is clear context without explicit 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?

Beyond the annotations, the description discloses important behavior: the call is free and does not count toward the daily question limit, and authentication is via the personal connection address with no email or password required. These are exactly the operational details an agent needs and annotations do not provide.

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

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

The description is front-loaded with the account contents, then usage examples, then authentication context, and it is reasonably efficient. Some field enumeration overlaps with what the output schema likely provides, and a few clauses could be tightened, but it is not bloated.

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

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

With zero parameters, an output schema, and safe read-only annotations, the description is complete: it explains what the account object covers, when to call it, that it is free, and how the user is identified. An agent has everything needed to select and invoke it correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds relevant context that no email/password is needed because the user is inferred from the connection, but there are no parameters whose semantics require further explanation.

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

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

The description clearly identifies the resource as the user's own CapitalSnitch account and enumerates the concrete account/subscription information it exposes: plan, status, renewal/expiry dates, payment method, quota usage, and feature access. The phrase 'user's own' distinguishes it from account-adjacent siblings such as about_capitalsnitch and buy_plan without ambiguity.

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

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

It gives concrete trigger phrases ('what plan am I on?', 'when does my subscription renew?', 'is my plan active?', 'how many questions do I have left?'), which is strong usage context. It does not explicitly state when not to use it or name alternatives like get_account_link or buy_plan, so it falls short of a full 5 under the rubric.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety needs little elaboration. The description does add two things annotations cannot: the result ordering (newest first) and the quota note 'Never counts toward the daily limit', which is genuinely useful context. It stops there — nothing about what an entry contains or how alert vs briefing emails are distinguished — so with annotations carrying most of the load this sits at a solid 3.

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

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

Two tight sentences: the resource and ordering come first, then concrete query triggers. No filler, no restatement of the title.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile; the description supplies scope, ordering, plan gating, and quota behavior. The only gap is that it doesn't say how mixed alert vs daily-briefing emails are presented, which matters slightly for interpreting results.

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

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

Schema coverage is 100% and the single 'limit' parameter is already documented with its 1–50 range and default in the schema. The description adds nothing about the limit (e.g., what happens when more exist than requested), 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?

Names a specific resource — the alert and daily-briefing emails CapitalSnitch sent the user — with ordering ('newest first'), making it clearly an inbox-style read rather than a content lookup. It does not explicitly name the closest sibling (get_daily_brief) to disambiguate 'briefing email' from 'brief content', so it stops just 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?

Two concrete trigger phrasings ('what alerts did I get today?', 'did anything trigger on my watchlist?') give an agent clear use context. No when-not-to-use or explicit alternative is stated, so the routing burden for adjacent tools like get_daily_brief is left implicit.

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

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

Annotations already declare mutation (readOnlyHint=false), idempotency, and non-destructiveness; the description adds context the annotations cannot: the plan-level 25-ticker ceiling, the ~30-minute alert latency after an SEC filing, downstream effects (leading the daily email briefing), and that calls never consume the daily quota. It does not flag how the replace action overwrites the existing list, which is the one genuinely risky behavior left undisclosed.

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?

Identity and plan cap are front-loaded, then benefits, then example phrasings, so the agent gets the essentials immediately. Some promotional phrasing ('INSTANT EMAIL ALERTS', 'lead the daily email briefing') is slightly padded, though it does convey real downstream behavior.

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 an output schema present the return shape needn't be explained, and annotations plus full schema coverage handle safety and parameters. Against that, the description supplies the plan limit, alert timing, and quota exemption. The remaining gap is replace semantics and error behavior when the 25-ticker cap is exceeded.

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

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

Schema description coverage is 100% and both parameters, including the action enum with per-value meanings, are fully documented in the schema, so the baseline is 3. The description adds the practical constraint of a 25-ticker Edge-plan cap, which is real value, but it does not clarify ticker resolution behavior (symbol vs. name) or what 'replace' does to existing entries.

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 precisely (the user's CapitalSnitch watchlist) and the effects of membership (instant alerts, daily briefing inclusion), and the sample utterances implicitly enumerate the operations list/add/remove. It stops short of explicitly contrasting itself with adjacent siblings like get_my_alerts or set_alert_preferences, so an agent must infer that this tool owns membership rather than alert delivery settings.

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?

Four concrete user utterances cover the main invocation contexts (alert me on insiders, add tickers, what am I watching, stop alerting), which maps cleanly onto list/add/remove. There is no explicit 'do not use this for X, use Y instead' routing, and the boundary with set_alert_preferences (tuning what kinds of alerts fire) is left implicit.

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

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

The annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so safety is covered. The description adds that results come from recent insider filings and include official names and CIK numbers, which is useful. It says nothing about matching semantics (fuzzy/prefix vs exact), ranking, or how many results are returned when multiple companies match.

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, and the core purpose is front-loaded before the usage conditions. Every clause carries information an agent needs.

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 only two parameters and an existing output schema, the description need not describe return values, and it correctly focuses on data source and trigger conditions. The one gap is the undocumented 'limit' parameter, which neither the schema nor the description explains.

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

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

Schema coverage is 50%: 'query' is documented in the schema with an example, but 'limit' has no description anywhere. The description's phrase 'ticker fragment' echoes the schema rather than adding format guidance, and it does not explain what 'limit' controls. Baseline 3 is appropriate given the schema carries the query semantics.

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 specific verb and resource ('Look up tickers and official company names') and names the data source (recent insider filings, SEC CIK). It is clearly distinct from data-fetch siblings like get_company_context or get_financials, which retrieve content rather than resolve an identifier, though it does not explicitly name those siblings.

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

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

It states two concrete trigger conditions: the user names a company without a ticker, or a ticker lookup returns nothing. That is real when-to-use guidance. It stops short of naming the alternative resolution path (e.g. get_company_context) or any exclusions, so it is strong but not complete.

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 idempotent, non-destructive write semantics; the description adds the plan gate ('Edge plan'), the partial-update contract (omitted settings stay unchanged), and a quota fact ('never counts toward the daily limit') that is not encoded anywhere in structured data. It does not say what happens on a non-Edge account or whether a confirmation/response shape is returned.

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 action and resource, then the three channels, then the update semantics, then the quota fact — a sensible priority order with no filler. The quoted example utterances are the only slightly padded element.

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

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

An output schema exists so return values needn't be explained, and the description still conveniently covers the empty-call read behavior. Combined with plan gating and partial-update semantics, an agent has enough to call it correctly; only the behavior when the user is not on Edge is unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the key semantic the schema lacks: a null/omitted value means 'leave unchanged' rather than 'disable', and a fully empty call turns into a read. That meaningfully improves correct invocation of the nullable booleans.

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 (turn on/off) and resource (the user's CapitalSnitch email alerts) and enumerates the three distinct alert channels, which maps directly to the three parameters. It does not differentiate itself from the sibling get_my_alerts, so an agent must infer the routing itself.

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

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

Gives explicit call patterns ('omit a setting to leave it unchanged', 'call with no settings to see the current ones') plus three example user utterances that anchor intent. No exclusion guidance against get_my_alerts, which handles a similar read use case, so it stops short of full 5-level clarity.

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

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

Annotations only say the call is a non-read-only, non-idempotent, open-world write. The description adds the material behavior annotations cannot express: it sends an email, it is a two-step flow, the first call returns the key terms, the terms must be explicitly accepted, and it is 'Free to call' (no charge incurred at this step).

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

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

The purpose and the step-1-of-2 framing are front-loaded, followed by the pre-call checklist, which is the right order. The embedded pricing ladder is the only bulk; it is useful but could be compressed or deferred to the plan schema. Little else 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 6-parameter, non-idempotent onboarding write with an output schema, everything an agent needs to call it correctly is present: prerequisites, the terms-acceptance mechanic, what the call returns to the user, and the handoff to confirm_signup.

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

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

Schema coverage is 100%, so the schema already explains each field; the description nonetheless adds business meaning the schema lacks — the four plan tiers with prices and the yearly = two-months-free, one-time, never-auto-renewing billing model, plus the card-or-crypto prompt. It does not restate plan/billing/crypto syntax, but the pricing context is genuinely additive.

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

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

The description names a specific verb and resource ('Create a CapitalSnitch account — or sign back in') and explicitly frames itself as 'Step 1 of 2: emails the user a 6-digit code,' which separates it cleanly from confirm_signup. An agent can route between the two without opening either schema.

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

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

It states what to do before calling (ask about plan, collect payment preference, show key terms), what happens after (ask for the code, then call confirm_signup(email, code)), and the exact gating rule for user_accepted_terms ('call once without user_accepted_terms to get them... only after an explicit yes'). Alternatives and sequencing are unambiguous.

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