clariBI.com

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful behavioral context: the possible statuses (pending, connected, failed, expired) and that a connected handoff yields a data_source_id. This goes beyond the structured annotations and clarifies the polling 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?

Two sentences, front-loaded with the action and resource, then the return value and downstream use. Every sentence earns its place with zero redundancy.

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

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

For a simple polling tool with one parameter and an output schema, the description is complete. It covers what the tool does, when to use it, what it returns, and how to use the result (pass to run_analysis). No gaps are apparent.

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

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

The schema already describes handoff_id as 'The id returned by request_oauth_integration_url', and the description repeats this same linkage without adding new parameter meaning. With 100% schema coverage, 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?

The description uses a specific verb 'Poll' and identifies the resource as 'an OAuth handoff initiated by request_oauth_integration_url'. It also specifies the returned statuses and the data_source_id, distinguishing this from sibling tools like get_analysis_status or check_pricing.

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?

Clear context is provided: use this tool to poll an OAuth handoff initiated by request_oauth_integration_url, and it explains the next step of passing the data_source_id to run_analysis. It does not explicitly list when not to use or mention alternatives, but the context 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safe read-only nature. The description adds valuable behavioral context by explicitly stating 'No authentication required' and enumerating the specific data fields returned. It does not contradict the annotations and provides additional operational detail.

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

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

The description is extremely concise, consisting of two short sentences. The primary action and resource are front-loaded, and every phrase adds useful detail (what is listed, and the auth requirement). No redundant or filler content.

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

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

For a simple tool with one optional parameter, full schema coverage, an output schema, and comprehensive annotations, the description provides all necessary context: what it does, what it returns, and the lack of auth requirement. Nothing critical is omitted.

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

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

The schema already fully describes the only parameter (tier) with its allowed values, providing 100% coverage. The description adds no extra meaning beyond what the schema offers, so the baseline of 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool's function with a specific verb ('List') and resource ('clariBI subscription tiers'), detailing exactly what is returned (prices, AI credits, data source limits, user limits, headline features). It is easily distinguishable from sibling tools like get_billing_status or create_checkout_session, which focus on billing status or checkout flows.

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

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

The description provides clear context for when to use the tool by specifying that it lists subscription tiers and pricing, and explicitly notes that no authentication is required. While it does not explicitly name alternatives or exclusion cases, the context is sufficient for an agent to select it correctly among siblings.

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

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

Although annotations already indicate a mutating, external-world action (readOnlyHint=false, openWorldHint=true), the description adds valuable context: the tool returns a URL and does not process payment within the LLM. This clarifies the exact nature of the side effect and prevents the agent from attempting to complete a transaction.

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

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

The description is two sentences: the first states purpose, the second adds a critical constraint (payment cannot happen internally). No wasted words, and the structure is front-loaded with the core action.

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

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

With a simple schema, full schema coverage, annotations, and an output schema, the description covers all necessary context: what the tool does, the key limitation, and the expected deliverable (a URL). Nothing essential is missing for an agent to invoke it correctly.

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

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

The schema provides 100% coverage for both parameters (tier and billing_period) with clear descriptions, so the description itself adds no additional parameter semantics. Baseline 3 is appropriate as the schema does the heavy lifting; no further elaboration is needed.

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

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

Description clearly states the tool creates a Stripe Checkout URL for upgrading a clariBI subscription, using a specific verb ('Create') and resource ('Stripe Checkout URL'). It distinguishes itself from sibling tools like check_pricing and get_billing_status by focusing on the upgrade/payment action, leaving no ambiguity about its function.

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

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

The description implies use when a user needs to upgrade their subscription and explicitly warns that payment cannot happen inside the LLM, guiding the agent to return the URL instead of simulating payment. It lacks an explicit mention of when not to use (e.g., for downgrades) or reference to alternative tools, but the context is clear enough for most cases.

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

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

Despite sparse annotations, the description discloses key behaviors: it stores configuration, sets up scheduling, and performs immediate source binding validation so errors surface before credits are spent. It also implies that running occurs separately via run_forecast, adding context beyond the annotations.

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

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

The description is concise and front-loaded with the primary purpose. Three sentences cover purpose, key behaviors, and a pointer to the related tool. No filler or redundant 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?

Given the tool's complexity (19 parameters, output schema exists), the description captures the essential workflow and validation behavior. It lacks a brief orientation on key parameters, but the output schema and parameter descriptions partially compensate, and the description clearly differentiates from run_forecast.

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 provides no parameter-specific guidance, relying solely on the input schema. With schema coverage at 63%, several parameters (e.g., schedule_day_of_week, include_anomalies) lack schema descriptions, and the tool description does not compensate by summarizing or prioritizing these fields.

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

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

The description clearly states the tool binds a forecast to a metric, stores configuration, sets up the schedule, and resolves source binding. It distinguishes itself from siblings by explicitly naming run_forecast as the tool to use for execution, making its role as a setup tool unambiguous.

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

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

The description provides clear context that this tool is for configuration and setup, and explicitly directs the agent to run_forecast to execute. However, it does not offer explicit when-not-to-use scenarios or prerequisites beyond the implied need for a valid source_id and metric_path.

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

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

Annotations already indicate the tool is not read-only (readOnlyHint: false). The description adds useful behavioral context: it creates an asynchronous report, returns an id for polling, and provides a download URL upon completion. It also discloses that omitting template_id results in an empty report shell. These details go beyond what annotations provide, though rate limits or auth requirements are not mentioned.

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

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

The description is concise: two sentences, no filler. The first sentence states the action and scope, while the second explains the return value and async workflow. Every word adds value, making it well-structured and easily scannable.

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

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

Given the tool's moderate complexity (3 params, output schema present, multiple sibling tools), the description covers the essential return behavior and polling workflow. It does not explain the output schema structure, but that is already available in the output schema itself. Missing auth or org-specific context, but the description is sufficiently complete for an agent to invoke it correctly.

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

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

The input schema already contains descriptions for all three parameters (100% coverage), including the default for output_format and the behavior of template_id. The description does not add extra parameter-level meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Create a new generated report in your clariBI organization.' It uses a specific verb ('Create') with a resource ('generated report') and differentiates from siblings like list_reports and get_report by focusing on creation. It also mentions the returned report id and download URL, which reinforces its purpose.

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

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

The description provides clear context by explaining the workflow: poll via get_report and wait for status 'completed' to get the download URL. However, it does not explicitly mention when to use this tool versus alternatives (e.g., create_forecast) or state when not to use it. This is a minor gap, but the workflow guidance is helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety. The description adds the key behavioral detail that it returns the analysis result if completed, implying a status/result distinction. This enriches the annotation-covered behavioral profile without contradicting it.

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

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

Two sentences, both essential. Front-loaded with the primary action ('Check the status'), followed by a clarifying return statement. No filler or redundancy.

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

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

For a simple status-check tool with one well-documented parameter, a rich output schema, and strong annotations, the description is complete. It doesn't need to explain return values in detail since an output schema exists. It adequately covers the core behavior and usage prerequisites.

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

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

The schema already provides 100% coverage of the single parameter 'job_id' with a clear description ('job_id returned by a prior run_analysis call'). The description's mention of 'previously-dispatched' adds no new semantic meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description uses a specific verb ('Check') and resource ('status of a previously-dispatched run_analysis job'), clearly distinguishing it from sibling tools like get_forecast_run or run_analysis. It also states the return behavior ('Returns the analysis result if completed'), adding further specificity.

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

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

The phrase 'previously-dispatched run_analysis job' clearly implies use after run_analysis, providing context for when to call. However, it does not explicitly state when not to use it or mention alternatives, though the sibling context makes this straightforward. This meets the 'clear context, no exclusions' bar.

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

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

Annotations already mark readOnlyHint and idempotentHint; the description aligns with these and adds value by disclosing the specific status components (tier, renewal date, upgrade options). This goes beyond the annotations and helps the agent understand the response 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 a single sentence, front-loaded with the action and resource, and every phrase adds meaningful detail. There is no redundancy or filler.

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

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

Given that this is a parameterless, read-only tool with a rich output schema and clear annotations, the description is fully adequate. It identifies the key informational content without needing to explain return values or parameters.

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

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

The tool has zero parameters, so the baseline of 4 applies. The description does not need to explain parameter meanings, and the empty schema with 100% coverage fully documents the input.

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

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

The description clearly states the action ('Get') and resource ('organization's billing status'), and specifies the key content returned (tier, renewal date, upgrade options). This distinguishes it from sibling tools like check_pricing, which focus on pricing rather than the billing status.

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

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

The description makes the tool's subject clear but does not explicitly state when to use it over alternatives such as check_pricing or create_checkout_session. Usage context is implied ('billing status') but no direct comparisons or exclusions are provided.

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 idempotentHint=true, so the agent knows this is a safe read operation. The description adds value beyond annotations by specifying exactly what is included in the response (widget definitions, recent refresh data, web URL), providing useful context about the tool's output.

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

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

The description is a single sentence that front-loads the core purpose, followed by a concise list of included elements. Every word earns its place with no redundancy or filler.

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

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

The tool has a simple parameter set and an output schema, so the description doesn't need to explain return values. It covers the key behavioral aspect (what the fetch includes) and is fully self-sufficient for a single-ID fetch operation.

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

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

The schema description for dashboard_id is already 100% complete and self-explanatory ('UUID of the dashboard to fetch'). The tool description does not add parameter-specific details, but given full schema coverage, the baseline of 3 is appropriate.

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

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

The description starts with 'Fetch one dashboard by ID', clearly indicating a specific verb (fetch) and resource (dashboard by ID). It further distinguishes from sibling tools like list_dashboards by emphasizing the singular fetch and including what the result contains (widget definitions, refresh data, web 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?

The description clearly implies this tool is for retrieving a single dashboard when its ID is known, which naturally differentiates it from list_dashboards. However, it does not explicitly state when to use an alternative or provide an exclusion criterion, so it misses the top score.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds critical context: the schema comes from preprocessing metadata from the last sync, and successful use requires status to be 'active'. This goes beyond annotations to explain the synchronization requirement.

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

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

Three sentences, front-loaded with the main action, followed by use case and a critical polling note. Every sentence adds value and the description is appropriately sized without redundancy.

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

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

With an output schema present and annotations covering safety, the description fully covers purpose, usage, behavior, and even the polling pattern for data readiness. Nothing essential is missing.

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

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

Schema description coverage is 100%, with the only parameter (data_source_id) already clearly described. The description adds no additional parameter semantics, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Fetch') and resource ('column schema for a data source'), clearly distinguishing it from siblings. It also ties it to run_analysis and upload/ingest flows, making the tool's role 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?

It explicitly says 'Useful before asking run_analysis about specific columns' and instructs to 'Poll this after upload_data_source / ingest_url_data_source until the returned status flips to active'. This provides clear when-to-use guidance and references sibling tools for 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 already declare readOnlyHint=true and idempotentHint=true, which covers basic safety. However, the description adds no further behavioral context, such as what happens for an invalid ID, error responses, or rate limits. It essentially restates the tool name without additional detail.

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

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

The description is a single concise sentence of six words: 'Fetch one forecast configuration by ID.' Every word is meaningful with no redundant filler, making it efficient and well-structured.

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

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

For a simple get-by-ID tool, the description is adequate given the presence of an output schema and annotations. It clarifies that 'configuration' is fetched, distinguishing from get_forecast_run. It does not mention edge cases but they are not expected for such a minimal tool.

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

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

Schema description coverage is 100% with the parameter forecast_id fully described as 'UUID of the forecast to fetch.' The description does not add extra meaning beyond the schema, so it meets the baseline but does not exceed it.

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

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

The description uses the specific verb 'Fetch' with the resource 'forecast configuration' and scope 'by ID', clearly distinguishing it from sibling tools like get_forecast_run (which fetches a run) and list_forecasts (which lists configurations). This is exactly what a tool description should do.

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

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

The description implies the tool is used when you have a specific forecast ID and need its configuration, but it does not explicitly state alternatives or exclusions. No guidance is given for when to use this versus list_forecasts or get_forecast_run, though the name makes it reasonably 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?

The annotations already declare readOnlyHint and idempotentHint, and the description adds the special behavior of run_id='latest' and the detailed contents of the returned envelope (drivers, anomalies, etc.). No contradiction with annotations.

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

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

Two concise sentences, front-loaded with the action, and every clause adds information (special case, return contents). 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?

The description, combined with the input schema and annotations, provides sufficient information for correct invocation: required parameters, the 'latest' keyword, and the expected results. No gaps identified.

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

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

The schema documents run_id with a description including the 'latest' special value, but forecast_id lacks a description. The tool description reinforces the run_id behavior and mentions fetching by ID, but adds no specific meaning for forecast_id beyond the schema's type/format. With 50% schema coverage, the description partially compensates.

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

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

The description uses the specific verb 'Fetch' and identifies the resource as 'one run of a forecast,' with a clear special-case for run_id='latest'. It contrasts with sibling tools like list_forecasts and run_forecast, making its purpose distinct.

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

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

The description provides clear context for when to use the tool (to retrieve a specific forecast run, including the latest) but does not explicitly mention alternatives or when not to use it. The context of returning a full forecast envelope implies its use case.

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 idempotentHint=true, so the agent knows it is safe and repeatable. The description adds meaningful behavioral context: each row compares a prior run's projection against actuals, and it explains how to interpret the output (trends, optimism bias). It goes beyond a simple 'returns data' statement.

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, purpose first, no fluff. The first sentence states the core functionality, the second provides use-case context. Every word earns its place.

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

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

Given the simplicity (one parameter, output schema present), the description covers the essential context: what is returned, how to interpret it, and why the tool might be used. It does not mention edge cases like empty runs, but the output schema likely covers response shape. This is a well-rounded description for a focused tool.

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

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

Schema description coverage is 0%, so the description must compensate. Although forecast_id is not explicitly defined, the description repeatedly refers to 'a forecast' and 'your forecasts', making it clear that forecast_id identifies the relevant forecast. With only one parameter, the semantics are effectively conveyed.

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: 'Returns per-past-run accuracy for a forecast.' This clearly distinguishes it from sibling tools like get_forecast (forecast details) and get_forecast_run (single run details). The purpose is immediately understandable.

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

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

The description explicitly states when to use the tool: 'Use this to see whether your forecasts have been getting MORE or LESS accurate over time, or to spot when a backtest sMAPE was systematically optimistic.' While it does not name alternative tools explicitly, the context is clear and actionable.

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 idempotentHint=true, which cover the safety profile. The description adds minimal behavioral context beyond that ('generated' report), but does not disclose edge-case behaviors like not-found errors or authorization requirements. Since the description is consistent with annotations and provides some value, a mid-range score is appropriate.

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

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

The description is a single, front-loaded sentence that conveys the essential information with zero wasted words. It is perfectly concise for the tool's simplicity.

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 low complexity (one parameter), the presence of an output schema, and strong annotations, the description sufficiently covers the necessary information. It does not explain return values, but that is not required since an output schema exists. Only a minor gap: no mention of error scenarios, but the overall context is complete.

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

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

The input schema has 100% coverage with the parameter report_id described as 'UUID of the report to fetch.' The description's 'by ID' simply restates this, adding no extra meaning beyond the schema. Baseline of 3 is appropriate given the high schema coverage.

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 'Fetch one generated report by ID' uses the specific verb 'fetch' with a clear resource ('one generated report') and scope ('by ID'). It distinguishes itself from sibling tools like list_reports (which lists multiple) and generate_report (which creates), leaving no ambiguity about its function.

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

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

The description implies usage context: use this when you have a specific report ID and need that single report. However, it does not explicitly mention alternatives or exclusions (e.g., 'For listing reports, use list_reports'). The context is clear but not explicitly contrasted with other tools, so it stays at implied usage.

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 idempotentHint=true, so safety is covered. The description adds the specific data points returned (AI credit usage, counts, rate-limit headroom), which gives the agent a clear expectation of the tool's output scope. No contradictions or missing safety notes.

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

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

The description is a single, well-structured sentence that front-loads the action ('Get') and the resource ('organization's current...'). Every word adds value; no filler or redundancy.

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

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

For a zero-parameter, read-only tool with an output schema, the description fully captures the tool's scope and the specific data points it returns. There are no apparent gaps in what the agent needs to know.

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

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

The tool has zero parameters, making schema coverage trivially 100%. The description does not need to explain parameter semantics, and the baseline for no parameters is 4.

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

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

The description clearly identifies the tool's purpose: retrieving organizational usage metrics (AI credit usage, data source count, user count, and rate-limit headroom). The verb 'Get' and the explicit resource scope distinguish it from sibling tools like get_billing_status or get_dashboard.

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

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

No explicit when-to-use or alternative comparisons are provided. The purpose is self-evident for a simple read-only getter, but the description does not guide the agent on choosing this tool over similar ones (e.g., get_billing_status). The usage is implied rather than 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 already indicate the write and non-idempotent nature. The description adds valuable context: the fetch is server-side, private networks are blocked, returns the data_source_id once preprocessing starts (indicating async), and the URL is fetched only once. These details go beyond annotations and set accurate expectations.

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

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

The description is compact and well-structured: primary action first, then formats, security constraints, return value, and usage guideline. Every sentence contributes useful information without redundancy or 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?

Given the tool's complexity (5 params, async behavior, security constraints) and the presence of an output schema, the description covers all key aspects: purpose, formats, limitations, return behavior, and when to use. Minor details like failure modes are left out but are likely covered by the output schema or are non-essential.

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 parameters are already documented in the input schema. The description reinforces the 'url' behavior (public fetch, blocking) and 'format' hint but adds little new semantic value beyond schema. A baseline of 3 is appropriate when schema carries the load.

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 begins with a specific verb and resource ('Create a new data source'), explains the method ('fetching a public URL on the server side'), lists supported formats, and distinguishes from siblings by mentioning the 25 MB upload cap and the 'upload_data_source' alternative context. This clearly identifies what the tool does and sets it apart.

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

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

The description explicitly states when to use this tool ('files larger than the 25 MB inline upload cap') and implicitly contrasts with the upload alternative. It also states a key limitation: private networks are blocked, implying those URLs should not be used. Though the sibling tool is not named, the guidance is clear and actionable.

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 and idempotentHint, so the description need not repeat safety. It adds value by specifying the exact returned fields and the browser URL, which is useful behavioral context beyond the 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?

The description is a single, front-loaded sentence that states the action and output. Every word earns its place, with no redundancy or filler.

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

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

For a simple list tool, the description is complete: it explains what is returned, while the schema covers pagination and search parameters. The output schema and annotations reduce the need for further elaboration.

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

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

Schema description coverage is 100%, with clear descriptions for limit, offset, and search. The description does not add parameter details, but the schema already carries the semantic burden, 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?

The description clearly states the tool lists dashboards in the clariBI organization, which is a specific verb+resource. It distinguishes from siblings like get_dashboard, list_data_sources, and list_reports by focusing on dashboards and mentioning the returned fields.

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

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

The description implies usage as a listing tool but provides no explicit guidance on when to use it versus alternatives like get_dashboard for a single dashboard. There is no mention of exclusions, but the context is clear enough for basic selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds return field details and notes row count is 'when known', which is minor extra context. No 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?

Two sentences with no redundant information, front-loaded with purpose and return fields.

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 list operation with optional filtering and pagination parameters, the description covers the core behavior. Output schema is present, so return format details are not needed. Minor gap: no explicit mention of pagination behavior, but limit/offset are in 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?

All three parameters have schema descriptions covering 100% of parameters. The tool description does not add any parameter-specific information beyond the schema, so baseline 3 is appropriate.

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

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

The description uses the specific verb 'List' and identifies the resource as 'data sources connected to your clariBI organization', also enumerating return fields. This distinguishes it from sibling list tools like list_dashboards and list_reports.

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

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

No explicit when-to-use or alternatives are mentioned. However, the resource clarity makes it the obvious choice for listing data sources, and the sibling get_data_source_schema could be an alternative for schema details, but this is not 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 already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds meaningful context about the list contents (per-row metric details) and relation to get_forecast_run, going beyond annotations without contradicting them.

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

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

The description is two sentences long, front-loaded with the primary purpose, and includes only essential information. Every sentence earns its place without redundancy.

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

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

Given the tool's simplicity, the presence of an output schema, and full parameter documentation, the description adequately covers what the agent needs. It states the row content and points to the companion tool for deeper detail, making it complete for this 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 input schema provides full descriptions for all three parameters (limit, offset, is_active), achieving 100% schema coverage. The description does not add parameter-level detail, so it meets the baseline of 3.

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

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

The description clearly states the tool lists metric forecasts in the clariBI organization, with a specific verb ('List') and resource ('metric forecasts'). It further specifies what each row covers (source binding, horizon, schedule, latest run status), and differentiates from get_forecast_run by directing users there for full results.

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

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

The description explicitly points to get_forecast_run as the alternative for retrieving full forecast results, providing clear guidance on when to use which tool. It does not exhaustively cover all possible sibling exclusions, but the given guidance is concrete and useful.

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 and idempotentHint, so safety is covered. The description adds the organization scope and lists return fields (id, title, status, output format, download URL), but does not disclose pagination behavior, default ordering, or that all statuses are included. This adds some context but not deep behavioral detail.

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

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

A single sentence that front-loads the action and resource, followed by a concise list of return fields. No wasted words.

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

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

The tool is a simple list operation with output schema present, and schema covers parameters. The description adequately scopes the operation and return data. Minor ambiguity around the word 'generated' could be confused with a status filter, but the schema disambiguates via the status enum. Overall sufficient for an agent.

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

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

Input schema descriptions cover 100% of parameters with clear meanings and defaults. The description does not reference parameters, but the schema already provides sufficient semantics, 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?

The description uses the specific verb 'list' with resource 'generated reports' and scopes it to 'your clariBI organization'. It distinguishes from siblings like get_report (single report) and other list_* tools by explicitly naming the report resource and return fields.

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

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

The description implies usage for browsing reports but does not explicitly contrast with get_report or mention when to prefer this tool over alternatives. No exclusions or preconditions are stated, so it is clear but not explicitly guided.

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

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

The description discloses cost (1-2 AI credits), side effect (overwrites old narration), return value (new narration), and failure preconditions (incomplete run, narration_enabled=false). This is exactly the kind of behavioral context that annotations do not provide, especially since all hints are false/uninformative. No contradiction with annotations.

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

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

Three dense sentences, each adding critical information: purpose and scope, cost and side effect, and refusal conditions. No filler, front-loaded with the primary action. Efficient and well-structured.

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

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

For a mutation tool with two required parameters, the description covers purpose, preconditions, cost, side effects, and return value. An output schema exists, so return format is handled elsewhere. No missing context that would prevent an agent from using 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 50% (run_id has description, forecast_id does not). The description adds context by tying both IDs to an 'existing completed forecast run' and highlighting that run_id must reference a completed run. However, it does not explicitly define forecast_id's role (e.g., the owning forecast), leaving some ambiguity. Partially compensates for the coverage gap but not fully.

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: 'Re-run ONLY the AI narration step against an existing completed forecast run.' This clearly distinguishes it from running the full forecast (e.g., run_forecast) and other siblings. The scope is precise and immediately understandable.

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

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

The description states when to use the tool (regenerate narration on an existing completed run) and explicitly identifies refusal conditions (run not complete, narration_enabled=false). It does not name an alternative tool, but the 'ONLY' phrasing and mention of 'no engine work' imply when not to use it (for full re-runs). Clear context with minor room for explicit sibling differentiation.

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

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

The description discloses key behavioral traits beyond annotations: it validates inputs, sends an email, returns a pending_id, and imposes a 10-minute requirement. Even though annotations are all false (not read-only, not idempotent), the description aligns and adds meaningful context. It doesn't fully describe what happens on duplicate signups or whether the email is always sent, but the provided details are valuable.

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

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

The description is two sentences, front-loaded with the main verb and resource ('Begin clariBI account signup'), followed by concise process details and a clear next-step callout. 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?

For a 5-parameter tool with an output schema, the description covers the full flow: validation, email dispatch, pending_id return, and the required follow-up action. It is complete for an AI agent to understand the tool's role, inputs, and outcome without needing to inspect further documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a small amount of semantic meaning by noting validation of 'email + organization name,' which is not explicitly in the schema. However, it doesn't elaborate on the optional fields (first_name, last_name) or further clarify accept_terms, so it stays at the baseline.

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

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

The description clearly states the tool's purpose: 'Begin clariBI account signup.' It details the specific actions (validates email + organization, emails verification code, returns pending_id) and distinguishes itself from sibling tools by explicitly referencing the next step, verify_email.

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 context for when to use the tool ('Begin clariBI account signup') and explicitly instructs the user to 'Call verify_email(pending_id, code) within 10 minutes to finish signup,' which is a clear follow-up action. However, it doesn't explicitly mention when not to use this tool or list alternatives, so it misses the full 'when/when-not/alternatives' guidance.

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

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

Beyond the annotations, the description discloses that the tool returns a user-facing authorization URL, requires user interaction (clicking Allow), asynchronously creates the connection, and provides a handoff_id used for polling. This is meaningful behavioral context that annotations alone do not convey.

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

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

The description is compact and front-loaded with the primary purpose, then adds the workflow in two sentences. Every sentence earns its place with no fluff or repetition.

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

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

Given the OAuth handoff complexity and the existence of an output schema, the description is complete: it specifies what the tool returns, what the user must do, and how to follow up. It also references the relevant sibling tool for status checking.

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 description adds no parameter-level detail beyond what the schema already documents. The list of integrations is helpful but redundant with the schema's provider enum description. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Initiate an OAuth handoff') and clearly identifies the resource (vendor integrations) with concrete examples. It also distinguishes itself from the sibling follow-up tool by mentioning check_integration_status for polling.

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

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

The description provides clear context for when to use the tool and outlines the expected workflow: call to get an authorization URL, have the user open it, then poll check_integration_status. It does not explicitly state when not to use the tool or name alternative tools, so it falls short of a 5.

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

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

The description discloses that the tool 'consumes AI credits'—a key behavioral trait not captured by the annotations (all false). It also explains the asynchronous behavior (returns inline or job_id for polling), adding useful operational context. With annotations that are neutral and uninformative, the description carries the burden and does so well, though it doesn't mention failure modes or rate limits.

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

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

The description is concise and well-structured: the first sentence states the core purpose, the second explains the return behavior, and the third provides actionable prerequisite guidance. Every sentence earns its place with no redundant filler, and important details are front-loaded.

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

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

With an output schema available (so return values are documented), the description covers the essential context: the core action, the async return modes, and the data-source prerequisite with alternative ingestion paths. It doesn't mention error scenarios or credit limits, but those are secondary given the clear guidance provided.

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

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

The input schema has 100% coverage, with detailed descriptions for `question`, `wait_seconds`, and `session_id`. The tool description doesn't add parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('run') and resource ('natural-language analytics question against your connected data sources'), making the tool's purpose immediately clear. It also distinguishes the tool from siblings by describing the two possible return modes (inline result or job_id for polling), which sets it apart from tools like get_analysis_status or list_data_sources.

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

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

The description explicitly states when NOT to use the tool: if list_data_sources returns an empty list, the agent should first ingest data using named alternatives (upload_data_source, ingest_url_data_source, or request_oauth_integration_url). It also references get_analysis_status for polling, giving clear workflow guidance and alternative paths.

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 all false, providing no safety hints, so the description carries the burden. It discloses meaningful side effects: "Reserves AI credits up front" and dispatches a multi-stage pipeline. It also clearly describes the asynchronous behavior and what determines the return path. This exceeds what the annotations or schema convey, offering high transparency.

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

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

Two sentences, both dense and purposeful. The first identifies the action, the second details behavior and outcomes. No filler or repetition; the structure front-loads the core purpose. This is exemplary conciseness.

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

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

The tool is complex (cost, async, pipeline), yet the description covers purpose, cost side-effect, pipeline components, and the two return paths. An output schema exists, so return values need not be explained. Missing are prerequisites (e.g., forecast must exist) and potential error conditions, but these are not critical given the description's breadth. Overall, it is largely complete for an execution tool.

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

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

Schema description coverage is 50%: wait_seconds has a description, forecast_id does not. The description adds context about wait_seconds by linking it to the inline-vs-poll outcome, but it doesn't elaborate on forecast_id beyond what the name and format imply. Since coverage is not low, a baseline of 3 is appropriate, and the description adds moderate value without fully compensating for the undocumented forecast_id.

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

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

The description clearly states the tool's function with a specific verb and resource: "Run a forecast now." It distinguishes from siblings by naming the dispatched pipeline (backtest + projection + correlation) and the two return modes (inline result vs. pollable run_id). This makes it clear that run_forecast initiates a run, unlike create_forecast or get_forecast_run.

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

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

The description provides concrete usage guidance: it explains how wait_seconds controls whether you get the result inline or a poll handle, and explicitly references get_forecast_run for polling. However, it does not explicitly state prerequisites (e.g., the forecast must already exist) or when not to use this tool in favor of alternatives like run_analysis, so it stops short of full 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?

The description reveals critical behavioral traits not captured by the false-only annotations: the file undergoes the same validation and preprocessing as a web upload, the tool returns a data_source_id asynchronously, and the caller must poll or use wait_seconds to await completion. This sets clear expectations about state changes and timing, going well beyond the minimal annotation hints.

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 deliver purpose, formats, validation behavior, return value, and async guidance without redundancy. Each clause adds critical information, and the description is front-loaded with the primary function. No filler or repetition.

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

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

For a tool with asynchronous preprocessing, multiple supported formats, and size constraints, the description is impressively complete. It explains the return value, how to handle readiness (poll or wait), and the alternative for large payloads. With an output schema present, there is no need to detail the response structure further.

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

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

The input schema already provides 100% coverage with rich descriptions for all five parameters, including format specifics, size limits, and wait_seconds semantics. The tool description adds contextual value by linking data_source_id to run_analysis but does not meaningfully elaborate on individual parameters beyond what the schema 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?

The description opens with 'Create a new data source from an inline base64-encoded file' – a specific verb and resource with the exact mechanism. It enumerates supported formats and explicitly mentions returning a data_source_id, making the tool's purpose unmistakable. It also distinguishes itself from the sibling ingest_url_data_source by contrasting inline base64 with URL-based ingestion.

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

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

The description gives explicit when-to-use guidance: 'For larger payloads, host the file at a public URL and use ingest_url_data_source.' It also explains the async workflow: either pass wait_seconds to block or poll get_data_source_schema for readiness. This clearly directs the agent on choosing this tool over alternatives and how to handle the asynchronous nature.

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 provide minimal signal (all false). The description adds valuable behavior: it returns an OAuth access_token and MCP API key, and places the org on Trial tier (50 credits, 14 days). It does not detail side effects like single-use codes, but the key behavioral outcomes are disclosed without contradicting annotations.

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

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

The description is two sentences, efficiently front-loaded with the core action and followed by return value and account tier. Every sentence adds value with no redundancy or filler.

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

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

The description covers the tool's purpose, return value, and post-condition (Trial tier), and an output schema exists to detail the return structure. It does not explicitly state the dependency on register_account, but the schema's pending_id reference and sibling context make it adequately complete for a signup completion tool.

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

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

Schema description coverage is 100% for all parameters, so the baseline is 3. The description adds no extra parameter semantics beyond mentioning 'verification code plus a password' and does not reference pending_id, but the schema fully documents each field with constraints and origins.

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

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

The description clearly states the specific action: 'Complete clariBI signup by submitting the verification code plus a password.' This uses a precise verb ('complete') and resource ('clariBI signup'), distinguishing it from siblings like register_account (which initiates signup) and other unrelated tools.

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

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

The description implies usage context: it is the signup completion step, referencing the pending_id from register_account in the schema. It clearly indicates when to use, but does not explicitly state exclusions or alternatives. However, because it is uniquely paired with register_account, the guidance is sufficient.

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