Flexreport Finance

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

Goes well beyond the annotations: exact return payload ({"status": "DELETED", ...}), the side effect that open streams receive a `closed` frame within one read cycle (<= 8 s), the 404 unknown subscription_id behavior (including another user's id), rate limits, and the OAuth requirement. The idempotent/destructive hints are confirmed rather than repeated.

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

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

Front-loads the operation and endpoint, then layers return shape, streaming side effect, error case, rate-limit rationale, and auth in compact sentences. Slightly dense with parentheticals, but every sentence carries decision-relevant 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?

Covers the full call surface: auth requirement, error semantics, post-delete streaming consequence, and the rate-limit context that motivates using this tool at all. With an output schema present it need not describe returns further, yet its extra detail is accurate and helpful rather than redundant.

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

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

Schema description coverage is 100%, and the schema already ties subscription_id back to register_event_subscription's return value. The description restates the identifier but adds no format, syntax, or lookup detail beyond the schema, so the baseline 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?

States a specific verb and resource ('Remove a saved event subscription') and even names the HTTP route, so there is no ambiguity about the operation. It does not explicitly name or contrast itself with siblings like register_event_subscription or stream_event_subscription, so it falls short of the top tier that requires sibling differentiation.

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

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

Gives genuine operating guidance: because registrations are rate-limited (30/hour), the agent should delete subscriptions the user is done with rather than re-registering each session. This implies the when-to-use context clearly, though it does not name an alternative tool explicitly or state hard 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?

Goes well beyond the annotations: it discloses that deletion is permanent and that query tokens are destroyed and cannot be reconstructed, explains that a 404 deliberately conflates 'does not exist' with 'not yours' so the agent must not leak ownership, documents the return payload, auth requirements, and a 100/min rate limit. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loads the action and keeps each sentence purposeful (destructiveness, ambiguity handling, 404 semantics, auth/rate limits). The explicit return-value line is somewhat redundant since an output schema exists, which keeps it from a 5.

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 destructive tool with annotations and an output schema, the description covers everything an agent needs: safety profile, idempotency implications, failure semantics, prerequisites, and rate limits. 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?

Schema coverage is 100% and the schema itself already clarifies that query_id is the row id from list_saved_queries, not a list position or user_request. The prose adds only the phrase 'by id', so it does not meaningfully extend the schema — 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?

States a specific verb and resource ('Delete one of your saved data requests by id') and scopes it to the user's own saved queries, distinguishing it from siblings like list_saved_queries, run_saved_query, and save_user_query. An agent can identify the operation without inspecting the schema.

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

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

Gives a concrete precondition for invocation ('when more than one row looks like a match, confirm WHICH one with the user') and describes the recovery path for an accidental deletion (re-run explore_data_catalogue and re-save). It does not explicitly name list_saved_queries as the id source in prose (that lives in the schema), so it falls just short of naming alternatives outright.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it specifies that only the cron schedule is removed while the saved workflow definition survives, gives the recovery path (re-save via `schedule_task`), and documents success/error return behavior. For a destructive tool, disclosing the exact scope of destruction and what is preserved is exactly the added value needed.

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?

Purpose is front-loaded in the first sentence and the body earns its place with scope and return details. The phrasing around workflow schedules ('the value `schedule_task` returned as `task_name`') is slightly convoluted and could be tightened, but nothing is wasted.

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

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

Covers purpose, name-source convention, blast radius, recovery path, and return/error behavior, and an output schema exists for the response shape. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool semantics the schema alone does not: for workflow schedules `task_name` is the value returned by `schedule_task` as `task_name`. This resolves real ambiguity about which identifier to pass.

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

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

States a specific verb (Delete) and resource (scheduled task / cron job) plus the identifier used to select it. It is immediately distinguishable from the many sibling delete_* tools (delete_event_subscription, delete_saved_query, delete_user_template) because the resource is named explicitly.

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

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

Clarifies the key selection consideration for workflow schedules and frames the operation as removable/re-creatable via `schedule_task`, which is genuinely useful routing context. It does not, however, state any explicit when-not-to-use condition or prerequisites (e.g. permissions, effect on running jobs).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantially more: permanence with no history, server-side ownership enforcement limiting it to the caller's own template, the exact success payload, 404 semantics, OAuth auth requirement, and a 100/min rate limit. No claims conflict with the annotations.

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

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

Front-loaded and well-paragraphed with each sentence carrying weight, but the explicit return-value sentence is partially duplicative given a structured output schema already exists.

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

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

For a zero-param destructive mutation, the description covers safety, reversibility, ownership, auth, rate limits and error behavior; an agent has everything needed to decide and invoke correctly, and return values are reinforced by the output schema.

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

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

The tool takes zero parameters, so the baseline is 4; there is no argument meaning to convey and the description correctly avoids inventing any.

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

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

States a specific verb+resource (delete the user's saved PDF template) plus the consequence (PDFs revert to standard layouts), which cleanly separates it from draft_user_template, save_user_template, update_user_template and get_user_template.

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

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

Gives an explicit prerequisite ('Confirm with the user before calling') and a useful negative condition ('A 404 means there was nothing saved to delete'), and the 're-creating the format means drafting and saving again' line implicitly points at the sibling tools for the alternative path. It never names an alternative tool outright, so it stops short of a 5.

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

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

Goes well beyond the readOnlyHint annotation: synchronous execution with no task id to poll, direct return of flagged bars, a 404-style error when no intraday data exists yet, and automatic OAuth bearer attachment. These are exactly the operational facts an agent needs before calling.

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

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

Front-loaded with the live-today purpose, then mechanics, then error/auth notes. Every sentence carries information, though it runs slightly long for three 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?

An output schema exists, so return values need not be described; the description nonetheless covers the synchronous contract, the failure mode, and auth. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: moves are scored against the stock's own daily-return volatility, the day is US/Eastern, and frequency is defined as the intraday bar size. Z-score semantics are clarified beyond the schema's terse 'Daily-sigma cutoff'.

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

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

States a specific verb+resource+scope: pulls TODAY's live intraday bars for a symbol and flags bars whose |z-score| exceeds a threshold. It is clearly distinguishable from siblings like get_technical_indicator_data, get_aftermarket_data, and get_company_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?

Gives a clear usage context ('quick is the stock making an abnormal intraday move right now? read') and implicitly scopes to live/today rather than historical analysis. It does not, however, name a sibling alternative or state when NOT to use it (e.g. after-hours vs. get_aftermarket_data).

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

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

Annotations only declare readOnlyHint=true, but the description adds substantial behavior: the fetch happens server-side, only S3 hosts ending in amazonaws.com are accepted, other hosts get a 400 (SSRF guard), and OAuth auth is attached automatically. This is meaningful disclosure well beyond the annotation.

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

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

Front-loaded with the core action and return type, then layers the SSRF guard, alternative routing, and auth note. All sentences earn their place, though there is mild redundancy with the schema's own url description.

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 2-parameter tool with no output schema, the description fully specifies the return shape ({file_name, media_type, report} as base64), the auth model, and the rejection behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description largely restates the url constraint (presigned S3, amazonaws.com) that the schema already carries. The baseline 3 applies since the schema does the heavy lifting and the description adds little new parameter syntax.

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

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

States a specific verb (fetch/download) and resource (presigned S3 PDF URL), and describes the return (base64 document). It explicitly distinguishes itself from the sibling get_latest_report, so an agent can tell them apart without opening either schema.

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

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

Gives explicit when-to-use (clients that can't open the link directly and need the document inline) and, rarer still, an explicit when-not-to (if you already have get_latest_report's report field, use it directly). It names the alternative and the condition selecting 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?

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds far more: nothing is persisted (24h cache), async with PENDING task_id and polling, minutes of latency from a model pass plus per-treatment render, OAuth auth, 30/min rate limit, 422 error shape via detail.errors, and the meaning of warnings/empty variant lists. No contradiction with the annotations.

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

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

Front-loaded and organized with THE POINT / THE FLOW / TEMPLATE RULES headings, and nearly every sentence carries operational weight. It is on the long side, and the finished-result JSON shape partly duplicates the existing output schema, but the density is justified by the tool's complexity.

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

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

Covers everything an agent needs for a complex, async, multi-step tool: the two-step workflow, polling requirement, template constraints, error and warning semantics, auth and rate limits, and the type-specific rendering behavior. Output schema exists, so return values are not the description's burden, yet the warnings interpretation is still supplied.

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 already 100%, but the description still adds real meaning: it explains the visual consequence of template_type ('add_on' renders at the 360pt column and clips rather than scales, stripping the host page chrome; 'bespoke' previews full pages), restates the anchor substring-matching requirement, and notes the 200KB/markdown-422 constraint on template.

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

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

States a specific verb+resource+outcome: renders PNG previews of a user's PDF template so it can be approved visually before saving. It explicitly positions itself as 'STEP 1 OF 2' and names save_user_template as step 2, so an agent can distinguish it from the sibling save/update/get template tools without opening any schema.

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

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

Gives an explicit numbered flow (author HTML -> call this -> poll get_task_status -> user picks -> save_user_template), names the alternatives (save_user_template, update_user_template, get_task_status) and the condition that selects each, and states an exclusion: never save a treatment the user has not seen.

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?

Far exceeds the annotations: async task_id/PENDING contract, 1-5 min timing, single-task polling via get_task_status, full (non-sampled) row semantics, REJECTED validation_status path, the 20/hour server-side rate limit, and the query_token/save_user_query lifecycle. None of this is derivable from the structured fields.

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

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

Front-loaded with the core purpose and arrow-marked sections help scanning, but the description is extremely long and repeats the event-driven guidance twice (the ===> situate block and the later 'EVENT-DRIVEN QUESTIONS' paragraph), plus restates the saving offer after already covering it. Significant redundancy for a one-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?

Covers the async contract, result shape, provenance/citation workflow, rejection handling, and the save/replay lifecycle — more than enough given an output schema exists. The main gap is length-driven redundancy rather than missing information.

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

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

Schema coverage is 100% and the tool has one well-described 'query' param, so baseline is high. The description adds real value beyond the schema by specifying that event-driven questions should take the query from situate(...)'s plan and by describing how query_token relates to saving, though it doesn't add syntax guidance for the query string itself.

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

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

States a specific verb+resource (explore the data platform/catalogue) and precisely delimits it against siblings: list_options for enumeration, explore_data_coverage for coverage counts, generate_research_report for the deep dive. An agent can route correctly without opening any schema.

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

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

Explicit when-to-use defaults ('THE DEFAULT, FIRST-STEP tool whenever the user wants to EXPLORE'), when-not-to-use (coverage questions → list_options / explore_data_coverage; report → generate_research_report only after explicit ask), plus the ordered pre-steps (list_saved_queries, situate) and a 'RUN THIS BY ITSELF FIRST' rule.

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?

Without leaning on the thin annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the backend is public and not plan/quota-gated, that there is a 20/hour server-side rate limit, that execution is asynchronous returning a task_id polled via get_task_status, the 1-5 minute latency profile, and that rows are not sampled or truncated. It even covers the REJECTED validation_status failure path — far beyond what annotations convey.

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

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

It is long, but front-loaded and information-dense: routing rule first, then gating, then async contract and result shape. A few clauses repeat the coverage-counting idea, costing some tightness, yet nearly every sentence carries operational value an agent needs.

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

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

For a single-parameter async tool it covers everything an agent needs: routing, entitlement expectations, polling loop, timing tolerance, success and rejection result shapes, and rendering instructions. An output schema exists, so the embedded result description is a bonus rather than a necessity.

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% for the single `query` parameter, so the baseline is 3; the description adds real meaning by specifying the query should be the coverage question in natural language as asked, and by explicitly stating that no `delivery` argument exists and why. That last point resolves an ambiguity the schema alone leaves open.

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 ('Answer a question about WHAT THE PLATFORM COVERS') and immediately narrows the scope to counts and breakdowns of coverage, contrasted explicitly against list_options and explore_data_catalogue. An agent can distinguish it from every coverage-adjacent sibling without opening a schema.

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

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

It gives an explicit three-way routing rule keyed on the shape of the expected answer (list -> list_options, count/breakdown -> this tool, actual data -> explore_data_catalogue), plus a negative instruction not to answer from memory or from headline universe totals. When-to-use and when-not-to-use are both stated.

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

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

Annotations only say readOnlyHint=false/destructiveHint=false. The description adds critical behavior: ~10 minute duration, async task_id return with get_task_status polling, standard mode SAVES the plan while custom mode is NOT saved, a 422 backend rejection without user_override, and OAuth attachment. Far exceeds what the annotations convey.

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

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

Front-loaded with the rebuild verb and the 'never the first call' warning, and organized into STANDARD/CUSTOM/ontology sections. It is long, but for an 11-param two-mode tool most content earns its place; a few connective passages could be tightened without losing meaning.

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 an output schema existing, the description still documents the return contract ({"<TICKER>": {"task_id", "status": "PENDING"}} and the polled result's {"pdf": "<base64>"}). Combined with mode semantics, the 422 rule, auth, and the ontology workflow, an agent has everything needed to call and follow up correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds real value beyond the schema: it explains that user_override is auto-set when any shaping field is non-empty (so a shaped request is never silently downgraded), and provides the ontology-driven derivation rules for choosing which shaping fields to populate. That derivation logic is not present 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?

Opens with a specific verb+resource+scope: 'FULL REBUILD of ONE ticker's report (~10 minutes)'. It explicitly distinguishes itself from get_latest_report (the fast path) and generate_research_report (open-ended/multi-company), so an agent can identify the correct tool without opening schemas.

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

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

States when to call it ('ONLY after get_latest_report returned stale: true or in missing'), when not to ('NEVER for a symbol that came back in rendering', 'never fanned out'), and names the preferred alternatives for bespoke asks (explore/ideate/overlay via list_saved_queries, explore_data_catalogue, get_user_template). Explicit routing to siblings throughout.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantial context the annotations do not: a server-side rate limit of 20/hour per user, asynchronous execution semantics, the exact return shape ({"task_id", "status": "PENDING"}), and the polling workflow via `get_task_status`. It also warns this is the slow (~10-12 min) professional deep-dive. No annotation contradiction.

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

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

Front-loaded with a clear '===> THE RIGHT TOOL' marker and logically ordered routing rules. It is longer than needed: the 'EXPLICITLY asks for the full report' constraint is stated twice and the options are spread across several paragraph fragments.

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 rate-limited, asynchronous, multi-minute job with an output schema present, the description supplies everything an agent needs: routing against three siblings, throttling, async return contract, and the polling follow-up. Since an output schema exists, it correctly avoids explaining the final report's contents.

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 both `query` and `delivery` are already documented by the schema, establishing the baseline of 3. The description reinforces `query` semantics via inline examples but says nothing about `delivery` channels or the delivery effect, so it does not exceed the schema.

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

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

States a specific verb (generate) and resource (research report) with clear scope: open-ended or thematic questions, extensible, multi-section. It explicitly contrasts itself with `get_latest_report` and `explore_data_catalogue`, so an agent can distinguish it from siblings without opening a schema.

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

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

Gives explicit when-to-use ('intent is a QUESTION rather than a request for an existing report'), when-not-to-use (plain 'get me the latest report' → `get_latest_report`; exploration → `explore_data_catalogue` first), and sequencing rules ('never run both for the same question at once', 'reach for THIS deep-dive only later'). Nothing is left to inference.

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?

Although annotations already declare readOnlyHint=true, the description adds substantial context: the data is a stored tape rather than a live feed, it is polled every 15 minutes from 16:30 ET with up to ~15 min lag, the 16:00-20:00 ET window and row ordering, plus auth (OAuth bearer) and a 300/min rate limit.

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

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

Front-loads the core purpose in the first sentence, then layers scope, caveats, defaults, and edge cases as separate short paragraphs. No sentence is redundant, and the sibling reference is placed at the point of contrast.

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

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

An output schema exists so return values need not be described, and the description nonetheless covers the operational profile an agent needs: stored/lagged semantics, time window, ordering, defaults, empty-result behavior, auth, and rate limits.

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

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

Schema coverage is 100% and both datetime defaults are already documented in the schema, so the baseline is 3. The description still adds interpretive value by framing omitting both datetimes as 'today's aftermarket tape' and by explaining the sort order (symbol then bar time DESC, latest first) that shapes how the params return data.

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

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

States a specific verb and resource with scope: 'Query STORED after-hours 15-minute bars (open/high/low/close/volume) for symbols.' It explicitly distinguishes itself from the sibling detect_intraday_outlier_jumps by contrasting the recorded aftermarket tape with a live intraday read.

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?

Names the alternative tool and the condition that selects it ('for a live intraday read of the regular session use detect_intraday_outlier_jumps instead'), and gives explicit guidance on omitting datetimes for today's tape. It also pre-empts a common confusion by stating an empty bars list is not an error.

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

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

Annotations only declare readOnlyHint=true; the description carries far more — public backend/no entitlement, transport-level OAuth caveat, 60/min rate limit, edge caps (~3 per cause type), market_context cap of 5, and the degraded empty-web semantics. It also warns that a missing edge is not evidence of non-relation and that `at` is a write time, not a business date.

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

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

Front-loaded with purpose and broken into labelled sections, which helps, but it is roughly a thousand words for a three-parameter tool. The get_event_ontology pairing is stated at least three times and the snapshot contrast is belaboured, so a meaningful share of the text does not earn 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?

An output schema exists, yet the description still covers node kinds, edge shape and confidence grades, the chaining recipe, auth fallback on get_signed_sql_drilldown, and the empty-web fallback — everything needed to call and interpret it correctly. No gap remains.

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, but the description adds real meaning: window_days should be widened before concluding a snapshot move is unexplained, and max_nodes interacts with per-node edge capping and the market_context cap. It stops short of documenting defaults in prose, but the capping semantics are genuinely additive.

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

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

States a specific verb+resource ('fetch the connected WEB of what recently HAPPENED to a company') and immediately frames the scope as the WHY behind the snapshot. It explicitly differentiates itself from siblings — situate already returns the web, get_company_snapshot gives the WHAT — so an agent can pick the right tool without opening a schema.

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

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

Explicit when-to-use (single-company 'catch me up', 'why is the thesis negative', before aiming a targeted explore_data_catalogue/generate_report_for_stock call), when-not-to-use ('do NOT use this tool to state the company's current position'), and named alternatives (start with situate, pair with get_company_snapshot and get_event_ontology). Nothing is left to inference.

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

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

Annotations declare only readOnlyHint=true, so the description carries the behavioral burden and does it well: synchronous and cheap, fixed block set, point-in-time semantics, per-block as-of dates (13F can be a quarter old), and the failure mode of misreading blocks as a comparable series. This is context an agent could not get from the structured fields.

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

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

Front-loaded with purpose before the caveats, and the bolded section headers make it scannable. However, the point-in-time constraint is restated several times across the warning and pairing paragraphs, so the piece is longer than a one-parameter read tool strictly requires and carries mild redundancy.

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

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

With an output schema present, return values need not be explained, and the description nonetheless enumerates the returned blocks. Combined with the routing rules, timing caveats, and pairing guidance, nothing an agent needs to call this correctly is missing.

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

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

Only one parameter (symbol), schema description coverage is 100%, and the description adds nothing beyond the schema's 'Covered ticker, e.g. AAPL.' Baseline 3 for a fully documented single-param schema 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?

Opens with a specific verb+resource — 'Fetch a structured, POINT-IN-TIME company snapshot' — and immediately enumerates what blocks it returns (thesis/bull/bear, financial overview, price performance, targets, ownership, grades). It is clearly distinguished from near-siblings like generate_report_for_stock, explore_data_catalogue, and list_options, so an agent can pick it without opening any schema.

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

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

Explicit when-to-use ('quick CURRENT read', general company questions), explicit when-NOT-to-use (any temporal/trend/'over time' question, coverage enumerations), and names the replacement tool for each case (explore_data_catalogue, list_options). It also instructs the standard pairing with get_company_event_web and states the selection reason (WHAT vs WHY).

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 only readOnlyHint=true in annotations, the description carries real behavioral load: auth requirement, the common 404 cause and its remedy, that transcript_url is frequently null (so don't offer a link), that highlights are pipeline-verified but not necessarily your quote, and that total_sections bounds n. None of this contradicts the annotations and none of it is recoverable from structured fields.

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 lead sentence is front-loaded and the purpose is clear before any caveats. It is on the long side, and the bold fiscal-period warning partially duplicates the schema's own field note, but every remaining sentence (citation derivation, 404 remedy, highlights semantics, null transcript_url) earns its place.

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

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

For a 5-parameter authenticated read tool with an output schema, the description covers the things the schema cannot: auth handling, error interpretation, how to read a mid-answer passage via adjacent sections, and caveats on two return fields. Nothing material an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description goes beyond the schema by explaining where each value originates (the citation URL's name/symbol/year/quarter/n components, or the transcript row's section_no) and by stressing the fiscal-vs-calendar period trap. It doesn't add per-parameter syntax beyond that, so it stops short of 5.

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

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

The opening line states a specific verb and resource with exact scope: 'Open ONE numbered section of a source document — the exact earnings-call speaker turn a citation points at.' It positions itself against siblings by naming trace_data_sources as the counterpart and clarifying the grain ('not the whole call, one turn of it'). An agent can distinguish this from transcript-listing tools without opening a schema.

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

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

It gives explicit when-to-use ('read the passage behind a number before quoting it... quote a speaker verbatim with the citation intact'), describes the alternative acquisition path ('if you pulled the row from earnings_call_transcript_sections yourself you already hold all four'), and instructs to derive args from the citation URL rather than guess. The 404 troubleshooting guidance is an unusually strong when-it-fails clause.

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

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

Annotations only declare readOnlyHint=true, yet the description discloses cost/latency profile (cheap, synchronous, public, symbol-independent, cacheable, fetch once and reuse), response sizes (~5-10 KB per card, ~230 KB unfiltered), the `degraded=true` meaning, and the freshness/lag semantics that are the tool's whole rationale.

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?

Well front-loaded and sectioned with headers, but it is very long and the field-by-field enumeration of what an event_type/relation card carries duplicates content that a present output schema already covers. Much of it earns its place; a meaningful fraction does not.

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 ontology tool with a rich return surface, the description covers selection, sequencing relative to `situate`, filter semantics, freshness caveats, and provenance grading. Even accounting for the existing output schema, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real value beyond the schema: the 'pass exactly ONE filter' constraint, expected card sizes per filter, and the mapping of web-node keys (`type`/`relation`/`family`) onto the parameters. The per-parameter examples largely restate the schema, keeping it from a 5.

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

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

States a specific resource and its scope: 'the platform's event ONTOLOGY — what an event TYPE means for everything else.' It explicitly distinguishes itself from siblings by naming `situate(...)` as the composing entry point and describing when to call this one directly instead.

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

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

Gives explicit when-to-use ('Call it FIRST on any real-time, single-company, or event-driven request'), names the alternative (`situate` composes this), and lists when-not/requisite conditions plus the freshness-check routing to `detect_intraday_outlier_jumps` / `get_aftermarket_data`. Nothing is left to inference.

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

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

Annotations only declare readOnlyHint=true, so the description carries the real burden and delivers: rate limit of 500/hour, OAuth auto-attached by the client, ~10-20s render vs ~10min rebuild, the fact that nothing regenerates on its own, and the meaning of stale true/false/null and the `rendering`/`missing` buckets. This is far beyond what the annotation provides.

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

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

Long but highly structured and front-loaded, with the default-tool claim in the first line and the branch semantics broken out per field. Slight redundancy: 'USE THIS BY DEFAULT', the ===> header, and 'ALWAYS call this before...' restate the same priority three times, but nothing is genuinely wasted.

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

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

Given no output schema, the description reproduces the return shape in full (result/missing/rendering, url vs base64 semantics, presigned ~6h validity) and covers every branch an agent must handle before handing a document over. Nothing needed to call or interpret the tool correctly is missing.

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

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

Single parameter with 100% schema description coverage (uppercasing, dedupe, 100-symbol cap, 413 status), so the schema baseline is 3. The description still adds operational meaning by stating lists longer than 100 symbols must be split across calls, which the schema does not express as workflow guidance.

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

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

States a specific verb+resource (retrieve the latest Flexreport research report for one or more tickers) and immediately positions itself against siblings, declaring itself the default and naming `generate_report_for_stock`, `explore_data_catalogue`, and `generate_research_report` as the alternatives. An agent can route to it without opening any schema.

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

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

Explicit when-to-use (queries for 'the report', 'research', 'analysis', 'the PDF') and when-not-to-use (open-ended exploratory questions → explore_data_catalogue; bespoke reports → explore + get_user_template; full deep-dive → generate_research_report). Includes the ordering constraint to call this before generate_report_for_stock.

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

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

Annotations only give readOnlyHint=true, and the description layers substantial extra behavior on top: HTTP 403 means invalid/tampered token with no-retry guidance, 422 means slot-mapping failure, auth is required (unlike the public get_company_event_web), and uncapped drilldowns can stall the client for minutes. These are exactly the operational facts annotations cannot express.

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 critical routing facts (what it fetches, which token, which sibling to use instead) are front-loaded in the first two paragraphs. It is long and somewhat sprawling across provenance, error codes, and auth, but nearly every sentence carries distinct, load-bearing information rather than filler.

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

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

Covers token provenance, the two value-fill paths, truncation via `max_rows`, 403/422 failure modes, auth requirements, and the `_source_*`/`sources` provenance contract with follow-on tools (trace_data_sources, get_document_section). Even though an output schema exists, the description goes further and explains the `is_new_record` flag and the `parameters` echo, leaving nothing an agent needs in order to call or interpret 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%, so the baseline is 3, but the description adds real meaning: the URL form is auto-unwrapped so either the full `signed_query_url` or just its `t` works, and `values`/`prompt` only apply to PLACEHOLDER TWIN tokens and produce a `parameters` block to echo. It goes beyond restating the schema without fully exhausting token-slot vocabulary (which it delegates to list_saved_queries).

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?

Opens with a specific verb+resource+scope: 'Fetch the rows behind an event-web drilldown from its server-minted query token.' It explicitly distinguishes itself from the closest siblings — get_company_event_web, run_saved_query, list_saved_queries — so an agent can route correctly without opening any schema.

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

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

Names the exact precondition (a node carrying `signed_query_url` from get_company_event_web), the explicit exclusion (tokens from SAVED requests belong to `run_saved_query` instead, 'not this tool'), and the alternative-route vocabulary source (`list_saved_queries` -> `metadata.parameters`). When/when-not/alternatives are all covered.

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

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

Annotations already declare readOnlyHint=true, but the description adds genuinely useful context: synchronous execution, no auth required, and the semantic distinction between current-basket YTD returns and realized track record. It stops short of rate limits or response-size behavior, keeping it just below the top tier.

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

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

Front-loaded with the core purpose in the first sentence, followed by return semantics and routing guidance in logical order. It is slightly long, but nearly every sentence carries a distinct fact, so there is little waste.

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

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

An output schema exists, so return values needn't be enumerated, yet the description still clarifies the semantics of ytd_return and basket_ytd_return. Combined with the no-auth/read-only disclosure and sibling routing, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and the single strategy_name parameter is already documented with examples in the schema; the description text adds no further parameter guidance. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Fetch the latest LLM-selected stock picks') and immediately clarifies scope with 'current rebalance holdings.' It also names the sibling tools it is not, so an agent can route between this and the performance tools without opening schemas.

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

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

Explicitly names the alternatives (get_strategy_performance_summary / get_strategy_track_record) and the condition that selects them ('how the strategies have ACTUALLY performed since inception'), contrasting with the current-basket YTD view this tool provides. Clear when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the sort key (excess return over the S&P 500), the one-row-per-book granularity, and the meaning of growth_strategy/growth_sp as the value of `amount` invested at inception.

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

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

Front-loaded with the one-line purpose and the headline use case, then supporting detail. The inline enumeration of twelve return fields is somewhat long, but it is the tool's actual payload and each remaining 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?

The tool returns a single flat table with one parameter and an output schema, so almost nothing is left to infer: purpose, sorting, row shape, and drill-down paths are all stated. The field list partially duplicates the output schema, which keeps it just short of a 5.

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 `amount` param already documents 'dollar amount assumed invested at inception; scales growth_strategy / growth_sp'. The description's explanation of growth_strategy/growth_sp restates that same semantics, so it adds little beyond the schema — 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?

Opens with a specific verb+resource+scope: a since-inception performance leaderboard versus the S&P 500 across all strategy books. It also explicitly distinguishes itself from siblings get_strategy_track_record and get_strategy_swaps, so an agent can route without opening a schema.

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

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

'THE first stop for "how are the stock picks / strategies performing?"' gives an explicit entry-point condition, and the closing sentences name the two alternatives with the conditions that select them (full daily series vs per-trade adds/drops).

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest of the burden. It discloses the non-obvious measurement semantics (ADD measured entry-to-exit, DROP as foregone return exit-to-latest-close, both vs S&P over the same window), which materially affects interpretation. It omits any statement about data freshness/latency or weighting assumptions, keeping it short of a 5.

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

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

Front-loads the one-line purpose before the methodology and routing note, and each sentence serves a distinct purpose. However, the verbose restatement of the return shape duplicates the existing output schema and could be trimmed.

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?

Read-only annotations plus a full output schema mean the safety and return-value burdens are covered elsewhere. The description adds the computational definitions needed to interpret the numbers correctly, though freshness/coverage caveats for the latest close are unstated.

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

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

Schema coverage is 100% and the enum already enumerates the five valid values, so the schema does the heavy lifting. The description adds only the scoping emphasis "ONE strategy book" and does not explain why pooled behaves differently beyond what the enum description states; 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?

States a specific artifact (per-trade swap ledger of adds/drops), the benchmark (S&P 500), and the scope (ONE strategy book). It also explicitly routes the agent elsewhere for the book-level time series, so it is distinguishable from siblings like get_strategy_track_record without reading either schema.

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

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

Gives the exact question this tool answers ("were the individual trades good?") and names the alternative tool plus the condition that selects it (book-level return series -> get_strategy_track_record). When-to-use and when-to-use-something-else are both explicit.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest and does so well: the 404-on-missing-history behavior and the fact that the Sharpe series is expanding-window and annualized with rf=0 are non-obvious traits an agent could not infer. It does not cover pagination or rate limits, keeping it short of a 5.

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

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

Purpose is front-loaded in one line and the routing/404 caveat is well placed, but the multi-line inline JSON dump of summary and series fields is redundant given an output schema exists — it consumes most of the description without adding selection 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?

For a read-only reporting tool with full schema coverage and an output schema, the description supplies everything an agent needs: scope, the 404 edge case, metric semantics, and sibling routing. Nothing required for correct invocation is missing.

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

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

Schema description coverage is 100% and both enums (book, strategy_name) are fully documented in the schema, so the baseline of 3 applies. The description adds nothing about the 'amount' scaling or enum choices beyond what the schema already states.

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

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

States a specific verb+resource with explicit scope: 'Since-inception daily track record vs the S&P 500 for ONE strategy book.' The 'ONE' and the sibling routing immediately distinguish it from the cross-book summary and the holdings tool.

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 names two alternatives and the condition that selects each: get_strategy_performance_summary for a cross-book leaderboard, get_stock_picks for current holdings. It also warns that the backend returns 404 when the chosen book has no history, which is a real usage constraint.

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

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

Annotations only declare readOnlyHint=true, so the description carries the interesting burden and does so: it documents the status lifecycle (PENDING, SUCCESS, FAILURE, RETRY) and that `result` is only populated at SUCCESS. It omits polling interval, task retention/expiry, and what FAILURE returns, which are relevant for a poll-based 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?

Front-loads the core action, then the return contract, then the status enum — a sensible ordering. The parenthetical tool list is long and trails off with an ellipsis, costing a little tightness, but nothing is redundant with the schema or annotations.

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

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

No output schema exists, so the description correctly steps in to describe the return shape, status values, and result population. It remains silent on polling frequency and on what `result` contains for each task type, minor gaps for a polling tool but not blocking.

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 with 100% schema description coverage ('The task_id an async tool returned'), so the schema already does the work. The description implies the task_id links to a prior async call but adds no syntax or format detail beyond that, making the baseline 3 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?

States a specific verb and resource ('Poll the status of an async job') and then enumerates the concrete producer tools (generate_report_for_stock, explore_data_catalogue, screen_stocks, etc.) whose task_ids this consumes. An agent immediately understands this is the status-check companion to the async report/exploration tools, and no sibling overlaps this role.

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?

Clearly signals the usage context: call it after invoking one of the listed async tools that returned a task_id. It does not, however, give any when-not-to-use guidance or polling cadence advice, but the retrieval scenario is unambiguous.

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

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

Goes well beyond the readOnlyHint annotation: it discloses error semantics (404 for unknown symbol, 400 with valid values for unknown indicator), the return shape (one row per trading day, ordered by date, column set varying by indicator), and the empty-range behavior. Auth requirement is also stated explicitly.

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

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

Front-loaded with the one-line purpose, then prerequisite, then error/return behavior, then auth – a logical order with no filler. The return-shape sentence is partially redundant given an output schema exists, which is the only real trim opportunity.

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 4-required-param read tool with an output schema, the description still covers the prerequisite dependency, both failure modes, ordering, and auth, so an agent can call it correctly on the first attempt. Nothing material is missing.

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

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

Schema description coverage is 100%, including the list_options cross-references and the YYYY-MM-DD inclusive semantics, so the schema already carries parameter meaning. The description adds only the aggregate notion of a date range and per-row date ordering, which is not materially beyond the schema. Baseline 3 applies.

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

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

Names a specific verb ("Fetch"), a specific resource ("historical technical-indicator series"), and the scoping axes (symbol, date range). This is clearly distinguishable from siblings like get_company_snapshot or get_aftermarket_data without opening any schema.

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

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

Gives a concrete prerequisite: call list_options("technical_indicators") first to obtain valid indicator names, which prevents a predictable 400. It stops short of stating when-not-to-use this tool or naming an alternative series endpoint, so it is clear context without exclusions.

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

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

Annotations only declare readOnlyHint=true; the description adds substantial context beyond that: the 404-vs-503 semantic distinction, the auth requirement, the 100/min rate limit, the fact that save replaces without history, and that the returned template is sanitized markup capped at 200 KB while the compiled blueprint is withheld.

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

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

Front-loads the return value and the primary usage trigger, then layers routing guidance and edge cases. Most sentences earn their place, though the enumerated Returns listing partially duplicates the output schema and could be trimmed slightly.

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

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

Given an output schema exists, return values needn't be spelled out, yet the description adds the useful nuance that the compiled blueprint is not returned and the 200 KB cap. Combined with auth, rate-limit, and error-code semantics, nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter detail is needed or missing.

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

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

States a specific verb+resource (returns the user's saved PDF template) and immediately distinguishes it from sibling tools like save_user_template, draft_user_template, and update_user_template. The one-line opener plus the 404 case makes the tool's identity 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?

Explicitly names three triggering scenarios (answering 'what format am I on?', before save_user_template because saving replaces without history, and before composing a PDF so the markup matches). It also names alternatives (draft_user_template, update_user_template) and gives the conditional cue that a 404 is the signal to offer drafting.

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context: unknown/wrong-case codes yield a 400 'Exchange not found.', no auth is required, and it discloses the return shape (one-element list, isMarketOpen boolean, session hours, timezone).

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

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

Front-loads the core purpose and the error contract, then the routing guidance, then the code-sourcing tip. Multi-line but every sentence carries distinct, actionable information with no filler.

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

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

Covered despite an existing output schema: error behavior, auth, routing, and parameter pitfalls are all addressed. Nothing an agent needs to call this correctly or act on the result is missing.

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

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

Schema coverage is 100% (baseline 3), and the description goes further by stressing the case-sensitivity pitfall, that full names are invalid, and that NYSE is the right default for US equities, plus how to source the value from get_company_snapshot.

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

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

States a specific verb+resource ('check whether an exchange is currently open') and distinguishes itself from market-hours siblings as a 'cheap routing helper'. An agent immediately knows this is a lightweight status probe rather than a data-fetch tool.

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

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

Gives explicit routing rules: when CLOSED, use get_aftermarket_data; when OPEN, use detect_intraday_outlier_jumps. It also handles the prior-step question of how to get a valid exchange code via get_company_snapshot.

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

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

Beyond the readOnlyHint annotation, it discloses that it does not build/return reports, rate limit (500/hour), synchronous behavior, auth requirement, the meaning of an empty result, the redis-vs-s3 source distinction, and the fresh/stale render semantics. This is well past what the annotation alone conveys.

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?

Purpose is front-loaded and the body is organized under clear headers (TWO WAYS IN, PICKING THE MOST PERTINENT PLANS). It is on the verbose side with some redundancy in the workflow narrative, but nearly every sentence carries routing or behavioral 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?

Covers auth, rate limits, error conditions, the empty-result edge case, and the full decision flow from event to plan to pull, despite an output schema already existing. An agent has everything needed to call it correctly and interpret the response.

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

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

Schema coverage is 100%, so the schema documents both params, but the description adds meaningful semantics: report_date is a lower bound defaulting to today, earlier dates widen the window and cost more, and plans stay renderable for 7 days. It also enumerates the valid event_types and the 422 failure mode.

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

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

The opening sentence states a specific verb and resource — 'List the symbols with a report plan SAVED on or after report_date' — and immediately scopes it as an inventory that does not build or return a report. It explicitly differentiates from the two nearest siblings, get_latest_report and generate_research_report.

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 two named entry paths (event-first vs research-first), tells the agent when to widen report_date, when to use list_realtime_events first, and when generate_report_for_stock is the correct follow-up. Explicit exclusions ('Not get_latest_report... Not generate_research_report') remove ambiguity about 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?

Goes well beyond readOnlyHint by disclosing silent dropping of out-of-coverage symbols, server-side enum validation returning 422, the AND-combination of filters, empty-list-on-no-match, and that "nan" means not available. This is rich behavioral context an agent needs.

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

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

Front-loads the core action, then layers date-window defaults, coverage caveats, and validation notes in short, scannable sentences. Every sentence carries distinct 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?

For a 6-param read tool with an output schema, the description covers the missing pieces: date defaults, silent filtering, enum validation, auth, and the "nan" convention. Nothing needed to call it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: dates default to today, filters combine with AND, and invalid enum values trigger 422. That goes beyond what the schema properties state individually.

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

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

States a specific verb (List), resource (scheduled earnings announcements), and scope (within a date window, Flexreport names only). An agent can immediately distinguish this from predict_earnings_move or get_company_event_web.

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

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

Gives concrete when-to-use guidance ('Omit both dates for "who reports today"') and warns the filters are AND-ed. It also routes the agent to list_options/list_sub_industries for valid enum values. It stops short of naming an alternative tool for overlapping needs, but the context 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?

Annotations only declare readOnlyHint=true, but the description adds material behavior beyond that: it is authoritative because it reads live backend config (never stale), it is public with no auth required, it enumerates rejection behavior for the query-scoped kinds, and it warns about payload size for tickers/tickers_with_names. That is substantially more than the annotation provides.

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

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

Front-loaded with the key imperative and organized as a scannable bulleted catalog, with no filler sentences. It is nonetheless a very long block, which is largely forced by the 15 enum values but does weigh on context budget for a lookup 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?

An output schema exists, so return-value documentation is not required, and the description still notes the returned `options` field. Combined with the per-kind routing, conditional-parameter rules, and payload/auth notes, all information needed to call it correctly is present.

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

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

Although schema coverage is 100%, the description goes well beyond the schema's flat enum: it defines the semantic content of each kind (e.g. financial_items vs as_reported_items, managers-as-CIKs vs investor categories), states the conditional requirement of ticker/q/cik per kind, and prescribes how returned values must be passed downstream.

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

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

States a specific verb and resource — enumerate the valid values for a parameter from the backend — and immediately frames the tool as a pre-flight lookup rather than a data-fetch. An agent can distinguish it from siblings like list_realtime_events or generate_report_for_stock because the description says this tool supplies the values those tools consume.

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 instructs 'Call this BEFORE guessing a parameter value,' names which kinds require the ticker/q/cik qualifiers and that they refuse without it, and routes every kind to the consuming tool/parameter (e.g. event_types -> list_realtime_events, institutional_managers -> a report's institutional_ownership). This is exactly when/when-not/alternatives guidance.

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

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

Annotations only supply readOnlyHint=true, so the description carries the behavioral load and does so richly: 12h cache TTL, that an EMPTY list means a cold cache rather than no event, that older events live in the ontology card's persisted_in relation, auth requirements, and material-event side effects on report plans.

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

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

Front-loaded with the core purpose and the critical situate-first constraint, and the workflow, return semantics, and auth note follow in a logical order. It is dense and longer than typical, but nearly every sentence carries operational weight for a multi-step tool, with only mild 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?

Although an output schema exists, the description still clarifies the empty-list meaning, which is essential context. Combined with auth, cache lifetime, and the chained-call workflow, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so the schema documents all five params and a baseline 3 applies. The description nonetheless adds real meaning beyond the schema: why event_type is REQUIRED with no default (a default would answer a different question), and that tickers should always be set on follow-up calls to avoid re-pulling the whole cache.

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

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

States a specific verb and resource ('Pull live market events from the backend's Redis-backed cache') plus the distinguishing constraint (12h TTL). It clearly separates this tool from siblings like situate, get_event_ontology, and list_available_reports, which are named and given explicit roles.

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

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

Explicit routing: call situate FIRST, never call for a type situate marked expired, use list_options('event_types') for the enumeration, and follow up on related_events narrowed by tickers. It even states when an empty result is expected versus meaningful, leaving nothing to inference.

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

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

Annotations only declare readOnlyHint=true, but the description adds substantial behavioral context: the full return shape, that rows are the calling user's only, the metadata-not-label matching rule, null-until-landed metadata with a 10s-5min window, stale-row skip logic, HTTP 503 meaning, auth requirement and a 100/min rate limit. This goes well beyond what the annotation provides.

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

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

Well front-loaded (the 'check HERE FIRST' directive comes before all detail) and organized with bulleted sections. However, it is very long and devotes substantial space to the downstream run_saved_query replay procedure and metadata field anatomy, which strains the size appropriate for a one-parameter list 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?

Despite an output schema existing, the description fully describes the return payload and every metadata field, plus edge cases (503, stale rows, null placeholder, duplicate user_request). Nothing an agent needs to act on the results is missing.

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

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

Schema description coverage is 100% for the single `limit` parameter, so the schema already documents it fully. The description adds no additional semantics for `limit` (its 'max_rows' guidance applies to run_saved_query, not this tool). Baseline 3 is appropriate when the schema carries the parameter 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?

Opens with a specific verb+resource: 'List the data requests you have saved with `save_user_query`, newest first,' and explicitly names the sibling tool that created the rows. An agent can immediately distinguish this from explore_data_catalogue or run_saved_query.

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?

Unusually explicit routing: it tells the agent to 'check HERE FIRST, before running explore_data_catalogue,' and contrasts the saved-query replay (seconds) against a '~1-5 minute planning job.' It also names exact-repeat vs same-shape alternatives and their conditions, plus the caveat to confirm with the user when a row is merely topic-close.

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

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

Annotations only supply readOnlyHint=true; the description adds the meaningful scoping fact that results are limited to the authenticated user's jobs and that workflow schedules follow a 'wf:{email}:{workflow-name}' naming convention. No pagination or ordering behavior is disclosed, but the scoping context is genuine added value.

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

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

Front-loads the purpose, then the return shape, then the delete routing. The enumerated return-field list is somewhat redundant given an output schema exists, but the overall structure is tight and purposeful.

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

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

Given an output schema exists, the return-value enumeration is more than sufficient, and the read-only scoping plus the sibling routing cover what an agent needs to call it correctly. Nothing critical is missing.

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

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

The tool takes zero parameters, so the schema carries no semantics to compensate for. The description does not need to explain parameters, and the baseline for a no-param tool applies.

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

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

States a specific verb and resource ('List the caller's scheduled tasks') and clarifies the resource is cron jobs created via `schedule_task`. It distinguishes itself from the many other list_* and delete_* siblings clearly.

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

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

Explicitly routes the agent to `delete_scheduled_task` and tells it to use the `name` field as the key for removal, which is actionable usage guidance. It doesn't state when-not to use it or contrast with other listing tools, so it stops short of a 5.

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

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

The readOnlyHint annotation already covers the safety profile, and the description's added detail (result key name, distinctness, downstream linkage) is largely duplicated by the output schema. No edge-case or failure behavior (e.g., unknown sector values) is disclosed, but the annotation bar makes this adequate.

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

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

Two short sentences, front-loaded with the action and following with the return linkage; nothing is padded. The return-detail sentence is partly redundant with the output schema, which keeps it from being flawless.

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 one-parameter read tool with an output schema and a readOnlyHint, the definition covers what the tool does and how its output chains into list_realtime_events. Only the upstream call ordering (list_options first) is left implicit.

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

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

With a single parameter at 100% schema description coverage, the schema already explains that sectors are drawn from list_options("sectors"). The description only echoes the "one or more sectors" cardinality and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (list sub-industries) scoped to "one or more sectors", so the agent knows exactly what comes back. It does not explicitly contrast with the closest sibling, list_options, which is where sectors themselves come from, so it stops short of full sibling differentiation.

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

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

It gives the downstream purpose of the result (narrowing list_realtime_events(industry=[...])) and the schema notes sectors come from list_options("sectors"), which implies the workflow. However there is no explicit when/when-not guidance or statement of which tool to call first versus this one.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, which is somewhat confusing for a tool that only returns a link; the description resolves this by explaining the actual mutating actions (updating card, cancelling) happen in the external Stripe portal, not here. That is meaningful added context beyond the annotations. It doesn't cover auth requirements or rate limits, hence not a 5.

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

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

Two sentences, zero waste. The 'what it does' sentence comes first, followed by the routing condition. Every clause 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?

An output schema exists, so the return value (the portal link) need not be re-explained, and the description correctly focuses on purpose and routing. The only gap is the missing differentiation from upgrade_plan for plan-change requests.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; baseline is 4. No spurious argument discussion is present, which 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?

Specific verb+resource: 'Get a link to the Stripe billing portal', with concrete scope (view invoices, update card, cancel subscription). An agent immediately knows this returns a URL, not a modification. It does not distinguish itself from the sibling upgrade_plan, which is the one adjacent tool a user query could plausibly route to.

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

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

Explicit trigger condition: 'Use when the user asks to manage, change, or cancel their billing/subscription.' This is clear routing guidance, but it gives no exclusion against upgrade_plan, which is the obvious alternative for plan-change requests.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses mutating+authenticated nature, a 30-60 min asynchronous backend workflow, email notification on completion, a 5/hour per-user rate limit, and the initial return shape. These are exactly the operational facts an agent needs before invoking an async, rate-limited mutation.

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 tight sentences, front-loaded with the mutating/authenticated warning, then timing, rate limit, usage condition, and return. Every sentence earns its place with no 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 an output schema existing, the description still states the initial return ({"task_id": ..., "status": "PENDING"}) and covers the async lifecycle, rate limits, and prerequisites. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single required "symbol" parameter is fully documented (including an "IMCR" example) in the schema itself. The description adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb+resource ("Request onboarding of a NOT-yet-covered ticker") and scopes it to symbols not yet covered, immediately distinguishing it from report/listing siblings like list_options and generate_report_for_stock.

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 names the trigger condition ("Use only when a symbol is missing from list_options("tickers") / returns no data elsewhere") and routes the agent to the alternative check first. This is a textbook when-to-use rule.

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

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

Annotations are thin (readOnlyHint=false, destructiveHint=false), and the description carries the load well: it discloses a server-side rate limit of 10/hour per user and that execution is asynchronous with a PENDING task handle. It does not explain what happens to in-flight tasks or whether the submission itself is billable, but the behavioral picture is substantially better than the annotations alone.

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

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

Front-loaded with the core purpose and no filler sentences; the rate limit and async contract are stated compactly. The hard line breaks mid-sentence ('Rate-limited to 10/hour / per user server-side') hurt readability slightly but nothing is wasted.

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

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

Given an output schema exists, the description need not explain return fields, yet it usefully describes the async PENDING payload and the supported/not_supported lists up front. Combined with rate-limit and polling instructions, the only meaningful omission is any differentiation from `optimize_portfolio_default`.

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

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

Schema description coverage is 100%, so all three parameters (symbols, delivery, risk_tolerance) are already documented in the schema, including enum choices and default. The description only echoes the scoring/optimization role of `symbols` and adds no syntax or constraint detail beyond minItems that the schema already states.

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

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

States a specific verb+resource ('Build a risk-optimized portfolio') and enumerates the internal pipeline (multi-signal scoring, LLM curation, risk optimization). It distinguishes itself from most siblings, but never contrasts with the obvious sibling `optimize_portfolio_default`, which an agent could easily confuse it with.

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

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

Gives real operational guidance for the async flow ('Poll `task_id` with `get_task_status` until SUCCESS') and implies the input requirement ('non-empty list of tickers'). It does not say when to pick this over `optimize_portfolio_default`, so sibling selection is left to inference.

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

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

Annotations only supply readOnlyHint, and the description adds substantially beyond that: synchronous execution with no task id or polling, no auth required on a public endpoint, symbol validation against a covered universe, and status semantics (OK/SKIPPED/EMPTY) for degenerate inputs. This is real behavioral disclosure the structured fields do not carry.

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

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

Front-loaded with the purpose and the sibling disambiguation in the first two sentences, followed by only the constraints an agent needs. The layout is scannable and no sentence is filler.

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

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

For a synchronous, 2-parameter public endpoint, the description covers routing, execution model, auth, and error semantics; with an output schema present it need not have restated the return shape, so nothing required is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: symbols are validated against a covered universe, with unsupported tickers surfacing in `missing` and low-history tickers in `dropped`. It says nothing extra about `risk_tolerance`, which the schema already documents well.

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?

"Build a risk-optimized portfolio from a list of tickers" states a specific verb and resource, and the definition explicitly positions itself as "THE DEFAULT optimizer route" versus the `optimize_portfolio` sibling. An agent can distinguish the two tools without opening either schema.

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

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

It names the alternative explicitly ("Reach for `optimize_portfolio` instead only when you explicitly want the slower LLM-curated variant") and gives the exact condition that selects it. When-to-use and when-not-to-use are both spelled out.

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

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

Annotations only declare readOnlyHint, so the description carries most of the burden and does well: it explains the returned fields (`expected_move` units and semantics, `hist_move_mean`/`hist_move_n` scope) and the two partition buckets for no-data symbols. It doesn't mention latency, rate limits, or coverage limits on historical depth, keeping it short of a 5.

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

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

Front-loaded with the core purpose, then scoped precisely around output fields and edge cases in a tight block. Slightly dense with backticked field names, but every sentence carries information and there is no padding.

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

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

An output schema exists, so return-value explanation is optional, yet the description goes further by defining units, direction semantics, historical context fields, and edge-case buckets — everything an agent needs to interpret and route results correctly. No gaps remain for a single-parameter read 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?

Only one parameter with 100% schema description coverage, so the baseline is already high. The description adds value by clarifying that each symbol returns per-symbol results and what happens to symbols without scheduled earnings, which the schema alone does not convey.

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

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

States a specific verb (predict) and resource (post-earnings move) with the exact metric being returned (`expected_move` as a log return, size only, no direction). No sibling tool does anything similar — the closest neighbors are earnings announcements listing (`list_earnings_announcements`) and generic stock data, and this is clearly distinguishable from both.

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

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

Usage context is implied by naming the input (symbols) and outputs, but there is no explicit 'use this when vs. list_earnings_announcements' guidance or exclusions. The description covers behavior thoroughly but never tells the agent when this is the right tool over 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?

Annotations only mark it non-read-only and non-destructive; the description carries the real behavioral load: cursor semantics ('only events published AFTER registration are ever delivered'), a 30 registrations/hour rate limit, the ~2,000-entry retention window and what happens to an idle subscription, plus auth via the MCP client's bearer. That is well beyond what the annotations disclose.

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

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

Front-loads the verb, resource and return value in a single bolded opening sentence, then layers usage, return shape, vocabulary and limits. It is long and slightly repetitive — it restates list_options("event_types") guidance already present in the schema — but nearly every sentence adds operational value rather than padding.

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

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

Although an output schema exists, the description still supplies what matters for correct invocation: the return shape, the persistence of subscription_id (no list endpoint), which tools consume it, auth, rate limit, and the resumption/retention caveat. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds usable semantics: empty body listens to everything, the vocabulary rules (report_plan as 'stream full research as it is minted', a family for 'everything earnings-related', symbols for a watchlist), and the filter-normalisation behaviour (topics lower-cased, symbols upper-cased, duplicates dropped).

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

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

States a specific verb+resource ('Save a realtime-event filter server-side') and the artifact produced (`subscription_id`), plus the underlying endpoint. It explicitly differentiates itself from the siblings stream_events, stream_event_subscription and delete_event_subscription, so an agent can pick it without opening another schema.

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

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

Gives an explicit alternative and the condition that selects it: 'For a live-streaming ask, the default is a dashboard... that loops stream_events itself — see stream_events. Register a subscription when the user wants a saved filter that resumes across sessions.' When-to-use and when-not-to-use are both stated.

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

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

Annotations only declare readOnlyHint=true, and the description goes well beyond that: no planning/polling, exempt from the 20/hour exploration budget, per-token isolation (one failure doesn't stop others), 403 = dead row vs 422 = mapping failure, truncation via row_count/truncated, and prompt-only fills can DRIFT. It also states SQL is never returned and provenance columns may appear. This is unusually rich behavioral disclosure. However, much of it is arguably operational instruction for the caller rather than intrinsic tool behavior, and return-shape detail overlaps the existing output schema.

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

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

Front-loaded with the core purpose before any elaboration, and each subsequent paragraph covers a distinct concern (tokens/values, prompt, max_rows, return shape, provenance, error handling). It is long and dense, and the return-shape and provenance passages drift into guidance that could be trimmed, but almost every sentence carries actionable 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?

For a 4-param tool with an output schema, no behavioral or routing gap remains: the exact-vs-re-aimed distinction, fallback chain, error taxonomy, truncation signaling, staleness expectation, and downstream trace_data_sources handoff are all covered. An agent could call this correctly on the first attempt from the description alone.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantics beyond the schema: the same `values` dict must be passed to every token, entity-set slots take {"id","name"} lists with server-side name resolution, unused keys surface as `ignored_values`, and slots fall back to `prompt` then the saved default (`defaulted_parameters`). `max_rows` guidance ("PASS IT ON EVERY REPLAY") is also operational context the schema lacks.

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?

Opens with a specific verb+resource ("Re-run a saved request's queries against live data") and immediately distinguishes exact replay from re-aimed replay. It names the sibling producing the input (list_saved_queries), the one it complements (save_user_query), and the ones it competes with (explore_data_catalogue, get_signed_sql_drilldown).

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

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

Explicit routing: "Use this INSTEAD of explore_data_catalogue whenever a saved row already covers the question," and "For a token that came from a get_company_event_web node ... use get_signed_sql_drilldown." It also states when to prefer `values` over `prompt` ("keep prompt for what you cannot type") and gives explicit fallback paths on 422/403.

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

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

Goes well beyond the annotations: owner-scoping, absence of upsert (duplicate saves create a second row), opaque-ciphertext tokens that fail with 403 if not server-minted, auth requirement, and a 100/min rate limit. It also explains the async placeholder authoring and the PENDING vs NOT_DISPATCHED states, which materially shapes call timing.

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?

Well front-loaded and organized with THE POINT / WHEN TO CALL headers, and nearly every sentence carries information. It is long, but the async-state and token-safety detail justify most of the length; a few clauses could still be tightened.

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

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

Covers the full lifecycle an agent needs: what to save, when, what the backend does next, what the placeholder enables, duplicate handling, and the failure/async states. Nothing necessary for a correct call or a correct follow-up decision is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: tokens are opaque server-minted ciphertext that must pass through exactly and never be written or guessed, and user_request is the row's only human-readable label so it should be specific.

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

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

States a specific verb (save) and resource (the queries an exploration planned) plus the outcome (exact or re-aimed replay). It clearly distinguishes itself from explore_data_catalogue, run_saved_query, schedule_task, and list_saved_queries by name.

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?

An explicit WHEN TO CALL block says to offer it once an exploration is done and shown, save on confirmation, and explicitly says NOT to save every exploration or one-offs. It also routes to alternatives (list_saved_queries before saving, delete_saved_query for stale rows).

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

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

Annotations only establish readOnly=false/idempotent=true/destructive=false; the description goes well beyond that, disclosing the UPSERT-with-no-history overwrite risk, the async return contract, the 404-on-expiry and 422 rejection modes, the 'keeping the previously compiled blueprint' warning semantics, downstream rendering effects, auth, and a rate limit. (Minor tension worth noting: an overwrite with no history is close to the line for `destructiveHint: false`, but the author surfaces the risk explicitly rather than hiding it.)

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?

Well front-loaded (purpose, then the two call paths) and sectioned into digestible blocks, with no filler sentences. It is long, and the 'WHAT CHANGES AFTERWARDS' paragraph could be tightened, but the length is driven by genuinely useful behavioral detail rather than padding.

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

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

For a five-parameter upsert with async execution and an existing output schema, the description covers call paths, error modes, the poll-then-read result contract, and downstream effects. An agent has everything needed to call it correctly without opening other tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: which parameters belong to which call path, that `template`/`template_type`/`anchor` are taken from the draft on the signed-off path, that `anchor` is required only for `add_on`, and that markdown input is a 422. It stops short of full parameter-level detail only because the schema already carries 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 first sentence names the exact verb+resource (save the user's PDF format) and the cardinality rule (one template per account, applied automatically to every PDF the backend renders). It is immediately distinguishable from `draft_user_template`, `update_user_template`, `get_user_template`, and `delete_user_template`, all of which appear as siblings.

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

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

It gives explicit routing: SIGNED-OFF (normal) vs DIRECT (only when skipping previews), names the required parameters for each path, and states the exclusions. It also says to call `get_user_template` first and confirm before overwriting, and to use `update_user_template` to change an existing format afterwards — when-to-use, when-not, and alternatives are all covered.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description far exceeds that bar by disclosing the endpoint allowlist, 422 rejection at save time, which endpoints are EXPENSIVE with a max-2 cap, cron field restrictions for expensive runs, the 10-active-schedule per-user limit, and the 201/200 upsert status semantics.

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

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

Front-loaded with purpose and usage before the detail, and the bulk of the length is the endpoint allowlist which genuinely earns its place. It is nevertheless dense and reads more like a manual than a description, with some list entries (e.g. the create-full-report override keys) verbose enough to compress.

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, high-stakes scheduling tool with nested-ish step objects, an output schema present, and no destructive annotation, the description covers everything an agent needs: eligibility, endpoint allowlist, constraints, limits, and upsert identity. Return values are covered by the output schema and only briefly echoed.

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

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

Even at 100% schema coverage, the description adds vocabulary the schema cannot encode: the allowlisted fetch endpoint names, which take JSON-body vs scalar query params, which are expensive, and the shape/semantics of `steps` (first must be a fetch, transform instruction applies to all prior results, last step is delivered). This is substantive meaning beyond the schema.

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

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

States a specific verb+resource+mechanism: 'Save a multi-step WORKFLOW (upsert by `name`) and attach a recurring cron schedule for its delivery.' It also distinguishes itself from the direct-call alternative and from siblings like delete_scheduled_task/list_scheduled_tasks by naming the upsert key semantics.

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

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

Explicit when-to-use ('user wants a sequence of platform calls delivered ON A SCHEDULE / repeatedly') with a concrete example, and an explicit when-not ('For a ONE-OFF request, call the corresponding tools directly instead'). Nothing is left to inference.

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

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

Adds two traits the annotations do not convey: a server-side rate limit of 10/hour per user and asynchronous execution returning a task id that must be polled. These are exactly the operational facts an agent needs to avoid retry storms and to correctly sequence calls.

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

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

Four short blocks: what it filters, how to obtain valid values, the rate limit, and the async contract. The purpose is front-loaded and every line carries distinct operational value with no filler.

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

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

Covers prerequisites, rate limiting, and the async/polling lifecycle, and an output schema exists so return-shape explanation is unnecessary. For an eight-parameter screener, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and each parameter already names its source list tool, so the description's opening enumeration mostly restates the schema. It adds no threshold syntax or value-format guidance beyond what the schema provides, making the baseline 3 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?

States a specific verb (screen) and resource (stocks) and enumerates the eight filter dimensions it accepts, which cleanly separates it from adjacent tools like get_stock_picks or generate_report_for_stock. An agent can tell what this tool does without opening the schema.

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

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

Gives a concrete prerequisite workflow: discover valid filter values via the list tools named in each parameter description before guessing, and poll the returned task with get_task_status until SUCCESS. It lacks any explicit when-not or comparison against sibling screening/picks tools, so it stops short of a 5.

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

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

Annotations only carry readOnlyHint=true, and the description adds a great deal beyond that: synchronous execution, keyword (never LLM) matching, cache TTL/expiry semantics, sync=false returning a task_id to poll, and degraded=true meaning a source was unavailable. It also defines the operational contract of plan/skip/suggest/guidance, which the annotations cannot express.

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

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

Front-loaded with the single most important routing fact ('THE FIRST CALL') and organized under clear headers with inline examples. It is long and dense, and some prose re-describes output fields that the output schema already defines, but for a meta-tool of this complexity nearly every sentence carries operational weight.

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

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

An output schema exists, yet the description supplies the interpretation layer an agent actually needs: what plan[], skip[], suggest[], and guidance[] mean, how to read an 'overdue' follower, and the degraded path. Nothing required to call it or act on its response is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning with worked invocations showing no-symbols = whole market and how a question naming a family vs. a specific type changes plan order. It reinforces that question must be passed verbatim, which matters for the keyword matcher.

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?

Opening line states a specific verb and resource: it reports what is happening now for the market or named symbols AND returns a ready-made plan of tool calls. It explicitly distinguishes itself from siblings (explore_data_catalogue, list_realtime_events, report tools) and brands itself as 'THE FIRST CALL', so an agent can route to it without opening a schema.

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

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

Gives explicit when-to-use triggers ('catch me up', 'anything before earnings?') and explicit exclusions ('Skip this tool ONLY for pure enumeration (list_options), an explicit get_latest_report, or a metric-history question'). It names the alternative tool for each exclusion, leaving nothing to inference.

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

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

Annotations only declare readOnlyHint; the description goes much further: bounded read semantics, no server-side state, cursor advances on heartbeats so empty events + moved cursor is normal, closed means server ended the stream and do-not-reconnect, auth required. Does not contradict annotations. Slightly less than 5 because some operational detail (rate limits, exact 422 shape) is only partially covered.

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?

Much of the content is valuable, but structure is dense: multiple distinct topics (delivery pattern, cursor loop, topics, symbols, closed) are packed with bold headers, inner bullet lists, and parentheticals. It works but is not front-loaded in the sense of a single tight opening; the caller must read the full document to extract the loop protocol.

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 complexity (bounded SSE read with cursor, 5 optional params, output schema present) the description covers consumption guidance, loop semantics, alternatives, and error behavior. Since an output schema exists, it does not over-explain return shapes while still calling out key fields (events, cursor, closed, elapsed_seconds).

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. Description adds meaningful semantics beyond schema descriptions: topics can be an event type, a family, or stream-only 'report_plan'; symbols note that 13f_* filer events carry CIK; cursor advances on heartbeats; unknown topic -> 422 with allowed lists. That is real added meaning over schema text.

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

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

States a specific verb+resource: 'Listen for realtime events as they publish — a bounded read of the backend's ad-hoc SSE stream (GET /events)'. Names the sibling alternatives and differentiates: 'For a subscription that resumes by itself, use register_event_subscription + stream_event_subscription instead', and references list_realtime_events as the polling counterpart.

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

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

Explicit 'DEFAULT DELIVERY' section tells the agent what to do (build a live dashboard, run the loop) vs when to stream into chat only. Names explicit alternatives ('use register_event_subscription + stream_event_subscription instead'), and specifies cursor handling per call. This is a rare example of explicitly covering when/why.

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

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

Annotations only declare readOnlyHint=true; the description carries the real behavioral load — server-side cursor persistence across connections, the 55 s wait cap, exactly-once/no-replay semantics, closed reasons, and the deliberately ambiguous 404. It also states the auth requirement.

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

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

Front-loaded with the core contract and organized into scannable paragraphs, but it runs long and the 'Acting on what arrives' section drifts into downstream-tool guidance (get_latest_report timing, generate_report_for_stock fallback) that belongs closer to those tools.

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 resumable streaming read with a 4-param schema, the description covers return shape, timeout behavior, cursor persistence, terminal closed states, error semantics, and auth. Even though an output schema exists, nothing an agent needs to call or loop this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: cursor is an ephemeral per-connection override that is NOT persisted, while the saved position resumes automatically without passing it. That interplay is the key semantic and it is spelled out.

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