Alphanume Datasets

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful context beyond those hints: it checks API-key validity and returns status/version, making the tool's diagnostic role clear. No contradiction with annotations.

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

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

The description is two sentences with no filler. The main purpose is stated first, followed immediately by a practical directive on when to use the tool.

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 diagnostic tool, the description covers what it checks, what it returns, and when to call it. The absence of an output schema is mitigated by explicitly stating that status and version are returned.

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 has zero parameters, so the description cannot add parameter-specific meaning. A baseline of 4 is appropriate because no parameter documentation is needed.

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 (Alphanume API), the action (connectivity and API-key check), and the outputs (status and version). It also implicitly distinguishes itself from the sibling data tools by positioning this as the diagnostic health check rather than a data endpoint.

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 an explicit usage trigger: 'Call this first if any other tool errors', and explains the diagnostic purpose—distinguishing a bad/missing API key from a dataset-specific problem. This is strong routing guidance for an agent deciding between 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses important behaviors: rows re-label when FDA materials change, no-tally rows carry vote_evidence explaining why, the forward calendar is included, and tallies are verified against official PDFs. It also explains the real-world latency around minutes publication. No contradiction with annotations.

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

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

The description is long but dense and front-loaded: the first sentence establishes scope and data source, followed by row semantics, update behavior, and operational caveats. Each paragraph earns its place by explaining a distinct aspect of the data an agent needs to call and interpret the tool correctly.

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 19 optional parameters, no output schema, and read-only annotations, the description is unusually complete: it states the row model, the meaning of placeholders, update timing, auth requirements, error interpretation, and the sparse-data caveat. An agent can both invoke the tool and interpret results without major blind spots.

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

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

The input schema already documents all 19 parameters with 100% description coverage, so the baseline is 3. The description adds useful semantic context around the data model, such as vote_evidence distinguishing 'no data' from 'no vote,' but it does not meaningfully elaborate on individual parameter formats or constraints beyond what the schema already 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 names a specific resource (FDA advisory-committee votes) and a precise scope (every drug/biologic AdCom meeting from 2024 forward), with the row unit defined as one row per meeting/vote question. It also specifies the exact data provenance: tallies extracted and verified against official minutes PDFs. This clearly differentiates it from generic FDA or market-data siblings.

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

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

The description provides practical usage context: minutes arrive months later, recent rows may be minutes_not_posted, short date windows can be legitimately empty, and 403 errors indicate plan limitations rather than missing data. It stops short of naming sibling alternatives or explicitly saying when to prefer another tool, so it does not reach 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that fields are null when the filing text does not explicitly support them, that an API key is required, and that specific errors indicate plan limitations rather than missing data. This materially helps the agent interpret results and troubleshoot failures.

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

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

The description is front-loaded with the core purpose and row structure, followed by use cases and error semantics. Every sentence contributes useful information and there is 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?

With no output schema, the description compensates by listing the returned fields in detail, explaining null behavior, and covering error semantics. Combined with full schema coverage for parameters and clear annotations, an agent has everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the input schema already explains each date parameter and max_rows. The description reinforces the date-range monitoring use case but does not add parameter-specific meaning beyond what the schema provides, matching the baseline expectation.

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 (corporate default events from SEC filings) and answers the exact question the tool addresses: which public companies just defaulted and on what terms. It enumerates the row structure and enriched fields, clearly distinguishing it from the finance-focused sibling tools.

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

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

The description states explicit use cases: distressed screening, credit event studies, and monitoring date ranges for fresh defaults. It does not name alternatives or explicitly say when not to use the tool, but there is no obvious sibling with overlapping functionality, so the context is sufficient.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful extra context: an API key requirement, the meaning of specific 403 error codes, that one matter can appear once per agency, that monetary relief repeats across respondent rows, and that date filters apply to published_date rather than action_date. This goes well beyond the annotation baseline.

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 tightly organized: it starts with the product definition, then explains row semantics, date behavior, deduplication, and auth/error handling. Every sentence carries operational or semantic weight; there is no filler or repetition of schema content.

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

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

For a 28-parameter read-only tool with no output schema, the description covers the essential context: data source scope, row granularity, output field semantics, date-window behavior, deduplication pitfalls, authentication requirements, and error interpretation. Pagination details live in the schema, which is appropriate. An agent has everything needed to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents every parameter clearly. The description adds cross-cutting semantics that the schema cannot express: monetary_relief_usd repeats per respondent row and requires de-duplication on action_key before summing, and nothing links across agencies. This is exactly the kind of parameter-level clarification that helps an agent avoid misaggregation.

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

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

The description opens with a precise resource definition: 'US digital-asset enforcement, one normalized tape across the three agencies' and names the three agencies individually. It clearly differentiates this tool from all sibling financial-data tools by its unique domain and row structure.

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

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

The description gives strong usage context: data coverage from 2024+, the 'one row per (action, respondent)' unit, de-duplication guidance before summing monetary relief, and how to interpret 403 errors. It does not explicitly name a sibling alternative, but no sibling appears to overlap with this specialized enforcement dataset, so exclusions are not critical here.

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

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

Beyond the annotations, the description discloses critical behavioral traits: flags are three-state and 'never collapsed,' amendments are separate rows linked to originals, materiality_determined_date is sparse (~15% fill), and days_determination_to_disclosure uses calendar days while the SEC deadline uses business days. It also clarifies that a 403 error means plan restrictions, not missing 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?

The description is long but densely informative, with the core population and scope stated first, followed by row semantics, flag behavior, date caveats, and API error interpretation. Every sentence adds necessary operational detail; there is no redundancy or filler.

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

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

Given 18 parameters, no output schema, and a complex domain, the description is remarkably complete: it explains population size, row-level granularity, date semantics, amendment modeling, sparse fields, calendar-day caveats, required API key, and error interpretation. An agent has enough context to select and invoke the tool correctly.

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

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

Even with 100% schema coverage, the description adds substantial meaning beyond the parameter list: the four distinct date roles, calendar-versus-business-day adjustment, NULL semantics for three-state flags, amendment linkage fields, and pagination behavior. This directly prevents misinterpretation when using date, flag, and amendment-related parameters.

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

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

The description states a specific verb and resource: retrieving material cybersecurity incidents from every Form 8-K filed under Item 1.05 plus 8-K/A amendments, described as the 'entire population, ~80 filings and growing.' It clearly differentiates the tool from generic SEC-filing siblings by specifying row granularity, date roles, and amendment linkage.

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

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

The description provides clear context: this is the cyber-incident 8-K dataset, with explicit explanatory notes about amendment rows, flag semantics, date calculations, and authentication errors. It does not explicitly name sibling tools or state when to use this tool versus alternatives, so it stops 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 already declare readOnly, openWorld, idempotent, and non-destructive behavior; the description adds substantial context beyond those: the meaning of date as the SEC filing date, ticker as the current trading symbol, null-field semantics, quality_flags behavior, and 403 error interpretation. This gives the agent a clear model of how data behaves without contradicting the annotations.

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

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

The description is long but densely packed with necessary details that the absent output schema would otherwise leave uncovered. It is well-structured: a lifecycle/field paragraph, a data-semantics paragraph, and an actionable usage paragraph. It could be slightly tightened, but every major sentence adds 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?

Given the tool's complexity, 12 optional parameters, rich annotations, and no output schema, the description is complete: it explains row granularity, all milestone and financial fields, null/quality handling, point-in-time history, common query patterns, and API-key/error behavior. An agent can select and invoke this tool correctly with no further context.

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

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

Schema descriptions cover 100% of the 12 parameters, so the baseline is 3. The description adds meaning by tying key parameters to use cases (status+pending+upcoming, view=history) and clarifying derived dates and the ticker rename behavior. It does not simply repeat the schema, earning an above-baseline score.

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 pair: it returns one row per SPAC business combination tracked across a defined lifecycle. It distinguishes itself from the many sibling get_* tools by naming the exact domain (De-SPAC) and the full list of milestones and financial fields returned.

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 four concrete usage recipes: status=pending&upcoming=true, ticker=<symbol>, view=history, and status=completed with a date range for redemption-rate studies. It clearly explains when each is appropriate, though it does not explicitly state when not to use this tool versus a sibling; the sibling topics are sufficiently different that this is a minor gap.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: API key requirements, and the meaning of 403 errors (subscription/date-range restriction rather than missing data). This meaningfully helps agents interpret failures correctly.

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 tool's purpose and output shape, then gives use cases, filter limitations, and error semantics. It is somewhat long due to the field enumeration, but every part contributes useful information and nothing feels redundant or 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?

With no output schema, the description compensates by fully enumerating the returned row fields. It also covers authentication, error interpretation, filter boundaries, and practical use cases. An agent has enough information to invoke the tool correctly and interpret the response meaningfully.

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

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

The input schema already covers all parameters with descriptions, so the baseline is 3. The description adds useful parameter semantics by stating that filtering is limited to ticker and filing-date range and explicitly calling out that there is no exact-date parameter. This helps an agent choose date filters correctly without over-specifying.

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 S-1 dilution filings and specifies the exact row-level content (ticker, filing timestamp, dilutive/resale flags, effectiveness/withdrawal status, SEC links). It is distinct from generic filing tools, but it does not explicitly differentiate from the closely related sibling get_shelf_registrations, so it falls just short of full sibling differentiation.

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 explicit use cases: flagging dilution overhang, tracking time-to-effectiveness, and building event studies. It also clarifies the available filter scope (ticker and filing-date range, no exact-date parameter). It does not state when to prefer a sibling tool, but the context is clear enough for basic 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?

The annotations already mark this as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: the exact output row structure, interpretation guidance for drop ratio, requirement for a Pro API key, and the meaning of specific error codes. This goes well beyond what the annotations alone provide.

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

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

The description is dense but every sentence carries distinct value: purpose, output structure, mode selection, interpretation guidance, and error handling. It is front-loaded with the core purpose and avoids redundancy with the schema.

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

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

With no output schema present, the description carries the full burden of explaining return values, and it does so thoroughly: row granularity, schedule fields, price-action fields, recovery flags, and interpretation. It also covers authentication requirements and error semantics, making the tool callable without external documentation.

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

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

The schema already documents all 10 parameters with descriptions, so the baseline is 3. The description adds useful semantics beyond the schema, such as how upcoming=true and future_days define the forward calendar, how ticker maps to full capture history, and how to interpret recovery-related output. This lifts the score slightly above 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?

The description explicitly identifies the resource as a dividend-capture calendar and scorecard, including the exact questions it answers and the output granularity (one row per ex-dividend event). This clearly distinguishes it from sibling tools, which cover unrelated market or event 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?

The description gives explicit mode instructions: set upcoming=true for the forward calendar and use ticker for a single name's capture history. It also explains that 403 errors indicate plan restrictions rather than missing data. It does not name alternative sibling tools, but the tool is distinct enough that the mode guidance is sufficient.

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

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

Annotations already mark this read-only, idempotent, open-world, and non-destructive, and the description does not contradict them. It adds substantial behavioral context: one row per earnings event per ticker, the meaning of the 403 errors (plan limitation, not missing data), and the Pro API key requirement. This goes well beyond what annotations alone communicate.

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 detailed but every sentence earns its place. It front-loads the core purpose, lists the output fields compactly, gives direct usage instructions, and closes with error interpretation. There is 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?

Given seven optional params, no output schema, and a large sibling set, the description covers the essentials: what the data represents, what fields are returned, how to use ticker and date, the auth requirement, and how to interpret errors. The input schema handles filter mechanics, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful domain context: it tells agents that ticker is how you evaluate historical straddle profitability for a name and clarifies that date means the earnings date. This enriches the parameter semantics beyond the raw schema descriptions.

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 ('earnings move track record') and a precise diagnostic question: whether the options market systematically over- or under-prices earnings moves. It also enumerates the output in concrete terms (straddle price, implied move, realized move, overpricing gap, flag, EPS data), which makes it unambiguously distinct from siblings like get_iv_hv_premium or get_momentum_index.

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

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

The description gives explicit, actionable usage guidance: use it before an earnings trade by querying ticker to assess whether selling or buying the straddle has paid, or screen by date to review recent reporters. It does not explicitly name alternative tools or when-not-to-use conditions, but the intended context is clear enough.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses default row counts, that date filters apply to disclosed_date, linkage of follow-ups/resolutions per program, the selective-disclosure limitation, and auth-related 403 meanings. No contradiction with annotations.

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

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

The description is long because the tool is complex, and it is front-loaded with the core purpose before caveats and auth. Every sentence carries information, but some clauses are dense and could be tightened 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 complex 18-parameter read-only tool with no output schema, the description covers default scope, optional reject rows, date semantics, linkage model, selective-disclosure limits, and error interpretation. This is sufficient for an agent 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?

Although schema coverage is 100%, the description adds cross-parameter meaning: date window semantics, days_letter_to_disclosure only on initial_disclosure rows, filing_role overstating event counts ~2.4x, and severity rank encoding precedence rather than market impact. This materially helps correct parameter selection.

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

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

The description opens with a specific verb-resource pairing: adverse FDA regulatory actions disclosed in 8-Ks, enumerating CRLs, full/partial clinical holds, and refuse-to-file letters. This clearly distinguishes it from sibling tools covering other event types like cyber incidents or SEC trading suspensions.

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 establishes the domain and scope explicitly, including a when-not caveat: CRLs disclosed only in a 10-Q or never are not present. It also explains default vs include_rejects behavior, though it does not name alternative sibling tools for out-of-scope queries.

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

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

Even with readOnly, openWorld, idempotent, and non-destructive annotations, the description adds meaningful behavioral detail: a 50,000-row per-request cap, cursor-based pagination semantics, the need for an Alphanume Pro API key, and the specific meaning of 403 errors. This goes well beyond the annotations.

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

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

The description is well-structured, front-loaded with the core definition, then usage, pagination, and error context. The 'corporate action fingerprints' sentence adds useful intuition and is not excessive; each remaining sentence carries operational weight.

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

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

For a 14-parameter tool with no output schema, the description covers what an agent needs: row schema, pagination mechanics, request-size limits, authentication requirements, and error interpretation. This is a high-complexity tool, and the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by showing how parameters are meant to be used, e.g., screening with filing_count_gte, pulling ticker history, and using cursor_date/cursor_ticker for pagination. It also clarifies that max_rows should not be raised as a substitute for narrowing filters.

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

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

The description clearly defines the resource: the number of EDGAR filings per company per day, with an explicit row shape (ticker, company name, date, filing_count). This distinguishes it from sibling tools by domain (SEC filing cadence) and by data granularity, so an agent knows exactly what it 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?

It gives concrete use cases: screening filing_count_gte over recent dates for unusual filing bursts, or pulling one ticker's history for regime changes. It provides actionable guidance for parameter selection and pagination, but it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Beyond the readOnly/idempotent annotations, the description discloses significant behavior: no restatement, no survivorship bias, 50,000-row pagination cap, has_more/next_cursor mechanics, and the 7-day range limit. It also explains that PRO_SUBSCRIPTION_REQUIRED and DATE_RANGE_RESTRICTED errors mean the plan does not cover the request rather than missing 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?

Three structured paragraphs front-load the core semantics, then move through requirements, pagination, companion tools, and auth/error handling. Every sentence contributes operational or selection value with no filler.

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

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

For a 9-parameter read tool with no output schema, the description supplies return fields (market_cap, shares_outstanding), pagination details, limits, companion tool guidance, and error interpretation. No critical operational gap remains 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 already covers all 9 parameters with descriptions, so the baseline is 3. The description adds meaning beyond the schema: the ticker-or-date-filter requirement, the cursor_date/cursor_ticker coupling rule, pagination behavior, and the range cap, which is valuable operational context the schema alone does not convey.

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

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

Description names a specific verb and resource: point-in-time historical market capitalization with daily market_cap and shares_outstanding per US ticker. It also states the key data semantics (no restatement, no survivorship bias), and names the companion tool list_market_cap_tickers, distinguishing it from related sibling tools.

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

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

Explicit invocation rules are provided: provide ticker OR at least one date filter, a bare date returns the whole market, and a date range without ticker is capped at 7 days. It also routes agents to list_market_cap_tickers for checking ticker availability and clarifies 403 error meaning, giving strong when-to-use and troubleshooting 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?

Beyond the readOnly/idempotent annotations, the description discloses meaningful runtime behavior: rows update intraday with is_final=0 and settle after close with is_final=1. It also explains the API-key requirement and clarifies that 403 errors mean plan restrictions, not missing data. This is exactly the kind of context that helps an agent interpret unexpected responses.

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

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

The description is dense but every sentence earns its place: the screener's question, the universe and metrics, intraday/settlement behavior, use cases, filter hints, and auth/error semantics. It is front-loaded with the core purpose and avoids filler or repetition of schema details.

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 an 11-parameter tool with no output schema, the description gives the agent enough context to call it correctly and interpret what comes back. It enumerates return row contents, explains is_final semantics, provides screening examples, and covers the one likely error condition. Nothing essential is missing.

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

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

The input schema already covers 100% of parameters, so the baseline is 3. The description adds interpretive value by linking filters to real screening goals, such as using min_iv_hv_ratio >= 1.5 for options priced 50% over realized vol and max_iv_hv_ratio for cheap options. This contextual framing goes beyond the schema's literal parameter definitions.

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

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

The description opens with a specific question ('are this name's options rich or cheap right now?') and enumerates the exact metrics computed: 30-day ATM IV vs HV, spread, ratio, percentile ranks, z-scores, notional volume, and ATM details. This clearly differentiates it from sibling tools like get_iv_rank or get_vol_of_vol by focusing on the IV/HV premium cross-sectional screener rather than single-name rank or volatility-of-volatility.

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

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

The description explicitly states when to use the tool: to find overpriced premium to sell, underpriced options to buy, or to track a ticker's premium history via `ticker`. It also gives concrete filter-based guidance like high iv_hv_ratio / min_ratio_rank near 1. However, it does not explicitly say when not to use it or name an alternative sibling for adjacent use cases.

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

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

The description discloses that rows update intraday and settle after the close (is_final=1), that the default latest value may be provisional, and that 403 PRO_SUBSCRIPTION_REQUIRED or DATE_RANGE_RESTRICTED errors are about plan coverage rather than missing data. These details go well beyond the annotations and materially help an agent interpret behavior and failures.

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 organized: core concept first, then update behavior, then a use case, then authentication/error context. Every sentence contributes something necessary, and no filler or vague phrasing 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?

With 13 optional parameters, no output schema, and many siblings, the description covers the essential context: the data universe, the computed metrics, update timing, filtering semantics, and the meaning of common auth errors. An agent has enough information to call the tool correctly and interpret the 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 description coverage is 100%, so the baseline is 3; the description adds value by defining what iv_rank, hv_rank, iv_percentile, and hv_percentile actually measure. It also gives min_iv_rank a practical interpretation, complementing the schema without redundantly restating each 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?

The description clearly identifies the resource (IV/HV rank and percentile within each name's trailing 52-week range for US optionable equities) and the tool's core purpose: answering whether volatility is high or low relative to that name's own history. It lacks an explicit retrieval verb like 'get' or 'return', but the subject matter is specific and distinct from the listed siblings.

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

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

The description provides a concrete usage pattern ('min_iv_rank=50 finds names in the upper half of their own vol range') and clarifies that ranks are relative to each name's own range, not absolute levels. However, it never contrasts this tool with closely related siblings such as get_iv_hv_premium or get_vol_of_vol, so an agent gets no explicit 'when to use this vs. that' guidance.

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

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

Annotations already indicate readOnly/idempotent/non-destructive behavior, and the description adds valuable context beyond that: point-in-time history, no look-ahead bias, rank semantics, and the 403 error interpretation. This meaningfully clarifies behavior an agent could not infer from annotations or schema alone.

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 well organized into three focused paragraphs: what the data is, how to use it, and important auth/error context. Every sentence carries information, with the resource definition front-loaded and no filler.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: columns, row semantics, point-in-time integrity, and rank meaning. It also covers query modes, key requirements, and error interpretation, making it complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic framing by explaining that a single `date` returns that day's basket and a range shows evolution, which helps the agent choose between the date family parameters. It does not add per-parameter detail beyond schema, but the usage framing is genuinely useful.

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 (Quant Galore Momentum Index constituents) and the data shape (one row per constituent per day: date, ticker, rank). It is specific enough to distinguish this tool from the many data-retrieval siblings, which cover different domains.

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

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

The description gives explicit use cases: mirror the index, source momentum candidates, or study turnover. It also explains how to query a single date versus a range. It does not name alternative tools or exclusion conditions, so it stops short of full when-to-use-versus-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 read-only, non-destructive, idempotent behavior. The description adds substantial context beyond that: the meaning of return and absolute_move fields, that the dataset acts as its own scorecard, the requirement of an Alphanume Pro API key, and that 403 errors indicate plan restrictions rather than missing data. This is genuinely useful operational transparency.

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

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

The description is well-structured: first the core data and meaning, then use cases, then authentication and error interpretation. Each sentence adds distinct value, and the most important facts are front-loaded. 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?

There is no output schema, so the description appropriately explains the key return fields (ticker, list date, return, absolute_move) and the scorecard nature of the data. It also covers authentication requirements and a critical error-class interpretation. This is sufficient for an agent to call the tool and interpret results 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 input schema has 100% parameter description coverage, so the schema already documents dates, range semantics, and max_rows behavior. The tool description adds high-level context about date-range backtesting but no additional parameter syntax or constraints beyond what the schema provides, 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 specific function: it returns US equities a volatility model ranks as likely to make an outsized move in the next session, with realized outcomes for backtesting. This clearly distinguishes it from sibling data tools like get_earnings_move_history or get_iv_rank, which target different signals or asset classes.

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

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

The description explicitly suggests two use cases: focusing trading attention on the daily list and backtesting the signal against realized moves over a date range. It does not explicitly name alternative tools or state when not to use it, but the use-case framing gives enough context for an agent to decide applicability.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: 50,000-row pagination cap, has_more/next_cursor mechanics, and crucially explains that 403 PRO_SUBSCRIPTION_REQUIRED or DATE_RANGE_RESTRICTED errors indicate plan coverage, not missing 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?

Every sentence earns its place: core concept, field definitions, filtering guidance, pagination mechanics, and error semantics. The most important point-in-time distinction is front-loaded, and the structure flows logically from what to how to error handling.

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

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

Despite lacking an output schema, the description names the key output fields (avg_days_between, has_weeklies), explains pagination response elements (has_more, next_cursor), and covers auth requirements and error interpretation. This is sufficiently complete for an agent to call and process results 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 input schema already documents all 7 parameters, so the baseline is 3. The description adds extra meaning by explaining that cursor_date and cursor_ticker must be sent together and come from next_cursor, and by clarifying that max_rows is applied after the API responds. This goes beyond the schema's descriptions.

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 returns: historical point-in-time snapshots of US equities with listed options, including specific fields like avg_days_between and has_weeklies. The emphasis on 'what was actually tradable then, not what is optionable today' clearly distinguishes its purpose from any current-universe tool among 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?

Gives clear guidance on when to use it, such as 'essential for honest options backtests,' and how to apply date filters and pagination. It doesn't explicitly name when-not-to-use alternatives, but the context is strong enough to guide selection.

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

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

Beyond the read-only/idempotent annotations, the description discloses publication timing (before the open, ~09:25 ET), walk-forward simulated history with a go-live date, later-filling outcome columns, NULL semantics, and known quirks in return fields. It also documents the 50,000-row pagination cap and cursor mechanics.

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

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

The description is long, but it is front-loaded with a one-sentence summary and organized into topic paragraphs (timing, authentication, simulation, outcome maturity, caveats, pagination). A small amount of repetition exists around pre-market publication and sub-$1 filtering, but the density is justified by the tool's complexity and lack of an output schema.

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

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

For a 14-parameter, no-output-schema tool, this is exceptionally complete: it names the key output fields (prob_drop, rank_for_date, intraday_return_pct, return_lead_*), explains their timing and NULL meaning, covers historical simulation, auth, filtering levers, and pagination. An agent has everything needed to call this tool correctly and interpret results.

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

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

While the schema already documents all 14 parameters (100% coverage), the description adds relational meaning: min_price=1 reproduces the legacy screen, sub_dollar=1 or max_price=1 isolates the penny cohort, and max_rank=5 returns the day's top five. It also explains cursor_date/cursor_rank pagination beyond the schema's 'must be sent together' note.

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

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

The description opens with a precise statement: 'model-estimated probability of an intraday decline in US microcaps,' then defines prob_drop as P(intraday open->close return <= -5%). It also distinguishes the dataset from generic movers by saying 'It measures the subset the model flags, not everything that moved overnight.'

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

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

It clearly says the data is 'built for researchers and traders analyzing pre-market activity in US microcaps' and spells out the Pro API key requirement. It also defines what the tool is not for ('Borrow and locate costs are NOT modeled'), though it never names sibling tools as alternatives.

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

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

The description goes far beyond the annotations, disclosing data provenance, daily ingestion from Polygon, the forward-calendar nature of upcoming rows, synthetic first_seen_at values for backfilled data, missing cap history before 2024-01-02, NULL semantics, exclusions at ingest, and pagination behavior. This level of behavioral detail is exceptional.

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

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

The description is long but well-structured with labeled sections and a front-loaded summary. The research-context paragraph is substantial, yet it earns its place by framing appropriate use and caveats. It is not terse, but it is dense with relevant information and organized clearly.

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

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

With no output schema, the description carries the full burden of explaining the data model, and it does so thoroughly: row granularity, key output fields, NULL behavior, auth requirements, pagination mechanics, and coverage caveats are all disclosed. An agent can confidently decide whether and how to call this 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains ratio as split_to/split_from with a 1-for-10 example, clarifies that upcoming=true is a genuine forward calendar, defines sub_dollar_flag semantics, and describes cap-tier history limitations. It enriches parameter understanding without exhaustively annotating every 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?

The description opens with a precise definition: 'Reverse-split calendar: every US reverse stock split, executed and UPCOMING...' and specifies the row granularity and data source. This clearly identifies the resource and scope, and the mention of dilution/shelf cross-links helps distinguish it from related sibling datasets.

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

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

The description gives explicit practical guidance: use it as a screening/avoidance signal, exclude fresh reverse-splitters from long screens, or anticipate events via the calendar. It also clearly warns against using it as a short card. However, it does not explicitly name or route to sibling tools like get_dilution_filings or get_shelf_registrations, even though those are related.

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

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

The description goes well beyond the readOnly/idempotent annotations: it discloses authentication requirements, the meaning of 403 errors, the post-2021 collapse in SEC output, that resumption is permission not evidence of quoting, that tickers are NULL in most pre-2022 rows, and that short date windows may legitimately be empty. This gives an agent accurate expectations for edge cases and failure modes.

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 yet every sentence adds value: scope, row semantics, bulk-order behavior, data quirks, authentication errors, and empty-result expectation. It is front-loaded with the core definition and then addresses operational caveats. No filler or redundant restatement of the tool name.

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

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

For an 18-parameter, no-output-schema tool, the description is remarkably complete. It tells the agent what each row represents, how to interpret resumption, how to handle bulk orders, when data may be missing, how API errors map to permission problems, and how recent data may lag. The schema covers parameter formats, and the description covers real-world behavior and 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?

Input schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: bulk orders share one release_number across many issuers, ticker NULL behavior, the normalized cited-reason taxonomy, and how issuer-level rows relate to order-level data. It still does not enumerate every parameter, but the schema already documents those thoroughly.

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 immediately identifies the resource: every SEC Section 12(k) trading suspension order from 1995 to today. It specifies the data scope, row granularity, and key fields (halts, resumption, reason taxonomy, order PDF URL), making it unmistakable what the tool retrieves. No sibling tool covers SEC suspensions, so the domain itself distinguishes it clearly.

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

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

The description gives clear context for when the tool is useful ('terminal-risk tape for dying OTC and small-cap names'), explains legitimate empty results, and tells the agent how to collapse bulk-order rows via issuer_count/issuer_index. It does not explicitly name an alternative or a when-not-to-use case, but no sibling tool competes with this dataset, so the omission is minor.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: row semantics, capacity_amount NULL meaning an indeterminate shelf, the 50,000-row pagination cap with next_cursor handling, and 403 error semantics. This goes well beyond what annotations alone convey.

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

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

Although long, the description is densely informative with no filler. It front-loads the core purpose and row semantics, then covers usage patterns, pagination, and error handling in a logical order. Every sentence adds operational value.

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

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

With no output schema present, the description fully compensates by enumerating all returned fields, explaining NULL capacity semantics, describing pagination behavior, and covering authentication/error cases. An agent has enough context to call the tool correctly and interpret its 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%, so the baseline is 3, but the description adds meaningful usage-level parameter semantics beyond the schema: using date_gte for recent shelf capacity, combining shelf_type=new with is_resale=0 for dilution risk, and passing next_cursor values back as cursor_date and cursor_accession. This materially helps an agent select and combine parameters correctly.

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

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

The description clearly identifies the tool as exposing S-3/F-3 shelf registration filings normalized into a point-in-time capacity ledger, with a specific row-level schema. It distinguishes itself from downstream dilution screeners by stating it is the upstream signal, so an agent can differentiate it from sibling tools like get_dilution_filings 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?

The description gives concrete usage patterns: screening date_gte for fresh shelf capacity, filtering shelf_type=new and is_resale=0 for primary dilution risk, or pulling a single ticker's history. It also explicitly warns that authorization is not issuance, preventing misuse, and provides pagination and error-handling instructions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that a Pro API key is required and interprets 403 PRO_SUBSCRIPTION_REQUIRED/DATE_RANGE_RESTRICTED errors as plan limitations rather than missing data. This materially helps the agent diagnose failures, and the 'deliberately minimal' note sets expectations about the dataset.

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 compact sentences front-load the core definition and use case, then add auth/error context. No sentence is wasted, and the structural cue 'Deliberately minimal' prevents over-expectation.

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

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

Despite lacking an output schema, the description states the exact output shape (one row per trading day with date and risk_regime label) and resolves the main operational ambiguity (403 meaning). Given the simple, read-only nature and fully documented parameters, nothing essential is missing.

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

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

The input schema already documents all six parameters with 100% coverage, so the description need not repeat them. It adds only high-level guidance that the latest date or a range can be queried, which is context but not parameter-specific semantic detail beyond the schema.

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

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

The description defines the tool as a daily binary risk-on/risk-off classification for the S&P 500, naming the exact resource and the row-level output (date and risk_regime label). The 'overlay/kill-switch input' framing clearly distinguishes its purpose from the sibling market-data tools, so an agent can select it 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 explicitly tells the agent when to call it: query the latest date for the current regime or a range to backtest a regime-filtered strategy. It also gives a when-not by saying it is not a dataset to mine on its own, though it does not name alternative sibling tools for exclusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds genuinely non-obvious behavioral context: the 403 error semantics ('PRO_SUBSCRIPTION_REQUIRED or DATE_RANGE_RESTRICTED error means the key's plan does not cover the request -- it does not mean the data is missing'), which prevents an agent from misinterpreting an auth failure as a data gap. It also discloses the row structure (one row per day, band plus instrument). This is more than the annotation layer alone provides.

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 compact sentences, each earning its place: the data definition, the use cases, and the error-handling caveat. The essential definition is front-loaded in the first sentence, and the operational note about API keys/403s is a valuable addition rather than filler. No redundancy with the schema or annotations.

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

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

With no output schema, the description correctly carries the burden of conveying return shape, and it does: lower_strike, upper_strike, the instrument, and one row per day. Combined with 100% schema parameter coverage, safety annotations, and the 403 diagnostic note, an agent has nearly everything needed to select and invoke the tool correctly. The only minor gap is that the date column is implied ('one row per day') rather than explicitly listed as part of the 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 description coverage is 100%, with all six parameters already documented in the schema (date formats, inclusive/exclusive semantics, max_rows cap). The description's mention of date-range backtesting aligns with the parameters but adds no syntax or meaning beyond what the schema provides. Per the rubric, baseline 3 is appropriate when the schema carries the documentation burden.

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 precisely what the tool returns: 'a model-derived intraday range (lower_strike, upper_strike) that same-day S&P 500 index options are expected to stay within, plus the instrument it applies to. One row per day.' This is a specific data product with a concrete resource, scope, and row semantics that clearly distinguishes it from sibling data tools like get_iv_rank or get_momentum_index without needing to open 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?

The description gives clear, concrete use cases: 'structure 0-DTE trades -- e.g. sell iron condors with short strikes at or beyond the band, or fade band breaches -- and to backtest how often the band held over a date range.' This tells an agent when the tool is relevant. It does not explicitly name alternative tools or state when-not-to-use conditions, so it falls just short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it is a current-state snapshot with no date dimension, one row per ticker, and no tier restriction. It also explains the taxonomy origin (SIC-derived but normalized for trading), which helps the agent reason about grouping semantics.

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 well-structured: a definition sentence, a sentence clarifying the taxonomy, a use-case sentence, and a constraints sentence. Everything included earns its place, and the key output shape is front-loaded rather than buried.

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

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

Given the tool has no output schema, the description compensates by naming the exact output columns and row granularity. It covers filtering options, taxonomy design, use cases, and scope limitations. An agent has enough context to invoke it correctly and interpret 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 100% and each parameter already has a clear description. The tool description adds general usage framing ('Look up one ticker, or filter by sector/industry') but does not add new semantic detail beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description opens with a specific verb-resource pair: 'maps every covered US ticker into Alphanume's own 11-sector / 25-industry scheme.' It clearly distinguishes itself from the sibling event/risk tools by being a classification/universe tool, and names the output schema (ticker, sector, industry) so an agent immediately knows what it returns.

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

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

The description gives explicit use cases: group datasets by sector, build sector-neutral baskets, enumerate a group by industry. It also states scoping constraints: no date dimension, no tier restriction, current-state mapping. It does not explicitly name an alternative tool or say when not to use it, but the sibling set contains no directly comparable classification tool, so this is adequate.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses intraday update behavior, settlement after close via is_final=1, authentication requirements (Pro API key), and interprets 403 errors as plan limitations rather than missing data. This is exactly the kind of behavioral context that structured annotations cannot convey.

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

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

The description is dense but well-structured: definition and data shape first, then interpretive guidance, then auth/error caveats. Every sentence adds value, and the most important 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 14-parameter, fully optional tool with no output schema, the description is remarkably complete. It explains the underlying computed fields, the ranking dimension, the intraday vs final distinction, and the error semantics. An agent can safely invoke and interpret this 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?

The input schema documents every parameter, so the baseline is 3. The description adds meaningful context by defining what iv_vov and hv_vov actually measure, tying those definitions to the filter parameters and to the cross-sectional rank fields. This helps the agent understand threshold meaning beyond the raw schema.

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

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

The description names a precise resource (vol-of-vol for US optionable equities), defines the core metric (coefficient of variation of implied and realized vol over a trailing month), and clearly separates it from related concepts like iv_rank or iv_hv_premium. It is not tautological and gives the agent a concrete sense of the data shape and ranking.

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

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

The description provides clear analytical guidance: high vol-of-vol names indicate treacherous vega risk and potential vol dislocations, while low vol-of-vol names have sticky surfaces. It does not explicitly name alternative tools or state when NOT to use this tool, but the use case is strongly 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 readOnly/idempotent annotations, the description discloses pagination details (50,000-row cap, has_more, next_cursor and cursor parameters), requires an Alphanume Pro API key, and explains that 403 errors indicate plan coverage rather than missing data. It also describes the one-row-per-ticker-per-day shape since no output schema exists.

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

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

The description is front-loaded with purpose and output shape, and every later section earns its place: use-case guidance, pagination mechanics, and error interpretation. Despite covering 14 parameters, it stays compact and 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?

For a 14-parameter tool with no output schema, the description plus 100% schema coverage covers output fields, date/ticker filters, pagination, auth requirements, and error semantics. Nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds operational meaning by framing zscore_30d_gte=3 as an attention-spike screen and by explaining how cursor_date and cursor_ticker should be passed from next_cursor, which goes beyond the schema's standalone parameter descriptions.

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

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

The description opens with a specific resource ('daily page views of each covered company's Wikipedia article') and a clear analytical output (30-day average and z-score). The phrase 'one row per ticker per day' and the listed fields make the return shape concrete, and this Wikipedia-specific tool is clearly distinguishable from all financial-data 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 gives explicit usage patterns: screen zscore_30d_gte=3 for fresh attention spikes or pull one ticker's history to compare with price. It doesn't name alternative tools or state when-not-to-use, but no sibling appears to compete in this domain, so the context is sufficient.

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

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

The annotations already establish read-only, idempotent, and non-destructive behavior. The description adds useful context beyond those annotations by revealing that the output is a coverage map with first-available dates and that the only parameter is the row cap. No contradiction with annotations is present.

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

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

The description is two sentences with zero filler. The core concept is front-loaded, followed by actionable usage guidance and a brief parameter note. Every sentence earns its place.

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

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

For a simple zero-required-parameter listing tool, the description covers purpose, return content, use cases, and the single optional parameter. The explicit statement of what the tool returns compensates for the absence of an output schema, and the annotations cover safety semantics.

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

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

The input schema already documents max_rows thoroughly, including the default, cap semantics, and guidance to prefer filters over raising the cap, so the schema carries the parameter meaning. The description only confirms that there are no other parameters, which is helpful but does not add substantial 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 clearly defines the tool as a coverage map listing every available ticker with its first available date, which is a specific resource and deliverable. It distinguishes itself from sibling data tools by framing its role relative to get_historical_market_cap, so an agent can tell it apart 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 explicitly says when to use the tool: check whether a name is covered before querying get_historical_market_cap, or enumerate the full point-in-time universe. It names the alternative tool directly and provides a clear decision rule, leaving nothing to inference.

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