mcp-server

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

No annotations are provided, so the description carries full burden. It does not disclose whether the tool overwrites existing signals, requires permissions, or has side effects. The only behavioral context is that the expression uses the same grammar as scan q.

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

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

The description is a single front-loaded sentence with no redundant information. Every word serves a purpose, making it concise and easy to parse.

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

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

The description covers the core purpose adequately but lacks details about return values, error cases, or lifecycle implications (e.g., whether duplicate names are allowed). For a creation tool with no output schema, slightly more context would improve completeness.

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%, but the description adds value beyond schema: 'Snake_case identifier.' for name, 'Optional human description.' for description, and 'Same grammar as scan `q`.' for expr, which clarifies the syntax. This extra context improves usability.

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

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

The description clearly states the verb 'save' and the resource 'SQL WHERE expression as a named custom signal', and it distinguishes the tool from siblings by specifying the result is referenceable in future scans.

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 does not provide guidance on when to use this tool versus alternatives like tickerbot_update_custom_signal or tickerbot_delete_custom_signal. It only mentions future scans but lacks explicit when-to-use or when-not-to-use criteria.

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

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

No annotations are provided, so the description must convey behavioral traits. It indicates a write operation ('create') but lacks details on success/failure, idempotency, or side effects. Adequate but not thorough.

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?

Single sentence with no wasted words; directly states the tool's purpose and context. Well-structured and 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?

Given the absence of an output schema, the description could have mentioned the return value (e.g., created universe ID). It covers the core purpose but leaves out expected response, making it partially incomplete.

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 already documents each parameter thoroughly. The description adds no additional parameter-level meaning, so a baseline score 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 clearly states the action ('Create'), the resource ('universe'), and its purpose ('named set of tickers for scoping future scans'), making it distinct from sibling tools like update_universe or delete_universe.

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

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

No guidance on when to use this tool versus alternatives, nor any prerequisites or constraints like uniqueness of the id or name. The description is too minimal for effective decision-making.

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

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

No annotations are provided, so the description carries full burden. It discloses the HTTP endpoint, the four trigger shapes, and the relationship to sugar tools, adding meaningful behavioral context. However, it does not mention response format, error handling, or authentication, so it is not fully transparent.

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 compact yet highly informative. Each sentence contributes: stating the canonical purpose, explaining usage versus sugar tools, and enumerating trigger shapes. It is front-loaded and well-structured.

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

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

For an 8-parameter tool with nested objects and no output schema, the description covers the core complexity (trigger shapes) and provides clear usage context. It does not explain the response format, but the schema handles parameter meanings and the description addresses the main decision of when to use it.

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%, providing descriptions for all 8 parameters, so baseline is 3. The description adds value by detailing the 'trigger' object shapes (scan, ticker, signal, event) with their fields, which the schema only refers to as 'see the tool description for each shape.'

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 the tool is 'The canonical webhook create — POST /v2/webhooks with an explicit trigger object', clearly indicating it creates a webhook. It also distinguishes itself from sibling subscribe tools by calling them 'flat sugar' and positioning this as the canonical form.

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

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

Explicitly provides usage guidance: 'The subscribe tools above are flat sugar over exactly this; use this form when composing the trigger programmatically or when a sugar door doesn't fit.' This clearly states when to use this tool versus alternatives.

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

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

With no annotations, the description fully covers behavioral traits: cascade-safe default, error response with referencing signals, force option effect, and subsequent reference breakage on recompile. No contradictions.

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 sentences, immediately stating the primary action, then detailing edge cases and plan availability. No unnecessary words.

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

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

The description covers core behavior, error handling, and force option. It does not describe the success response, but as a delete operation this is sufficient given no 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 100% so baseline is 3. The description adds context beyond the schema: explains the cascade behavior for `force` and the error listing, making the tool's behavior clearer.

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

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

The description clearly states the action ('Delete one of the caller's custom signals') and differentiates from sibling tools (e.g., create, update) by specifying ownership ('caller's') and the specific resource.

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 explains when the tool will refuse (409 if referenced) and how to force deletion. It does not explicitly name alternatives but implies that deletion should be avoided if references exist unless forced.

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

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It reveals that the tool deletes only the caller's own universes, that system universes are protected, and that webhooks referencing the deleted universe will fail—a critical side effect. No contradictions 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 concise with three sentences, each serving a distinct purpose: state the action, note an exception, and warn about side effects with a precaution. No unnecessary words or repetition; 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?

Given the tool's simplicity (one parameter, no output schema), the description covers all essential aspects: what it does, constraints (non-system universes only), and a key behavioral consequence (webhook failures). The lack of return value details is acceptable for a delete operation. The description is complete for the agent to use 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?

The only parameter is 'id' (universe slug), and the input schema already describes it as 'Universe slug' with 100% coverage. The tool description does not add additional meaning about the parameter format or constraints beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool deletes one of the caller's universes, specifying that system universes cannot be deleted. It distinguishes the action from sibling tools like tickerbot_create_universe and tickerbot_update_universe by explicitly noting which universes are eligible.

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

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

The description provides explicit when-not-to-use guidance by stating system universes cannot be deleted. It also includes a preparatory step: cleaning up webhooks that reference the deleted universe to avoid failures. This helps the agent decide when to invoke the tool and what to do beforehand.

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

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

No annotations are provided, so the description carries full burden. It discloses the destructive nature (delete) but lacks details on reversibility, permissions, or side effects. Adequate for a simple delete operation.

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

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

Two sentences: first states purpose, second provides usage context. No wasted words; front-loaded and efficient.

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

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

For a one-parameter delete tool with no output schema, the description is sufficient. It specifies what and when, meeting expectations without needing to detail return values.

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% with parameter 'id' described as 'Webhook id (looks like `wh_…`)'. The description adds 'by id' but no new meaning beyond the schema, so baseline 3.

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

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

Description clearly states 'Delete a webhook subscription by id' with a specific verb and resource, distinguishing it from sibling delete tools like delete_custom_signal or delete_universe.

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 says 'Use after listing webhooks when the user wants to remove an alert,' providing clear context and scenario for use, though no explicit when-not-to-use.

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

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

With no annotations provided, the description fully discloses behavioral traits: it flips status to active, clears match-state, and resets evaluation behavior. This is comprehensive for a mutation tool.

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

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

Three sentences with no redundancy: main action first, then details (match-state clearing), then usage note (no-op). Optimally front-loaded and efficient.

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

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

For a single-parameter tool with no output schema, the description covers all necessary context: purpose, side-effects, and when to use. Complete for an enable operation.

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% with 'id' described as 'Webhook id.' The description adds no extra meaning beyond that; baseline 3 is appropriate.

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

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

The description clearly states the tool re-enables a disabled webhook, using specific verb 're-enable' and resource 'webhook'. It distinguishes from sibling tools (delete, test, list, get) by focusing on the enable action.

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

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

The description advises 'Use after fixing whatever caused auto-disable' and notes it's a no-op on active webhooks, providing clear usage context. However, it lacks explicit comparison to alternative webhook 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?

With no annotations, the description carries the full burden. It discloses key behaviors: cursor-paged backward pagination, flat row structure, transitions_only behavior with transition_drivers, and 'all-time on every plan'. It lacks details on rate limits or error handling, but the provided behavioral context is substantial and goes well beyond minimal.

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 compact and information-dense, with each sentence contributing a distinct aspect: purpose, row format/pagination, transitions, and alternatives. It is slightly longer than necessary due to marketing-style phrasing ('THE series primitive'), but overall it remains focused and readable.

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

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

Given no output schema, the description effectively explains return values and pagination. It covers the core use cases and key constraints, but omits edge-case behaviors like timezone handling or error responses. For a tool of this complexity, it is reasonably complete, though not exhaustive.

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% with detailed parameter descriptions, so baseline is 3. The description adds context about limits (25 columns, 50 tickers) and row shape, but these are not new semantic details for individual parameters beyond what the schema already provides. It enriches usage context but doesn't materially add to schema 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 clearly identifies this as the cross-ticker, multi-column time series primitive, distinguishing it from per-ticker history endpoints by explicitly stating it replaces them. The verb 'get' and resource 'series' are specific, and the description names concrete use cases like transitions_only.

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 this tool: for multi-ticker, multi-column aligned series, and directly says it replaces looping asof snapshots and sunset per-ticker history routes. This provides clear alternative guidance, satisfying the 'explicit when/when-not' criterion.

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

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

With no annotations, the description must carry the behavioral disclosure burden. It does disclose sorting behavior ('Sorted by signal value desc for numerics') and condition semantics, but it does not mention response format, pagination behavior, or other potential side effects. This is adequate but not comprehensive.

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

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

The description is two concise sentences, front-loaded with the main purpose, and includes only essential clarifications. There is no wasted wording.

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

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

Given no output schema and no annotations, the description covers the core behavior, parameter requirements, and sorting. It could be more complete by mentioning the response structure or explicitly contrasting with similar tools like tickerbot_scan, but it handles the essential context 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%, so the baseline is 3. The description adds meaningful value beyond the schema by clarifying that booleans need no condition, showing condition syntax examples ('>70', '<=200'), and explaining sorting. This enhances understanding of signal and condition parameters.

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

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

The description clearly states the tool's purpose: 'Find tickers that match a single signal right now (or at a past moment with asof)'. It uses a specific verb and resource, and distinguishes itself from sibling tools by emphasizing single-signal matching and the asof capability.

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 for when to use the tool (matching a signal) and explains the distinction between boolean and numeric conditions. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls 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?

With no annotations provided, the description explains the `asof` behavior (date-only vs timestamp) and what data is returned. It does not disclose potential error responses, rate limits, or idempotency, which would improve transparency.

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

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

Two succinct sentences: first defines purpose and output, second covers the optional parameter. No filler, front-loaded with essential information.

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

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

The description covers the main use cases (current and historical data), lists example columns, and explains ticker formats. Lacks mention of any edge cases (e.g., invalid ticker, data not available), but is otherwise complete given no 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 100%, but the description adds significant value: explains ticker format details (equities vs crypto) and clarifies `asof` behavior beyond the schema. This helps the agent use 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 states it retrieves the full current row for one ticker, listing example columns. It distinguishes from sibling tools like tickerbot_get_ticker_bars (historical bars) and tickerbot_get_ticker_history (history series) by focusing on the full current snapshot.

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

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

Provides clear context on when to use the `asof` parameter for historical data and explains ticker format (equities vs crypto). However, lacks explicit guidance on when not to use this tool or direct comparison to other ticker-related 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?

With no annotations, the description carries the full burden. It discloses meaningful behaviors: 'oldest-first' ordering, 'bulk response keyed by symbol', 'back-fill on demand', and coverage differences. It does not describe potential errors or rate limits, but for a read-only getter it is reasonably transparent.

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 sentences, front-loaded with the core purpose. Each sentence adds distinct value: main action, bulk/back-paging parameters, and interval behavior. No wasted words.

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

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

For a complex tool with 8 parameters and no output schema, the description covers the primary use cases (single, bulk, point-in-time, back-paging) and interval nuances. It does not explain cursor-based paging explicitly, but that is documented in the schema. Overall, it is sufficient for an agent to choose and initially invoke the 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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds extra semantics by explaining the comma-separated ticker list behavior, the point-in-time use of asof, the back-paging use of before+limit, and the special coverage of 1d/1h intervals. This goes beyond mere schema repetition.

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 ('Get') and resource ('OHLCV bars') plus scope ('one or more symbols at a given interval, oldest-first'). This clearly distinguishes it from siblings like get_ticker_history or get_series by emphasizing bar data with explicit ordering.

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 clear usage context for parameter combinations ('Use asof for a single point-in-time bar, or before+limit to back-page') and interval coverage ('1d/1h cover the full universe with full history; sub-hour intervals back-fill on demand'). It does not explicitly name alternative tools, so it stops short of full when-not-to-use 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?

With no annotations provided, the description carries the full transparency burden. It goes beyond a simple 'returns coverage info' by characterizing the tool as the 'honesty endpoint' and detailing what behavioral distinctions it makes (coverage gap vs. never-covered). It does not disclose output format or side effects, but the description is substantially informative for a read-only reporting tool.

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

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

The description is two sentences, front-loaded with the core purpose and immediately followed by practical usage context. Every phrase earns its place—no fluff, no repetition of the tool name, and the 'honesty endpoint' metaphor is compact and memorable.

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

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

Given the tool's simplicity (one parameter, no annotations, no output schema), the description is thorough: it defines the report's contents, its purpose, and when to call it. The only missing piece is a concrete outline of the return shape, but that is not essential for invoking 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 description coverage is 100%: the only parameter 'ticker' is documented as 'Symbol.' The description adds minimal semantic value beyond that, though 'one ticker' reinforces the singular input. Since the schema already handles the parameter documentation, a 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 opens with a specific verb+resource combo: 'Data-coverage report for one ticker' and immediately lists what it covers ('which intervals and columns exist, from when, at what depth'). It also distinguishes itself from sibling data-retrieval tools by framing it as the 'honesty endpoint' to check before interpreting gaps as outages.

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 guidance on when to use this tool: 'ask this before assuming a gap in bars/series is a data outage vs. genuinely-never-covered'. It provides illustrative edge cases ('sub-hour bars outside the active universe, fundamentals on non-equities') but does not explicitly name alternative tools or exclusion criteria, 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool returns a historical snapshot, includes indicators, boolean flags, and most-recent fundamentals, and offers 'Unlimited depth on every plan'. It does not cover error cases or exact response format, but the key behaviors are clear.

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

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

The description is two sentences, front-loaded with the core concept ('Time-travel SNAPSHOT') and then provides a distinction from the sibling tool and the return contents. Every sentence adds value, and there is no fluff or redundancy.

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

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

For a simple two-parameter tool with no output schema, the description is mostly complete. It explains what the tool returns, how it differs from the series variant, and the unlimited-depth guarantee. It does not discuss exact field names or edge-case behavior, but that is not necessary given the tool's simplicity and the schema's completeness.

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 provides 100% coverage for both parameters ('ticker' and 'asof'). The description adds meaning by clarifying that the snapshot is for 'one ticker' and is 'as of a past date', reinforcing how the parameters are used together. It goes beyond the schema's basic descriptions without repeating them verbatim.

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

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

The description clearly states the tool's purpose: 'Time-travel SNAPSHOT: the full wide row for one ticker as it stood at a past date'. It uses a specific verb (get) in the name and describes the resource (ticker history) and scope (one row, one ticker, past date). It also explicitly distinguishes itself from tickerbot_get_series, making the purpose unambiguous.

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

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

The description provides explicit usage guidance by saying 'for a multi-column time SERIES use tickerbot_get_series'. This clearly tells the agent when to choose this tool over an alternative. The phrase 'one row, not a series' further reinforces the scenario this tool is designed for.

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

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

No annotations are provided, so the description takes full responsibility for behavioral disclosure. It clearly explains the behavior when the ticker is not an ETF (is_etf=false, holdings empty) and when it's a real ETF but holdings aren't ingested (is_etf=true, zero holdings). It also states the ordering ('heaviest first'), which is useful behavioral detail.

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 plus a parenthetical, with no redundant words. It front-loads the primary purpose and adds necessary edge case details efficiently.

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

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

Given the tool's simplicity (2 params, no annotations, no output schema), the description covers key edge cases and distinguishes the tool from related functionality. It does not explicitly describe the internal structure of holdings, but it is clear enough for an agent to understand the tool's purpose and behavior.

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 both parameters fully described in the input schema. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 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 states a clear verb+resource: 'Get an ETF's constituent holdings and their weights, heaviest first.' It distinguishes from sibling tools by focusing specifically on ETF holdings, and clarifies the is_etf edge cases.

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 warns against using this tool for reverse lookups ('which ETFs hold NVDA') and directs to a scan filter on the etf_holders column, providing an alternative. It also details when to expect empty holdings, giving clear usage context.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: non-ETFs return `is_etf: false` with empty `sectors`, and `is_etf: true` with zero sectors indicates missing ingested data. This adds valuable edge-case context beyond mere retrieval.

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: first states the core action, second explains edge cases. It is front-loaded with the essential purpose and contains no redundant or filler content. 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?

Given there is no output schema, this simple one-parameter tool describes return behavior sufficiently for an agent to interpret results correctly. It mentions the `is_etf` and `sectors` fields and covers edge cases. It could be more explicit about the overall response structure, but it is complete for the tool's simplicity.

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 provides 100% coverage for the single parameter `ticker` with description 'ETF symbol.' The tool description adds no additional parameter semantics beyond what the schema states, so the baseline score 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 clearly states 'Get an ETF's sector allocation' with specific verb and resource, and further clarifies 'sector weights, heaviest first.' This distinguishes it from sibling tools like get_ticker_holdings or get_ticker_bars. The purpose is unambiguous and specific.

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 implies that this tool is for ETF sector allocation and explains what to expect for non-ETFs, but it does not explicitly state when to use this tool versus alternatives like get_ticker_holdings. The guidance is more about interpreting results than choosing between tools, so it falls short of explicit usage 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?

No annotations are provided. The description states it includes the ticker list but does not elaborate on read-only behavior, error handling, or rate limits. The term 'get' implies a read operation, but transparency is minimal.

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

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

One sentence with no fluff, front-loading the action, resource, and key detail (ticker list). Every word adds 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?

Given the simple tool with one required param and no output schema, the description covers the essentials: what it returns and how to identify the universe. Minor omission about non-existent slugs is acceptable.

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% with the 'id' parameter described as 'Universe slug.' The description adds no further semantics beyond 'by slug,' so it meets the baseline 3.

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

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

The description clearly states 'Get one universe by slug, including its ticker list.' The verb 'Get' and resource 'universe' are specific, and mentioning 'ticker list' distinguishes it from listing or creation 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 implies usage for fetching a single universe by slug, but does not explicitly contrast with siblings like tickerbot_list_universes or provide when-not-to-use 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?

No annotations provided, so description carries burden. Discloses that it's account-scoped and returns state/match-set/schedule, but lacks details on error handling, id format confirmation, or side effects. Adequate but not thorough.

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, both directly relevant. No fluff. Front-loaded with the core action.

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?

Simple tool with one parameter. Description explains the returned data structure. Could benefit from noting error cases or id format example, but sufficient given the simplicity.

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% with the id parameter described. Tool description adds no additional meaning beyond the schema's description of id. 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?

Clearly states the verb 'fetch', the resource 'webhook subscription by id', and specifies the returned data (current state, match-set, schedule). Account-scoping distinguishes it from list_webhooks and delete_webhook.

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?

Implies usage by stating account-scoped and read-only, but does not explicitly mention when to use this vs list_webhooks (e.g., for a single specific webhook) or any 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It effectively discloses row format, ordering (newest first), case-sensitivity nuances, aggregate behavior (truncated: true instead of paginating), and the join=state replay behavior. It also notes the historical depth for analyst payloads. This is substantial transparency for a complex query tool.

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

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

The description is long but dense with essential information, front-loading the core purpose with 'THE events primitive'. Each sentence contributes: row format, filters, aggregation, join behavior, and requirements. It is structured logically but could benefit from paragraph breaks for readability; still, it avoids redundancy and earns its length for a 20-parameter 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?

Given the tool's complexity (20 params, no output schema, no annotations), the description covers the most critical aspects: event kinds, row structure, filtering strategies, aggregate mode behavior, join semantics, and mandatory bounds. It does not explicitly cover pagination defaults or all parameter interactions (e.g., transition, interval), but those are documented in the input schema, making the overall package complete enough for an agent.

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 baseline is 3. The description adds significant value beyond the schema: it explains q's SQL grammar over (ticker, ts, kind, payload jsonb), the case-sensitivity difference between firm and q payload matches, the required-bound rule, and how group_by/select/having change the output shape. This meaningfully helps the agent use 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 states the tool's function: listing events across all event logs, with explicit examples ('all splits this month', 'AAPL's full corporate history'). It distinguishes itself from siblings like tickerbot_list_signal_events and tickerbot_get_ticker_history by framing itself as 'THE events primitive' and covering multiple event kinds.

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 strong usage context: it states the tool is for cross-ticker event queries, explains opt-in kinds (signal, news), and gives explicit constraints ('Requires at least one bound... q alone is not a bound'). It also differentiates between firm/action filters and q payload matches. However, it does not explicitly mention when to use alternative tools like list_signal_events or get_ticker_history.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses ordering (newest-first), state vs. event flag semantics (true-windows vs. point firings), null handling ('ended_at is null while still true'), and outputs ('prices at both ends'). It also notes the limitation that only built-in booleans have precomputed spans.

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 concise—three sentences that front-load the core purpose. The second sentence explains the important state/event distinction, and the third sentence gives a concrete usage example and a key limitation. Every sentence earns its place without fluff.

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 adequately explains what rows look like for both flag types. It covers the core semantics, example usage, and limitations. It does not detail pagination behavior, but the schema already documents cursor and limit. Overall it is sufficiently complete for a list 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. The description adds a helpful example for from/to (June dates) and clarifies the signal parameter must be a built-in boolean, but it does not substantially enhance understanding of most parameters beyond what the schema already states.

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

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

The description explicitly states the tool lists 'Occurrence SPANS of a boolean signal for one ticker, newest-first.' It gives a specific verb ('list'), a clear resource ('spans of a boolean signal'), and scope ('one ticker'). It also distinguishes itself from siblings by contrasting with tickerbot_get_series for numerics and custom signals.

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 when-to-use guidance: 'Built-in booleans only — numerics and custom signals have no precomputed spans (use tickerbot_get_series).' This defines an exclusion and names the alternative tool. It also gives a concrete example, 'Golden crosses in June' with from/to parameters, demonstrating the intended query pattern.

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

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

With no annotations provided, the description carries the full burden. It explains the contents of the catalog and the kind filter, but it does not mention pagination behavior, default return of both kinds, or any read-only implications. The description adds value but lacks some behavioral details that would be helpful.

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

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

The description is two sentences, front-loaded with the core purpose, and then provides useful metadata details. Every sentence earns its place; there is no fluff or redundancy.

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

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

For a simple listing tool with 3 optional parameters and no output schema, the description covers the purpose, contents, and usage context. It could mention that omitting 'kind' returns both types, but this is implied by 'every built-in' plus 'custom signals'. The high schema coverage and simple resource make it reasonably complete.

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

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

Schema description coverage is 100%, and the description adds context about the meaning of builtin vs. expression, which aligns with the 'kind' enum. However, it does not elaborate on limit or cursor, though those are fully documented in the schema. The description meets the baseline without adding significant new parameter information.

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

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

The description clearly states the tool lists the unified signal catalog, distinguishing built-in and custom signals. The verb 'List' with the specific resource 'signal catalog' makes the purpose unambiguous, and it differs from sibling tools like list_tickers or list_universes.

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 states the intended usage: 'Use to discover what q= clauses and signal names are available before composing a scan.' This gives clear context but does not mention exclusions or alternative tools by name, though the context is sufficient for a discovery tool.

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

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

No annotations exist, so description carries full burden. It discloses the nature (built-in, rebalanced monthly, free) and implies read-only behavior. No contradictions.

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 wasted words, front-loaded with purpose and examples.

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?

Complete for a zero-parameter, no-output-schema tool: covers purpose, examples, usage, and constraints.

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?

No parameters, so baseline is 4. Description adds value by explaining what system universes are and how to use the returned slugs.

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?

Explicitly states it lists built-in system universes, provides examples (top_10, top_100), and distinguishes from sibling tools like tickerbot_list_universes by specifying 'system'.

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?

Tells how to use the slugs in scans/signals/subscriptions and notes availability to all accounts, but doesn't explicitly contrast with alternatives for listing custom universes.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the pagination order (alphabetical), the effect of `tickers` (ignores pagination params), and that search/min_market_cap order results by market_cap desc. It does not mention rate limits or response shape, but it covers the most consequential behaviors.

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, each densely packed with distinct information. It front-loads the core purpose, then adds the universe composition, pagination mode, and filter list without repetition or fluff. Every sentence earns its place; it is appropriately sized for a tool with 10 parameters.

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 (10 params, no output schema, no annotations), the description provides a solid overview of universe scope, special parameters, and filtering behavior. It does not describe the return payload shape, but for a list operation with a cursor, the response format is typically inferable. The description is complete enough for an agent to select and invoke the tool correctly for most use cases.

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 meaningful context beyond schema: what 'active' means, the universe composition (US equities plus R: and X: symbols), and the alphabetically-with-cursor pagination behavior. It also reinforces the `tickers` parameter's bulk-row behavior, which is only partially implied in 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 opens with a specific verb+resource: 'List active tickers from the Tickerbot universe', immediately clarifying the tool's function. It distinguishes itself from siblings by describing the universe scope and the unique `tickers` bulk-lookup mode, setting it apart from single-ticker tools like `tickerbot_get_ticker` and scan 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?

It provides clear usage context: when to use the `tickers` parameter for bulk lookup versus walking the universe with `cursor` pagination. It also lists supported filters, which helps the agent decide when to call this tool. However, it does not explicitly contrast with alternatives like `tickerbot_scan` or `tickerbot_search_news`, leaving some ambiguity for edge 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?

With no annotations, the description adds valuable context: it mentions that each row carries 'system: true|false' and explains pagination behavior for system universes. However, it does not disclose read-only nature or authentication requirements.

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 highly concise, using only two sentences to convey purpose, filtering options, and response structure. No superfluous 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?

The description covers main behavior and filter logic, but does not explain the 'cursor' parameter or how pagination works beyond the limit note. For a 3-param tool with no output schema, some gaps 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?

Despite 100% schema coverage, the description adds meaning beyond the schema by explaining the 'owner' default and the 'limit' behavior for system universes. This enhances understanding.

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

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

The description clearly states the action (List) and resource (universes), and distinguishes between saved ones and built-in system universes, providing specific examples (top_10, top_100).

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

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

No guidance on when to use this tool versus siblings like tickerbot_list_system_universes or tickerbot_get_universe. The description does not mention alternatives or 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?

With no annotations, the description discloses the most important behavioral trait: it returns metadata only and explicitly notes the POST body is not stored. It also states the ordering (newest-first), which is a behavioral detail an agent needs to know.

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

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

The description is two sentences, with the primary action and filter context in the first sentence and a critical caveat in the second. No superfluous words.

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

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

The description covers the tool's purpose, return type limitation, and data retention nuance, compensating for the lack of an output schema. The schema handles parameter details, so the overall package is sufficient 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?

All six parameters are fully documented in the input schema, including formats and enums, so the description need not repeat them. The description adds no parameter-specific syntax 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 specifies a clear action ('List recent deliveries') and identifies the resource type ('for a webhook'), with a distinct scope ('pings and fires') and purpose ('for diagnosing failures'). This differentiates it from sibling tools like list_webhooks and list_events.

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

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

The phrase 'for diagnosing failures' provides clear context for when to use this tool, but it does not explicitly name alternative tools or exclusion criteria. The sibling list_webhooks is a different operation, so a more explicit when-not would be beneficial.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: ordering ('newest-first'), scope ('caller's'), and provenance ('created via the subscribe tools'). While pagination and return format are not detailed, the essential behavior for a list operation is covered. No contradictions with annotations since none exist.

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

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

The description is two sentences, with the primary action and scope in the first sentence and a practical usage hint in the second. Every word contributes value, with no filler or repetition of schema content. This is exemplary conciseness.

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

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

Given the tool's simplicity (list operation, three optional parameters, no output schema), the description covers the key aspects: what is listed, whose, order, and a filtering option. It does not describe the return structure, but with no output schema and straightforward semantics, the provided information is largely sufficient. A 5 would require explicit guidance on expected response shape or pagination behavior.

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 covers all parameter descriptions at 100% coverage, which sets the baseline at 3. The description adds meaningful context by explaining that the listed items are 'rules created via the subscribe tools' and explicitly suggests using `status` for filtering. This enriches understanding of the parameters beyond the schema's bare definitions, justifying a 4.

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 ('List') with a clear resource ('webhook subscriptions') and scopes it to 'the caller's'. It also clarifies that these are 'rules created via the subscribe tools', distinguishing it from sibling tools like list_webhook_deliveries and get_webhook. The purpose is immediately understandable.

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 by stating it lists the caller's subscriptions and includes a usage hint for the `status` filter. It does not explicitly name alternatives or exclusions, but the sibling tool names (e.g., list_webhook_deliveries) make the differentiation obvious enough. This is one notch below explicit 'when to use vs 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?

With no annotations, the description carries full burden and excels: discloses immutability of trigger/channel, partial-update semantics (editing in place), state preservation on pause, and strict error handling (unknown fields return 400, never silently ignored). These are significant behavioral traits beyond what parameters imply.

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 each earn their place: purpose and editable fields, immutable-fields guidance, and error behavior. No redundant phrasing; front-loaded with the core function.

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 5-parameter patch tool with no output schema, the description covers all essential context: editable fields, immutability constraints, state behavior, and error handling. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% with each parameter already described. The description adds extra meaning for 'enabled' (pausing/resuming without losing match-state) and clarifies the immutable fields, so it adds value beyond the schema without duplicating it.

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

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

The description clearly states 'Edit a webhook in place' with the specific mutable fields listed, distinguishing it from create/delete/enable siblings. It also specifies which aspects are immutable (trigger and channel), making the tool's scope unambiguous.

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

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

Provides explicit guidance on when to use alternatives: for changing trigger/channel it says 'delete and re-create', and for re-enabling after auto-disable it points to tickerbot_enable_webhook. This gives clear when-to-use vs when-not-to-use context.

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

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

With no annotations, the description carries full burden. It discloses both row and aggregate modes, the flat WHERE grammar constraints, asof behavior, and example usage. It doesn't cover pagination or authentication, but for a read-only query tool it provides strong transparency about behavior and limitations.

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?

Four sentences, front-loaded with purpose, then mode, grammar, and example. Every sentence adds value and the content is well-structured.

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

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

Given 12 parameters and no output schema, the description does an excellent job explaining the two operating modes, the query language, and the asof feature. It provides enough context to understand what the tool returns and how to use it, though it defers some details to parameter descriptions.

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 covers 100% of parameters, so baseline is 3; however, the description adds substantial semantics by explaining q grammar (AND/OR/NOT, comparisons), group_by aggregation, asof depth, and example queries. This goes well beyond the schema's per-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 clearly states the tool runs a SQL WHERE clause against the ticker universe, returns matching tickers or aggregate rollups with group_by, and provides an example. This distinguishes it from sibling tools like list_tickers or get_ticker, which serve different retrieval purposes.

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 specifies the tool is for filtering/querying the universe via SQL syntax, and it explicitly notes limitations ('No JOIN or subqueries'). It doesn't name alternative tools, but the context implies it is the go-to for flexible scans. It gives examples of use cases, including historical scans with asof.

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

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

With no annotations, the description carries the full burden. It disclose the data scope (news_article columns), syntax (`tk='NVDA'`), time range, and aggregation support, which goes well beyond schema descriptions. It does not explicitly state read-only or return format, but 'search' implies read-only and the column listing provides expectations. The transparency is solid but not exhaustive.

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

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

The description is dense but every sentence earns its place: archiving depth, plan availability, column list, ticker filtering syntax, example, and aggregation note. It is front-loaded with purpose and uses a practical example. No fluff or redundancy.

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

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

Given the tool's complexity (9 params, SQL interface, aggregation), the description covers the key aspects: query syntax, available columns, example, and aggregation. It doesn't explain default output shape, but schema covers defaults and cursor/pagination. The description is sufficiently complete for an agent to use it correctly, with minor gaps around response format.

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 baseline is 3. The description goes beyond schema by explaining the SQL WHERE pattern, the auto-unnest alias `tk`, and how group_by/having work together. This adds meaningful semantic value for the main parameters, especially `q` and `group_by`, without duplicating schema info.

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

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

The description clearly states the tool searches a news archive with a SQL WHERE clause, a specific verb+resource. It distinguishes itself from sibling tools (e.g., tickerbot_get_ticker_bars, list_events) by focusing on news articles and even provides column details and an example query. The purpose is unmistakable.

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: searching news, archive back to 2015, and available on every plan. It gives a concrete example and mentions aggregation capabilities. It does not explicitly name alternative tools or exclusion criteria, but the context is strong enough for an agent to know when to use it. Missing explicit 'when not to use' guidance, but clear context earns a 4.

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

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

With no annotations, the description carries the full burden and does well by disclosing the event trigger behavior, filter semantics, delivery payload structure, latency, and paid plan requirement. It does not detail every side effect but covers the key behavioral aspects.

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 each of the five sentences adds valuable information (filters, delivery, latency). It is longer than the two-sentence ideal but remains efficient and free of fluff.

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

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

For a tool with 10 parameters, no output schema, and no annotations, the description provides a solid overview of capabilities, payload, and latency. It relies on the schema for parameter details but covers enough behavioral and use-case context to be considered 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?

Although the schema covers 100% of parameters, the description adds critical meaning by distinguishing q (ticker state filter) from event_q (event content filter) and providing examples in the /v2/events grammar. This goes beyond the schema descriptions, warranting a score above the baseline 3.

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

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

The description clearly states that the tool creates an event-trigger webhook for new events, listing specific event types and examples. However, it does not explicitly distinguish this from sibling tools like subscribe_ticker or create_webhook, so it falls short of the highest clarity bar.

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 context on when to use this tool (for new event notifications) and includes a latency caveat contrasting with state webhooks, which implicitly guides tool selection. It does not explicitly name alternative tools or state when not to use this tool, but the guidance is clear.

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

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

With no annotations provided, the description carries the full burden of disclosing side effects. It states that a webhook is registered, that it fires on changes (not continuously), and that cadence can be throttled to hourly or nyse_open. This is meaningful behavioral context beyond a simple 'subscribes to scan.' It stops short of explaining webhook payloads, unsubscription, or authentication requirements, but it does cover the key behavioral triggers and delivery options.

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 sentences long, with the main purpose in the first sentence, delivery details in the second, and cadence/use-case in the third. Every sentence contributes distinct information, and the formatting makes it easy to scan. No filler or redundant 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?

The tool has 8 parameters and no output schema, so the description should explain what happens after subscription (e.g., response containing a webhook ID) and the shape of webhook deliveries. It does not describe the payload format, how to manage/delete the subscription, or the mobile_push channel mentioned in the schema. While the main use case is covered, these gaps prevent a higher score.

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

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

The schema has 100% coverage, so the baseline is 3. The description adds minor value by restating delivery patterns (e.g., 'Pass target_url for an https POST, or channel:'discord' + discord_url') and default cadence, but these are already fully documented in the input schema. No new parameter-level insight is provided beyond what the schema already offers.

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: 'Register a webhook that fires when matches for a scan query change.' This clearly distinguishes the tool from siblings like tickerbot_subscribe_ticker or tickerbot_subscribe_signal, which target different event types. The intended use case is also stated, leaving no ambiguity about what the tool accomplishes.

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

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

The description explicitly says 'Use to satisfy "alert me when this happens" prompts,' giving a clear trigger for adoption. It also explains delivery-mode alternatives (target_url, Discord, in-app) and cadence options. However, it doesn't explicitly contrast with sibling subscribe tools, though the 'scan query change' context implicitly differentiates 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?

With no annotations, the description carries the burden of behavioral disclosure. It explains the trigger condition, the optional scoping, and the delivery options. It does not mention side effects like overwriting existing webhooks or authentication requirements, but for a subscription creation tool the described behavior is fairly transparent.

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 sentences, each serving a distinct purpose: first states the core trigger behavior, second clarifies the ticker scoping, third explains delivery channel options. No wasted words, and the structure naturally front-loads the essential action.

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 10 parameters and no output schema, the description covers the main decision points: condition type, scope, and delivery. It omits cadence (though documented in schema) and does not describe return values, but the description is sufficient for an agent to correctly configure the subscription for most use cases.

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 covers 100% of parameters, but the description adds value by explaining the interplay: booleans vs numerics for condition, ticker restriction vs full universe, and the target_url/discord_url/in-app channel logic. This enriches the schema-level definitions without redundancy.

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

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

The description clearly states the tool's core function: 'Register a webhook that fires when a signal turns true (booleans) or its value crosses a condition (numerics).' This is a specific verb+resource, and it distinguishes from sibling tools like tickerbot_subscribe_ticker and tickerbot_subscribe_scan by focusing on signal-based triggers rather than raw ticker or scan 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 provides practical usage context: optional ticker restriction, delivery channel choices, and the boolean vs numeric distinction. It does not explicitly name alternative tools or exclusions, but the inclusion of 'omit to watch the whole universe' and channel selection gives clear when-to-use 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?

With no annotations, the description carries the transparency burden. It discloses the trigger behavior (fires on condition match), delivery methods (POST/Discord/in-app), and gives a realistic condition example. It doesn't cover edge cases like validation or idempotency, but the core behavior is well described.

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

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

Two sentences, front-loaded with purpose, followed by practical usage details and an example. Every sentence earns its place without 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?

Despite 8 parameters and no output schema, the description provides enough context to select and invoke the tool correctly. It highlights the most complex parameter (condition) and the channel configuration interplay. Return values are not specified but can be inferred for a subscription creation 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 covers all 8 parameters with descriptions, so baseline is 3. The description adds value by explaining relationships between channel, target_url, discord_url, and provides an example of the `condition` parameter, going 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?

Clearly states it registers a webhook for one ticker that fires when a condition matches, with a concrete SQL clause example. This distinguishes it from broader sibling tools like subscribe_scan or subscribe_events.

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 guidance for delivery channels (target_url for HTTPS POST, discord_url for Discord, omit for in-app) and clarifies the condition format. It doesn't explicitly name alternative tools or exclusions, but the single-ticker scope is clear.

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

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

With no annotations, the description fully discloses key behaviors: synchronous execution, one-shot nature, no retries, no auto-disable on failure, byte-identical body with test header, and return format including error fields. However, it omits explicit statement about authentication requirements or potential side effects.

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 concise (three sentences) and front-loaded with the core action. Every sentence adds value without redundancy, efficiently covering behavior and constraints.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all essential aspects: action, mechanism, return values, failure conditions, and behavioral traits. No gaps 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?

Only one parameter (id) exists, and the schema already provides its description ('Webhook id.'). The description adds context that the webhook must have a target_url, which is useful beyond the schema but does not significantly enhance parameter understanding.

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 states it sends a test webhook POST synchronously with byte-identical payload and a test header, clearly distinguishing it from sibling tools like tickerbot_delete_webhook or tickerbot_list_webhook_deliveries. The verb 'send' and resource 'webhook' are specific.

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 specifies when to use (testing a webhook synchronously) and a condition when not to use (webhook lacks target_url, leading to a 400 error). It does not explicitly list alternative tools, but the purpose is unique among siblings.

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

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

With no annotations, the description carries the full burden and does well: it discloses recompilation behavior for expr, 409 conflict on renaming, ownership restrictions, and plan availability. It stops short of describing response content, but the disclosed behaviors are valuable and non-obvious.

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?

Five succinct sentences, each adding distinct value: what it does, the editable fields, special behavior for expr, renaming conflict, ownership and plan. No filler or redundancy.

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

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

For an update tool with no output schema and no annotations, the description covers the essential constraints and edge cases. It could optionally mention return values, but the provided information is sufficient for correct selection and invocation.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaning beyond the schema by noting that expr is recompiled against the live whitelist, and that new_name can trigger a 409 if other signals reference the current name. This enhances understanding of the 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 opens with a clear verb+object: 'Edit one of the caller's custom signals'. It lists editable fields and immediately distinguishes itself from siblings like create_custom_signal and delete_custom_signal by focusing on modification of existing signals.

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 clear context: only custom signals the caller owns can be patched, built-in signals are read-only, and renaming is refused if referenced. It does not explicitly name alternative tools, but the constraints effectively tell the agent when to use and when not to use this tool.

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

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

With no annotations, description must fully disclose behavior. It mentions caller ownership and system universe restrictions, but does not address return values, error cases, idempotency, or permissions. The mutation nature is implied but not elaborated.

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?

Single, well-structured sentence leads with the action, followed by clear groupings of parameter usage. Every word contributes; no fluff. Ideal length for quick parsing.

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 6 parameters, no output schema, and no annotations, description covers main usage scenarios but lacks details on success/failure responses, error handling, and permissions. Completeness is adequate for straightforward updates but falls short for a mutation 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 covers 100% of parameters with descriptions. Description adds value by grouping parameters by intent (relabel, replace, adjust) and explaining the effect of add/remove vs tickers. Accounts for deduplication in schema; description reinforces without redundancy.

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 clearly identifies the tool as updating a caller's universe, specifies actions (relabel, replace list, add/remove), and distinguishes from sibling tools like create_universe and delete_universe. Explicitly notes that system universes cannot be edited, enhancing clarity.

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?

Description provides explicit guidance on when to use each parameter group (relabel, replace, adjust subsets) and notes that system universes are ineligible. Implicitly contrasts with create/delete siblings, but could explicitly state when to choose this over alternatives.

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