Flexreport Finance

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

Beyond the readOnlyHint annotation, the description discloses important behavior: the call is synchronous, returns rows directly, and can be very token-expensive if as-filed tables are pulled without line_items. It also warns about newest-first ordering, duplicate netIncome rows across statements, stale YoY data, auth requirements, and error semantics.

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

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

The description is long, but it is front-loaded and clearly structured with headings for tables, line_items, row shape, stale YoY, citation, and access constraints. Nearly every section earns its place, though some prose around the token-cost warning and citation workflow could 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?

Given the tool's complexity, multiple financial tables, high token-cost risk, and output schema, the description is complete enough for an agent to call it correctly. It covers routing, table selection, filtering, return ordering, citation, stale data, auth, and error handling.

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 meaningful operational semantics for financial_type values, line_items usage, and the stale YoY caveat. It explains which tables are standardized versus as-filed and how line_items should be chosen, though it adds little beyond the schema for the limit parameter.

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

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

The description states a specific verb and resource: reading a company's EDGAR financial statements, including revenue, EPS, margins, and cash flow by quarter or year. It also distinguishes the tool from siblings by explicitly saying to prefer it over explore_data_catalogue for one company's reported statements and by linking its use to situate's read_by relation cards.

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 guidance: use this for one company's reported statements, especially when a relation card lists it in read_by after a table refresh. It names the main alternative, explore_data_catalogue, explains why this tool is preferable, and adds edge-case guidance for non-filers, 404s, and 422s.

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: 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 adds the critical scope of destruction ('removes only the cron schedule; the saved workflow definition is kept'), the error condition if no such task exists, and the exact success payload. This is behavior an agent cannot infer from the annotations.

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

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

Front-loaded with the core action and selector, then scoped pitfalls and return format. Efficient overall, though the middle sentence is slightly convoluted with nested parentheticals that could 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?

For a destructive single-parameter tool with annotations and an output schema, the description covers purpose, side effects, preservation semantics, recovery paths, and error/return 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% and the schema already documents the expected 'wf:{email}:{workflow-name}' format and warns against the bare workflow name. The description adds complementary meaning by explaining that for workflow schedules the value is what schedule_task returned as task_name, tying the parameter to its producer.

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 a scheduled task (cron job) by its name'), and immediately clarifies the key selector semantics. An agent can distinguish this from the other delete_* siblings and from schedule_task.

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 describes what happens in each case (workflow schedule vs 'ds:' dataset schedule), what is preserved, and how to resume each ('re-saving it via schedule_task', 're-save via save_user_dataset'), even naming delete_user_data_feed as the tool that removes the dataset itself. Strong when/when-not and alternative routing.

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

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

Annotations already declare destructive=true and idempotent=true, and the description corroborates rather than contradicts them: 'can't be undone' matches destructive, and 'every step is safe to repeat / call again with the same name' matches idempotent. It further adds error semantics (404 = no such dataset; 503 = partial failure with a retry recipe) and the auth requirement, which annotations do not cover.

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 destructive scope before the alternative, then returns, then errors, then auth — a logical order with no filler. Every sentence carries actionable content; the return-key list is slightly redundant against the output schema but is compact enough not to count as 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?

For a destructive single-parameter tool it covers the full decision surface: what gets destroyed, irreversibility, confirmation duty, the non-destructive alternative, failure modes with recovery, and auth. The output schema exists, yet the inline return summary still helps the agent interpret partial-failure results (e.g., files_deleted vs saved_query_deleted).

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 parameter, and the schema already explains that dataset_name is 'the dataset's `name`, as list_user_datasets shows it.' The description adds only the confirmation-time instruction to name the dataset, so the baseline 3 is appropriate — the schema does the heavy lifting here.

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

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

States a specific verb+resource ('Delete one of the user's own datasets completely') and enumerates exactly what is destroyed: schedule, built files, latest_url link, and saved query. It also names the sibling it is not (delete_scheduled_task) and the exact argument form that routes there, so an agent can distinguish it from the other delete_* 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?

Explicit when-to-use (full dataset removal) and when-not (to only stop builds and keep files, use delete_scheduled_task("ds:{email}:{name}")). It also adds a required procedural precondition — confirm with the user first, naming the dataset — which is guidance beyond mere routing.

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

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

Annotations 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, so the description carries most of the burden and does so richly: a hard rate limit of 3 calls/week including failed calls, 12-hour presigned link validity, document feeds collapsing to one row per document, published_at as-of semantics, `notes` reporting omissions, and OAuth/quota side effects. This is far beyond what structured fields convey.

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

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

The text is long, but it is front-loaded with purpose and the critical rate limit, then organized into labeled sections (Sizing, Shaping, Returns) with a bulleted constraint list. For a 10-parameter tool with a hard weekly quota, nearly every sentence earns its place; the density is justified rather than padded.

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

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

Despite no output schema, the description spells out the return shape ({dataset, start_date, end_date, bulk_download, latest_file_version, shape, rows, row_count, truncated, published_at, notes}), what `notes` contains, and how to surface it. Auth requirements, rate limits, and quota accounting are all covered, leaving nothing an agent needs to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all 10 parameters. The description still adds meaning the schema doesn't: `date_field` determines what dates filter on, include_page_text is only for page-level reads narrowed by symbols/document_urls, bulk_download is full-history only, and symbols is impossible for download_links feeds. It goes beyond the baseline 3 without fully compensating for anything missing, since the schema already covers 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?

The description opens with a specific verb+resource: 'Read one of Flexreport's versioned daily data feeds by date.' It immediately names list_options("data_feeds") as the source of valid feeds and explicitly contrasts itself with 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?

Usage is fully routed: use this over explore_data_catalogue when a feed answers a date/date-range ask, and keep to explore_data_catalogue for open-ended analysis ('why did X move'). It also gives sizing heuristics (week ahead for predictions, latest completed date for 'how did it do', one business day for documents) and explicit anti-patterns (never test-fire, never poll).

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 quantifies output size (~120K chars for 5 pages, ~750K for 20), discloses the SSRF guard (host must end in "amazonaws.com" and contain "s3", otherwise a 400), notes the fetch is server-side, and states OAuth is auto-attached. No output schema exists, so the explicit return shape {"file_name", "media_type", "report"} earns further credit.

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-and-resource plus the fallback role, then layers conditions, size warnings, constraints, and return shape in a sensible order. Slightly padded by repeating the S3 host rule already present in the schema, and the paragraph break mid-thought about size is a little awkward.

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 two-parameter read tool with no output schema, the description covers selection criteria, size/shape of the result, error behavior, auth handling, and the return payload — everything an agent needs to decide and call correctly. 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%, so both parameters are already documented in the schema, including the same S3 host constraint. The description restates the URL restriction but adds no new semantics for file_name (e.g., whether it affects the returned file_name field) or for URL edge cases. Baseline 3 is appropriate 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 a presigned S3 PDF URL server-side and return the document as base64") and immediately frames its role as "The FALLBACK for reading a report." That framing distinguishes it from both get_latest_report (which only returns the URL) and a plain client-side HTTP fetch.

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 preferred path (fetching the link yourself is "the normal way to read the PDF") and states the exact conditions that select this tool: the client cannot reach the link but can run code to decode base64. It even adds a disqualifying condition — the payload is useless to a model that cannot decode 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=true, so the description carries the real weight: it discloses asynchronous execution, a 45s–4min latency, the exact SUCCESS payload (validation_status, candidates, query_token), the REJECTED relay path, and a 20-drafts-per-hour rate limit with OAuth auth. It also flags two non-obvious traps — a `published_at` column blocks saving, and `query_token` must never be shown to the user.

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 numbered research-first protocol is well front-loaded and each step is actionable, but the description runs to roughly five blocks and repeats itself — 'ask for ONE candidate when variants don't matter' appears both in step 5 and again in the refine paragraph. The multi-sentence research_url digression, while behaviorally useful, sits awkwardly inside a tool definition rather than a linked doc.

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 high-complexity async planner tool, nothing an agent needs is missing: trigger conditions, pre-work, async polling, full result contract, save handoff, refinement loop, and failure handling are all covered, even though an output schema exists and would have excused omitting the return shape.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond it by explaining when `target_format` must be supplied ('always for rss/atom') and what rss/atom does to planner shaping, and by insisting `request` be re-sent identically when refining with `previous_draft_id` + `feedback`. `sample_rows` is left entirely to the schema, which is fine.

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

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

The description states a specific verb and artifact: 'Drafts the user's OWN dataset — a table built from Flexreport data on a schedule and published as a file (parquet, csv, ... or an rss/atom feed) behind a fixed link.' It explicitly separates itself from siblings download_dataset, explore_data_catalogue, save_user_dataset and schedule_task, so an agent can route 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?

It gives concrete trigger phrases ('build me a daily file of...', 'an RSS feed of...') and a hard exclusion ('never substitute schedule_task, an emailed workflow or a one-off file'), plus a carve-out that plain data feeds skip the research-first protocol. The two-step lifecycle (draft here, save_user_dataset schedules it) and refine path (same request + previous_draft_id + feedback) are 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=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?

Beyond the sparse annotations, the description discloses the async task model, PENDING/SUCCESS polling with get_task_status, expected runtime, the 20/hour rate limit, dashboard-only delivery, REJECTED validation behavior, and the full result shape including provenance columns. It also explains that rows are not sampled and that query_token is only for save_user_query.

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

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

The description is front-loaded and sectioned with `===>` markers, so its navigation is clear. However, it is extremely long for a one-parameter tool and repeats the save-offer and event-driven guidance multiple times, creating redundancy that makes it harder to scan as a tool definition.

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

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

Given the tool's complexity as an asynchronous query-planning job, the description is complete: it covers alternatives, prerequisites, polling, runtime, rate limits, output shape, validation failures, provenance, and follow-up save behavior. The output schema exists, but the description still supplies enough operational context to call and interpret the tool correctly.

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

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

The tool has one parameter, `query`, and the input schema already provides 100% coverage with an example. The description adds useful framing — that it should be an open-ended natural-language question and that event-driven queries should name refreshed relations — but it does not materially document a typed or structured parameter beyond what the schema already supplies.

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

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

The description states a specific verb and resource: it plans and runs open-ended data-exploration queries against the data catalogue and returns raw result sets for dashboard charts/tables. It clearly distinguishes itself from company_financials, list_options, explore_data_coverage, generate_research_report, and 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?

It gives explicit when-to-use and when-not-to-use guidance: use this for exploratory data questions, use company_financials for direct company statement reads, list_options for enumeration, explore_data_coverage for counts, run_saved_query when a saved shape fits, and situate/get_event_ontology for event-driven questions. It also specifies sequencing with generate_research_report and when to offer save_user_query.

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 declare readOnlyHint=false / destructiveHint=false; the description carries the rest and then some — the note REPLACES the symbol's report and triggers `report_plan` subscriber notifications, the call is asynchronous returning a task_id that must be polled to SUCCESS, latency is minutes, a 422 is returned for shaped requests without user_override, unknown keys are ignored, and OAuth auth is required.

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

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

The two opening sentences are well front-loaded, but the body runs ~600 words with repetition: "a few minutes" appears three times, the report-replacement consequence is stated twice, and the explore/ideate/overlay detour is a full alternative workflow argued at length. Capped section headers help navigation but the definition is over-stuffed for an 11-param 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 everything an agent needs for a complex async mutation: preconditions, the replacement side effect, the exact return shape and how to read it (result[ticker][task_id] → get_task_status → get_latest_report for the PDF, not the task result), the subscription shortcut, auth, and the fact that event context is server-owned with no editorial fields. The output schema is also present, so return values need no further prose.

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 each parameter description already names its `list_options` vocabulary, so much of the parameter discussion restates structured data. The genuinely additive part is the ontology-driven derivation (earnings family → financial_items + estimate_items; institutional_ownership → CIK from fetch.cik; analyst_activity → estimate_items + ratios) and the auto-set user_override rule, which an agent could not infer from 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: "Write a NEW research note for ONE ticker, now (a few minutes)." It explicitly distinguishes itself from both relevant siblings — `get_latest_report` (the cached fast path) and `generate_research_report` (open-ended/multi-company) — 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?

Gives hard preconditions ("Never the first call", "call it ONLY after get_latest_report returned the ticker with `stale: true` or in `missing`") plus an exclusion ("Never fan it out across a list of names"). For custom mode it names the preferred alternative workflow (explore → ideate → overlay) and reserves CUSTOM for the case where the user explicitly wants the Flexreport note written.

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, so the description carries real weight and delivers: synchronous and cheap, requires OAuth bearer, rate-limited 60/min, node/edge/market_context caps, and that a missing edge is not evidence of unrelatedness. It also discloses the degraded-empty-web state and the `at`-is-publish-time trap, which no annotation or schema 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?

Content is largely load-bearing, but it is very long with ALL-CAPS emphasis, three separate `===>` blocks, and the get_event_ontology pairing stated twice (opening and closing) — the reader must scan past duplicated guidance. The output shape is front-loaded reasonably, but the length is closer to a manual than a tool 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 graph-returning tool it covers nodes, edges, cause grades, market_context, and the chaining procedure, and it even documents semantics of the return despite an output schema existing. Nothing an agent needs in order to call it correctly and interpret 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 already 100%, so the barrier is low, but the description adds genuine meaning: `window_days` should be widened before declaring a snapshot move unexplained, and `max_nodes` beyond the cap truncates edges (~3 same_chain_run, ~3 co_occurrence) — a consequence the schema's "Node cap (default 40, max 200)" does not convey. Symbol semantics add little beyond the schema's own "Covered ticker" example.

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 connected event web for one company — and immediately contrasts it with `situate` (deduped, newest-per-type) and `get_company_snapshot` (the WHAT vs the WHY). An agent can distinguish it from every plausible 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?

Explicit when-to-use with concrete user phrasings ("catch me up on WM", "why is the thesis negative?"), an explicit alternative (`situate` first, this for the raw graph or a different window), and explicit when-NOT (don't use it to state current position; don't quote headlines as content). Routing conditions are stated, not implied.

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

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

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; the description adds substantial behavior beyond that — cheap, synchronous, public, symbol-INDEPENDENT, cacheable, ~230 KB unfiltered vs ~5-10 KB filtered, a 12h realtime_cache_ttl_hours boundary, and the meaning of degraded=true ('the table has not been built yet, not that the type is unknown'). It also discloses the provenance honesty axis (mined | declared | pg_depend | static:tasks.py | beat | catalogue | data_model) and warns that `informs` is the weakest edge and must not be presented as lineage.

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 visually structured with `===>` markers and a clear filter block, but roughly half the text enumerates what an event_type card and relation card carry (about, persisted_in, entails.<layer>, precedes, episodes, deepened_by, informs, evidence), which duplicates return-value documentation that an output schema already covers. Several paragraphs restate the same caching/requisite point, so the length is not fully earned.

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-required-parameter, four-filter ontology reader with an output schema and a readOnly annotation, the description covers everything an agent needs: what it returns, when to prefer `situate`, cost/size expectations, cacheability, and the freshness comparison rule that motivates the tool's existence. No material gap remains for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents each filter, but the description adds a real constraint absent from the schema: 'Pass exactly ONE filter for a small card' and the no-filter case ('the whole class graph, 21 event types, ~300 relations'). It also supplies the join contract with `get_company_event_web` (pass a node's `type` as event_type, its `relation` as relation, its `family` as family), which meaningfully disambiguates the string values.

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 with a precise framing: 'the platform's event ONTOLOGY — what an event TYPE means for everything else', and explicitly separates itself from `situate` and `get_company_event_web` by describing which slice each returns. An agent can distinguish this from all ~55 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?

Explicit when-to-use ('Call it FIRST on any real-time, single-company, or event-driven request', 'REQUISITE for... BEFORE aiming explore_data_catalogue or generate_report_for_stock'), explicit alternative ('for a named company, situate(symbols=[...]) ... start there'), and explicit when-to-call-directly (FULL card, relation card, whole family, unfiltered graph). Also names a downstream decision rule: use intraday tools when next_run_at is after the event.

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 substantial context beyond that: it FETCHES and never builds, returns in seconds, rate limit of 500/hour, OAuth bearer required, and the URL is a presigned link valid ~6h after which a fresh call is required. It also warns never to edit or construct a URL, which prevents a realistic failure mode.

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 decisive 'USE THIS BY DEFAULT' line, then triggers, then exclusions, then response semantics. It is long, but nearly every block maps to a real decision (stale flag handling, PDF access, list splitting). Minor redundancy: the inline JSON response shape overlaps with the existing output schema.

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

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

Covers the full lifecycle an agent must handle: symbol partitioning into `result`/`missing`, stale-true/false/null handling with a recommended next action, 6h link expiry, download-and-read vs hand-the-link distinction, and the >100-symbol split rule. Nothing needed 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% and the single `symbols` parameter is already documented (uppercased, de-duplicated, max 100), so the baseline is 3. The description adds operational meaning with 'Split a list longer than 100 symbols across calls', which tells the agent how to recover from the documented 413 rather than just what the limit is.

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 ('Get the latest Flexreport research report(s) for one or more tickers') and immediately differentiates itself from siblings: it is the default fetch path, not `generate_report_for_stock`, `generate_research_report`, `explore_data_catalogue`, or `list_available_reports`. 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?

Gives explicit when-to-use triggers ('the report', 'research', 'the latest research', 'analysis', 'a writeup', 'the PDF'), explicit when-NOT (open-ended/exploratory questions go to `explore_data_catalogue`; bespoke writeups go to template tooling), and ordering guidance ('ALWAYS call this before `generate_report_for_stock`'). This is as close to a routing decision table as a description gets.

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 readOnlyHint, it discloses the response shape (`format`/`count`/`rows`, never the SQL), the `is_new_record` flagging for contextual drilldowns, `_source_*` provenance columns plus a `sources` block with grain/traceability, the 403 and 422 meanings, and the fan-out stall risk. That is far more than the annotation carries.

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 and the token source before routing, errors, and provenance. The all-caps citation block and the saved-row repetition are a bit heavy, but every paragraph carries information an agent needs to call this correctly.

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

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

Even with an output schema present, it explains the return envelope, provenance semantics, and truncation. Combined with auth, 403/422 handling and the downstream trace_data_sources handoff, nothing material about invoking this tool is left unanswered.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning by saying the URL or just its `t` is accepted and unwrapped, that `values`/`prompt` only apply to placeholder-twin tokens and that substituted `parameters` should be echoed, and that `max_rows` should be used on fan-out drilldowns.

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: fetching the rows behind an event-web drilldown from a server-minted query token. It immediately separates itself from siblings by naming run_saved_query (saved-request tokens) and get_company_event_web (the source of signed_query_url).

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: use this when the node carries `signed_query_url`, use `run_saved_query` for saved-row tokens, use `get_document_section` to open a cited speaker turn. It also states when-not behavior (403 = do not retry with an altered token; not-authenticated = sign in again).

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?

Although annotations already declare readOnlyHint, the description adds substantial behavioral context beyond them: the exact status values (PENDING, SUCCESS, FAILURE, RETRY), when result is populated, and the critical >8 MB failure mode with remediation advice. This is exactly the kind of operational detail an agent needs to avoid misusing the tool.

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

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

The description is front-loaded with purpose, then return shape, then a critical caveat, which is a logical structure. The parenthetical list of async job names is somewhat lengthy, but it serves to identify applicable tools and every sentence provides 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?

There is no output schema, yet the description fully specifies the return object keys, status enum, result population condition, and the error behavior when results exceed ~8 MB. Nothing essential for correct invocation and result interpretation 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 single task_id parameter has 100% schema description coverage ('The task_id an async tool returned'), so the schema already carries the parameter meaning. The description adds return-shape context but no additional parameter syntax or constraints, making 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?

The description opens with a specific verb and resource ('Poll the status of an async job') and enumerates the sibling async generators it applies to (generate_report_for_stock, screen_stocks, etc.). An agent can immediately distinguish it from those generator tools and from synchronous data retrieval tools.

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

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

It clearly indicates this is for polling an async job's status, and gives explicit handling guidance for the oversized-result case ('re-run the job scoped narrower ... instead of polling it again'). It doesn't explicitly say to call this only after an async tool returns a task_id, but that is strongly implied.

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

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

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?

Beyond readOnlyHint, the description discloses parsing behavior for json/jsonl/csv/tsv/xml/rss/atom, rss/atom row shape, research_url handling, unsupported parquet/xlsx behavior, size-cap errors, return fields, and auth requirements. These are meaningful operational details an agent needs before invoking the tool.

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

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

The description is front-loaded with its core purpose and alternative, then layers in format and error behavior. It is longer than a simple read tool needs, but the added detail is mostly functional rather than redundant.

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

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

There is no output schema, but the description compensates by listing the return fields and explaining special cases such as rss/atom rows, unsupported formats, and oversized files. Given the tool's complexity and read-only annotation, the definition is complete enough for correct agent use.

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 in the input schema. The description reinforces version behavior and dataset-name usage but does not add substantial syntax or format details beyond the schema.

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

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

The description states a specific verb and resource: reading the rows of a saved dataset as published, including latest_url or a dated version. It explicitly distinguishes this from run_saved_query, which re-runs live SQL and produces different rows without review.

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 guidance: use this tool to read the published file, never replay the saved query instead, give latest_url for parquet/xlsx, and use get_latest_report as the user's route for reports. The alternatives and exclusions are 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?

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 already declare readOnlyHint=true, and the description adds real context beyond them: it is cheap, it requires no auth, it returns a single boolean, and an unknown exchange code raises an error rather than defaulting. It doesn't cover edge cases like holidays or stale data, so not a full 5, but the disclosure is well above the annotation baseline.

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

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

Front-loads the purpose, then return value, then error behavior, then routing. Every sentence carries distinct information with no repetition of the schema beyond the error rule.

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?

Output schema exists so return format needn't be re-explained, annotations cover safety, schema covers the parameter. The description fills the remaining gaps: cost model, auth, error semantics, 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 coverage is already 100%, so the baseline is 3, but the description adds meaning the schema cannot: it points to `get_company_snapshot`'s `exchange` field as a compatible source for the value, which directly answers where the parameter comes from.

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 frames the tool's role as a 'cheap routing helper', which immediately distinguishes it from the market-data siblings. An agent knows exactly what it 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?

Explicitly routes the agent: when CLOSED use `get_aftermarket_data`, when OPEN use `detect_intraday_outlier_jumps`, and when the exchange is unknown use `get_company_snapshot` to obtain the code. This is textbook when-to-use/when-to-use-something-else guidance naming concrete alternatives.

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

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

The description goes far beyond basic functionality, providing deep behavioral context. It defines the meaning of `fresh: true` vs `fresh: false` and describes the resulting behavior (e.g., recommending a wait or triggering `generate_report_for_stock`). It also mentions cost constraints (500/hour) and synchronous behavior.

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

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

While extensive, the structure is highly efficient and appropriately sized for the tool's complexity. The use of bold headers (e.g., 'TWO WAYS IN') and categorized bullet points ensures maximum readability and zero-waste information delivery.

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 definition is extremely complete for a high-complexity inventory tool. It details internal states (redis vs s3 source), usage patterns, and complex logic flows, leaving no critical decisions for the agent to make without the provided context.

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

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

The description significantly adds meaning beyond the schema by listing valid `event_types` and warning about the consequence of using invalid types (422 error). For `report_date`, it explains the trade-off between widening the window and incurring greater cost, as well as the 7-day retention policy.

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

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

The description is exceptionally clear, stating that this tool is an 'INVENTORY' of report plans, distinguishing it from 'build' or 'return' functions. It explicitly contrasts itself with sibling tools like get_latest_report (PULL) and generate_research_report (topical writeups). The purpose is stated upfront and refined throughout the document.

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

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

It provides clear, actionable usage guidelines in two distinct modes: 'Event-first' and 'Research-first.' Furthermore, it outlines a comprehensive five-step workflow for finding the most pertinent plans, linking this tool to several other sibling functions.

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, so the safety profile is covered. The description adds real value beyond them: public/no-auth, authoritative live-config reads (never stale), refusal behavior for under-scoped kinds, and payload-size warnings for `tickers`/`tickers_with_names`. Strong supplemental context for an annotated read-only 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-loaded with the core directive before the long catalog list, and each bullet carries unique routing information. Slightly long with chatty asides ('NOTE: thousands of names', parenthetical hints), but almost none of it is removable for a 16-way multiplexer.

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-shape detail is not owed, and the description still names the `options` payload. It covers scoping prerequisites, auth, sizing, and per-kind destinations, leaving nothing an agent needs to invoke it correctly.

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

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

Schema coverage is already 100% with an enum on `kind`, so the baseline would be 3, but the description goes far beyond it: each kind gets a meaning, example values, the structure of what comes back ({concept, statement_type, label, ...}), and which of `ticker`/`q`/`cik` it consumes. This is semantics the schema cannot express.

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, straight from the backend') and then enumerates every catalog the `kind` multiplexer can return. It is unmistakable against siblings like `get_technical_indicator_data` or `download_dataset`, which it explicitly routes to/from.

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?

Opens with an imperative rule of thumb ('Call this BEFORE guessing a parameter value'), names the three kinds that require a scoping param (`ticker`, `q`/`cik`) and states they refuse the call without it, and explicitly redirects agents away from `download_dataset` (3 calls/week) to this tool for feed discovery.

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 adds the substantive behavior: 12h TTL cache, empty list means cold cache rather than no event, cache.count semantics from situate, coalescing onto report writes, and OAuth bearer requirement. These are exactly the traits an agent would otherwise misread as data absence.

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 with the core action first, then the situate prerequisite, then the follow-up pattern. It is longer than needed for a list tool and the arrow-chain examples and repeated cache-TTL mentions add bulk, 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 5-parameter filtered read with an output schema and only a readOnlyHint annotation, the description covers prerequisites, valid type strings, follow-up narrowing, empty-result interpretation, and where stale data lives. Nothing material is missing before an agent fires the call.

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

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

Schema coverage is already 100%, yet the description adds genuine meaning: why event_type has no default (a default would answer a different question) and the eps_update-is-one-slice-of-earnings nuance. It also restates the enumerating source (list_options("event_types")) and the tickers narrowing rule, though sector/industry/market_cap are left entirely to the schema.

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

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

States a specific verb and resource ('Pull live market events from the backend's Redis-backed cache') plus the scoping constraint (12h TTL). An agent can tell it retrieves cached realtime event records by type, distinct from report or streaming 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?

Explicit ordering rule ('Call situate(...) FIRST') with the reason for each branch (symbols vs no symbols), the alternative when data is older than the cache ('payload lives in the card's persisted_in table'), the required-first-hop pattern, and the downstream alternatives list_available_reports/get_latest_report. When-not guidance is also given ('an unfiltered follow-up call re-pulls the whole cache').

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?

readOnlyHint=true already covers the safety profile, so the bar is lower, and the description still adds real context: results are scoped to 'only the authenticated user's jobs' (an auth/isolation constraint not in the annotations) and it documents the naming conventions for workflow vs dataset schedules. It doesn't mention ordering, limits, or pagination, 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 purpose, then scope, then output shape, then naming, then cross-tool routing — a sensible order. Slightly padded by enumerating the returned fields, which the output schema already provides, but the remainder earns its place.

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

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

With an output schema present, the description needn't re-explain return values, yet it supplies the non-obvious parts — user scoping and the wf:/ds: naming scheme that an agent needs to interpret or act on the results. Nothing required to invoke this zero-parameter read 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?

Zero input parameters, so the baseline is 4; there is nothing for the description to disambiguate. The naming-convention detail (wf:/ds: prefixes) is useful but relates to interpreting results, not to inputs.

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

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

States a specific verb+resource ('List the caller's scheduled tasks') and immediately ties it to the origin tool `schedule_task`, which disambiguates it from the many other list_* siblings. An agent can tell this apart from delete_scheduled_task and get_task_status 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?

Explicitly routes the agent onward: 'Use `name` as the key to remove a job with `delete_scheduled_task`', giving a concrete when-to-use-this-vs-sibling rule. It doesn't state exclusions or preconditions for the listing itself, but the listing scope 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?

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?

Beyond readOnlyHint=true, the description discloses substantial operational behavior: the review/publishing caveats, what each build status means, that file URLs are presigned and valid for 12 hours, that links must not be fetched into chat, auth requirements, and plan-quota-only rate limiting. This is exactly the kind of 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?

The purpose is front-loaded in the first sentence, and the remaining paragraphs are organized around output shape, link handling, and build statuses. It is longer than strictly necessary for a list tool and repeats the return shape even though an output schema exists, but the extra detail is largely substantive rather than rambling.

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

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

Given the tool's complexity, 4 fully documented parameters, existing annotations, output schema, and the unusual publishing-review behavior, the description covers everything an agent needs to call it correctly. No meaningful gaps remain for selection or invocation.

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

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

Schema description coverage is 100%, so start_date, end_date, latest_only, and dataset_name are already fully explained in the input schema. The description does not add syntax or format details for these parameters beyond the schema, so the high-coverage 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?

The description states a specific verb and resource: 'List the user's own saved datasets (from save_user_dataset) with their build status and download links.' It explicitly ties the tool to save_user_dataset and later names get_user_dataset_file as the tool for reading rows, so an agent can distinguish it from adjacent dataset siblings 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?

It provides explicit routing: use get_user_dataset_file to read a file's rows, give latest_url for 'what's my feed URL?', never call or offer research_url as a download, and use get_latest_report for the user's own reports. These are concrete when-to-use and when-not-to-use alternatives, not just implied context.

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

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

Annotations 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.