analytics

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description is consistent with them. The description adds modest content-domain context but discloses no further behavioral traits such as output format, response size, or any platform-specific constraints.

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 11-word sentence that front-loads the primary purpose and contains no filler. It is appropriately sized for a one-parameter tool, though 'usage' carries a slight ambiguity (plan tiers vs API usage) that a more precise phrase could resolve.

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, read-only documentation tool with full annotation coverage and 100% schema documentation, the description is nearly sufficient on its own. The only gap is the unspecified return-value format, which matters slightly more because there is no output schema, but the nature of a docs tool makes a free-text documentation response predictable.

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 of 3 applies. The description loosely foreshadows the parameter's value space ('tiers, usage' maps to topics), but it adds no detail beyond what the topic parameter description already provides.

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

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

The description clearly identifies the tool as a platform documentation/info provider covering 'how it works, tiers, usage'. The resource is specific and the content domain is distinguishable from nearby siblings like discover_tools or tools_schema, though it doesn't explicitly name or contrast them.

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 implied: an agent needing platform-level documentation or information about tiers and usage would reach for this tool. However, there is no explicit when-to-use versus when-not-to-use guidance, and several siblings (discover_tools, ask_library, tools_schema) occupy overlapping 'find information' territory without any routing between them.

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 cover read-only, idempotent, non-destructive behavior. The description adds the user-facing action of handing over the link and guiding the user, which is useful context, but does not describe any further behavior like navigation or redirection details.

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, both informative: one defines scope and examples, the other explains the intended interaction. 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 simple one-parameter tool with a complete enum and safety annotations, the description is sufficient. It conveys when to use it, what it does, and how to deliver the result; no output schema is needed for a link-returning tool.

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

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

Schema coverage is 100% and the single parameter has a clear enum with descriptions. The description does not add additional semantic detail beyond what the schema already provides, 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 links users to account pages for actions not doable in chat, listing billing, browser upload, and report management as examples. It is a specific verb+resource, though it does not explicitly distinguish itself from siblings like reports_list or reports_view.

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 when-to-use context: for anything not doable in chat, such as billing or upload. It does not explicitly enumerate exclusions or name alternative tools, but the intended scope is 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?

Beyond the annotations, the description discloses meaningful behavior: a new named arrangement is created, nothing is overwritten, and numbers are untouched. This goes beyond the raw annotations and sets accurate expectations for side effects.

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

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

A single compact sentence delivers the action, scope, side-effect guarantees, and a constraint. It is front-loaded and contains no filler.

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

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

For a two-parameter tool with no output schema, the description covers purpose, safety expectations, and the type of accepted instructions. It is slightly light on alternative routing, but not enough to constitute a real gap.

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

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

The schema already documents instructions as 'What to change, in the user's words', and the description reinforces this as 'layout wishes'. It adds the useful constraint that instructions should not involve number changes, but it does not add extra semantics for estimate_id beyond the name.

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 action ('Apply') and a clear resource ('the estimate's page'), and explicitly frames the scope as layout-only via 'layout wishes'. It distinguishes itself from number-changing tools by stating 'no number changes', making its purpose unmistakable.

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

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

The description clearly implies this tool is for layout-oriented user requests and explicitly rules out number changes. It does not name an alternative tool for numeric edits, but the exclusion is enough to guide an agent toward the correct 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 cover read-only, idempotent, and non-destructive behavior, lowering the bar. The description adds meaningful behavioral context by framing the tool as advisory ('help desk') and by disclosing that it is multi-turn, which tells the agent this is a stateful conversation rather than a single-shot API call. It does not detail context handling, but the annotation coverage is strong.

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: it names the role ('AI help desk') before listing three action areas and the multi-turn trait. Every phrase contributes information, with 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 one-parameter conversational tool with rich annotations and no output schema, the description covers the essential behaviors: what the tool helps with and that it is multi-turn. It does not explain how multi-turn context should be supplied in the message, but given the low complexity, this is a minor gap rather than a serious omission.

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 schema already documents the sole 'message' parameter. The description's references to 'your question' add no new constraints on format, length, or how to include multi-turn context, which keeps this at the baseline score.

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

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

The description identifies an 'AI help desk' and names three concrete functions: choosing an analysis, interpreting results, and fixing errors, plus 'Multi-turn' to signal conversational use. This is a clear functional scope, but it does not explicitly contrast sibling tools such as check_tool_fit or discover_tools, so it lacks full differentiation.

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

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

It provides clear trigger conditions: use when the user needs help deciding which analysis fits, interpreting results, or troubleshooting errors, especially in a multi-turn conversation. It does not state when not to use it or name an alternative tool for direct execution, so it stops short of explicit exclusion 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by stating that non-reads produce immediate=false with a reason and route to decide_path, which is useful. However, it does not disclose details like response format, latency expectations beyond 'in seconds', or any side effects, though for a read-only tool this is a minor gap.

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 core purpose ('A read of the data... answered in this response, in seconds'). The conditional routing instruction is placed at the end, which is appropriate. Every sentence earns its place, though the phrasing is slightly awkward ('answered in this response, in seconds').

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 tool with two simple string parameters and no output schema, the description is mostly adequate. It explains what kinds of reads are supported and what to do for non-reads. However, it does not clarify what 'dataset_ref' should contain (e.g., a dataset ID or name) or how the agent should phrase the objective, which could lead to incorrect 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 0%, so the description carries the full burden for explaining parameters. The description mentions 'objective' implicitly by describing the kinds of reads it answers, but it does not explain what 'dataset_ref' refers to or how to format the objective. With two required parameters and zero schema descriptions, the description should provide more parameter-level guidance.

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

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

The description states a specific verb ('read') and resource (data), and enumerates the kinds of reads it answers (average, count, total, highest/lowest by group, a value in a month). It distinguishes itself from a non-read path by saying 'Not a read -> immediate=false... continue with decide_path.' However, it does not name a specific sibling tool as an alternative, so differentiation is implicit rather than explicit.

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

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

The description gives clear context for when to use the tool: when the objective is a read of data matching the listed patterns. It also provides an exclusion: 'Not a read -> immediate=false with the reason; continue with decide_path.' This tells the agent what to do when the tool is not appropriate, though it does not name alternative sibling tools explicitly.

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, idempotentHint, and destructiveHint, establishing that this is a safe read operation. The description adds behavioral context by mentioning it synthesizes an answer and includes citations, which is useful. It does not contradict annotations and provides sufficient transparency for a query tool.

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

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

The description is a single, concise sentence that front-loads the primary action and scope. It includes the key output detail (synthesized answer with citations) without any fluff, making it exceptionally efficient.

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

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

For a tool with one parameter, no output schema, and comprehensive annotations, the description is complete. It explains the purpose, scope, and expected return form. Nothing an agent needs to decide whether to call this tool is missing, especially given the read-only and idempotent hints.

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 coverage is 100%, so the 'question' parameter is fully documented. The tool description does not add extra semantics about the parameter beyond restating that it is a plain-language question. This meets the baseline of 3 but does not elevate 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 states a specific verb ('ask'), a precise resource ('all your delivered analyses'), and the expected output ('synthesized answer with citations back to specific reports'). This clearly distinguishes it from report listing or viewing tools and conveys its Q&A nature.

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 a clear context: it is for asking a question across the entire report library. It implies when to use it but does not explicitly state when not to use it or name alternatives such as 'answer_now' or 'find_precedent'. Since there are many siblings, the lack of explicit exclusions is a minor gap, but the context is sufficiently scoped.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine behavioral value by disclosing the returned content (stage progress, queue position, rejection reason tied to objective mismatch, ETA, report link), which matters because there is no output schema. It omits auth or rate-limit context, but that is minor for a read-only status check.

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 front-loaded sentence with no filler; the verb and resource lead, and the returned items are listed compactly. It is dense but every clause carries 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 read-only status tool with annotations covering safety, the description effectively substitutes for the missing output schema by enumerating what is returned. Nothing critical to correct invocation is absent, though a note on the relationship to package_status would complete the picture.

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 parameters (pipeline_id, track_token) are documented with their provenance in the schema, so the baseline is 3. The description mentions neither parameter nor adds format/syntax detail, 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 ('Check') and resource ('a commissioned build') and enumerates what it surfaces: stage progress, queue position, rejection reason, ETA, report link. An agent can distinguish it from modify_analysis (which commissions builds), but the description never contrasts it with the similarly-named package_status sibling.

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?

'Check a commissioned build' implies the tool is used after a build has been commissioned, and the schema ties pipeline_id back to modify_analysis, so the post-commissioning context is inferable. However, no explicit when-to-use trigger or when-not/alternative guidance is stated in the description itself.

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 read-only and idempotent behavior, and the description adds that the result includes a fit verdict, column mapping, and missing-input identification. However, phrases like 'the places it delivers' are vague, and there is no disclosure of how the fit verdict is reached or what happens with invalid inputs.

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 short and front-loads the core question before listing outputs. The telegraphic output list and the unclear 'places it delivers' prevent a perfect structure score.

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

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

With no output schema and three under-described parameters, the description supplies the gist and output categories but lacks clear return-value details and parameter definitions. An agent could probably call it successfully, but not with complete confidence in what it will get back.

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 define the parameters, but it never names objective, tool_name, or dataset_ref directly. It loosely hints at 'library tool' and 'THIS dataset/THIS question', but leaves objective unexplained and the parameter mapping implicit.

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 communicates that the tool evaluates whether a library tool fits a specific dataset and question, and it names concrete outputs (column mapping, missing required inputs, method-fit verdict). It is more informative than the tool name alone, though it does not explicitly contrast itself with sibling tools such as discover_tools or tools_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?

'Before naming a library tool' is an explicit workflow cue, and 'THIS dataset for THIS question' scopes when the tool applies. It gives no when-not-to-use guidance or named alternatives, so it does not fully reach explicit routing.

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

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

The annotations are all false/neutral, so they carry little safety information. The description compensates by disclosing that builds create durable owned objects, that JSON/deck tiers are re-runnable, and that 'failed builds are never billed' — useful behavioral and financial context beyond 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?

The purpose is front-loaded in the first sentence, and the four tier definitions are compact and scannable. Every sentence carries distinct information about required input, timing, or ownership, with no filler.

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

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

For a 7-parameter tool with nested objects and no output schema, the description covers the critical decisions: which tier to pick and the easiest parameter combination. It does not describe the response/return value or the legacy specification path, but the schema covers parameters and sibling tools like build_status can cover post-submission tracking.

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 100% schema description coverage, the baseline is 3; the description adds real value by detailing each tier's meaning, declaring tier as required even though the schema lists no required fields, and recommending the simplest parameter combination. It does not explain the legacy specification object, but the schema already documents 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 opens with a specific verb and resource: 'Commission a NEW analysis built for your question.' The word NEW distinguishes it from siblings like modify_analysis and run_analysis, and the tier breakdown clarifies the exact product being created.

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 frames when to use the tool (commissioning a new analysis) and tells the agent the easiest invocation ('fuzzy_request + dataset_ref + tier'). It also explains how to pick a tier by describing each option, but it does not explicitly name alternatives or state when not to use the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the fuzzy matching behavior, which is useful beyond the annotations, but doesn't cover pagination or result format details.

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 that are front-loaded with the primary action and capabilities. Every clause is informative and there is 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 read-only list/search tool with full schema coverage and annotations, the description sufficiently covers what the tool does and what it returns (uuid references). It could mention default limit behavior or result ordering, but is largely complete.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema. The description mentions fuzzy matching on name, description, and tags, which aligns with the 'search' parameter but adds no 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?

States a specific verb (list and search) and resource (your uploaded datasets), plus the fuzzy matching capability. It distinguishes itself from datasets_upload by clarifying this is for retrieval, not creation, though it doesn't explicitly name that sibling.

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 by mentioning the returned reference for path_resolver and path_tool_run, but it does not explicitly state when to use this tool versus alternatives like ask_library or my_objects for dataset 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 mark this as a write (readOnlyHint=false) that is neither idempotent nor destructive, so safety basics are covered. The description adds real context beyond that: REFRESH overwrites the existing dataset in place, downstream schedules/tools pick up new data on next run, and the upload-link path yields a file only the user can reach.

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 core action and organized by mode. Slightly informal phrasing ('Get your data in') costs nothing in clarity and every clause carries load.

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

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

With no output schema, the description correctly notes what you get back (a dataset_ref ready for path_resolver) and covers both modes plus the in-place refresh lifecycle. Complete for a 3-parameter, zero-required tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the crucial interrelationship: `replace_ref` must be combined with `data` to trigger refresh, and omitting `data` switches to upload-link mode. That pairing semantics is not obvious from the schema alone.

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 ('Get your data in' → create the dataset / get an upload link) and distinguishes two operating modes clearly. It lacks explicit differentiation from sibling datasets_list, but an agent can tell this is the write-side counterpart to listing.

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 routes usage by parameter: pass `data` to create immediately, omit it for an upload link, and add `replace_ref` with `data` to refresh. The when-to-use condition for each mode is spelled out rather than inferred.

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 convey read-only, idempotent, non-destructive behavior. The description adds value by stating deterministic behavior and specifying in detail what the single returned record contains, including conditional fields for read vs. package routes and the fallback question when information is missing. There is 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?

One dense, information-packed sentence that front-loads the essential use ('Step 0') and then economically enumerates all output components without wasted prose. Every clause adds routing or output semantics.

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 without an output schema, the description enumerates the record structure and all route branches (read plan for read, method family/tool fit for package, question when incomplete), which gives an agent a solid mental model of the tool's result. It does not describe score formats, error behavior, or an example, but those are secondary for a two-input router.

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 zero schema description coverage, the description must clarify the two parameters. It does suggest that objective is the new question and dataset_ref is the data ('which path answers it on this data'), which is meaningful, but it stops short of explaining expected formats, examples, or precise constraints. It partially compensates for the schema gap.

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

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

The description clearly identifies the tool as the initial routing decision for a new question and names the exact resource it operates on: the question and the data. It goes beyond the name by enumerating the five possible route values and the conditional components of the returned record, which distinguishes it from execution-oriented siblings like answer_now or order_analytics_package.

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 opening phrase 'Step 0 for a new question' gives a clear context for when to call it: before any other path is chosen. It does not explicitly name sibling tools as alternatives or state when not to use it, so it misses the top rung, but the intended placement in the workflow 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot: results are tagged source:'own' or 'standard_library' and ordering puts your own results first. It stops short of describing result volume or pagination, so 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?

Three compact sentences, each load-bearing: what it searches, how matching and default listing work, and the escape hatch. No repetition of the tool name 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 one-optional-parameter, read-only discovery tool with no output schema, the description covers sources, matching semantics, ordering, and the fallback route. Nothing an agent needs in order 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 parameter is self-documenting, so baseline is 3. The description still adds meaning beyond the schema: matching is plain-language (not keyword/exact) and the default ordering when the query is omitted is 'your own first', which the schema does not state.

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 (browse) and resource (analyses you can run), and goes further by naming the two content sources it spans: your commissioned analyses plus the platform Standard Library. An agent can tell this apart from siblings like ask_library, tools_schema, or my_objects without opening the schema.

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

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

Gives explicit when-to-use (browse available analyses), what happens with no argument ('no query lists everything, your own first'), and a concrete fallback path when nothing matches ('Commission it with path_resolver'). Both the trigger and the alternative are stated rather than inferred.

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, and the description reinforces this with 'read-only.' It adds useful scope information—'platform-wide' and the kind of results included—but does not disclose result size, ordering, or failure behavior. With annotations covering the main safety profile, this is acceptable but not rich.

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 key usage cue, 'Before estimating.' Both sentences contribute meaningful scope information, and there is no obvious filler or redundancy beyond what annotations already state.

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 three-parameter read-only tool with no output schema, the description leaves 'k' undefined and does not tell the agent what result shape to expect. It orients the agent on why to call the tool but not enough to confidently set all parameter values.

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

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

Schema description coverage is 0%, so the description must compensate for the three parameters. It loosely maps to 'objective' and 'dataset_ref' via 'how did we answer this objective before, on this data or any data?', but it says nothing about 'k', its default, or how these parameters affect the search. This is minimal added meaning over the raw schema.

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

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

The description clearly states the tool's purpose: to find how a given objective was answered before, by searching prior packages and library runs. It names the resource and scope (platform-wide, read-only) and is clearly distinct in spirit from estimation/execution siblings, though it does not explicitly name a differentiating sibling.

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 'Before estimating' gives a clear contextual trigger for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives such as discover_tools or run_analysis, leaving the routing partially 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?

Discloses important behavioral traits beyond the sparse annotations: 'the original stays put', 'Rebuilds on the analysis's own dataset by default', and 'Returns pipeline tracking'. This gives the agent a clear picture of mutation, non-destructiveness, and follow-up behavior without needing additional inference.

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 tightly-scoped sentences with no fluff. The core action and required inputs are front-loaded, followed by default behavior, return value, and the recommended follow-up step.

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 a moderate 4-parameter tool with no output schema, the description covers required inputs, default dataset behavior, non-destructive side effects, return semantics, and next step. An agent has enough to invoke and monitor the operation correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by clarifying that changes are expressed in plain language and that the dataset_ref defaults to the analysis's own dataset, going slightly beyond the schema.

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

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

States a specific action: 'Modify an EXISTING analysis into a new version', with concrete change examples like 'reword the question, swap the method, or add a variable'. This clearly distinguishes it from creation and execution siblings, since it targets existing analyses and produces a new version.

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

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

Provides clear usage context: pass tool_name + changes in plain language, rebuild on the existing dataset by default, and follow with build_status. It does not explicitly name when-not-to-use alternatives, so it does not fully earn a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the data scope (owned objects, grouping by objective), which is useful. However, it does not disclose the behavior of parameters like limit, query, or include_dropped, nor any pagination or filtering semantics. Since annotations cover the core safety aspects, a 3 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, concise sentence that front-loads the action and resource. It avoids fluff and communicates the core purpose efficiently. It earns a 4 for being well-structured, though it could add a bit more detail without becoming verbose.

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 three parameters, no output schema, and zero schema description coverage. The description explains the tool's scope but omits parameter semantics and output format. For a list/search tool, an agent needs to know how to use query, what limit does, and what 'include_dropped' affects. The description is incomplete for effective 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 0%, so the description must compensate by explaining the parameters. It does not mention limit, query, or include_dropped at all. An agent has no guidance on what 'query' searches, how limit affects results, or what 'include_dropped' means. This is a critical gap.

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

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

The description clearly states the verb ('List and search'), the resource ('objects you own'), and adds specific context (curated charts/tables/figures, grouped by objective). This differentiates it from sibling tools like reports_list or datasets_list, which focus on different resources. The purpose is unambiguous and not a tautology.

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

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

The description explains what the tool does and its scope, allowing an agent to infer when it is appropriate. However, it does not explicitly state when to use this tool over alternatives, nor does it mention exclusions or prerequisites. Given the large sibling list, explicit guidance would improve selection accuracy.

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 usefully discloses billing behavior: 'Credits per tool run; failed runs never billed.' It also implies this is a non-read-only ordering action, consistent with readOnlyHint=false. However, it does not disclose side effects, delivery mechanics, or how an existing order/package is affected.

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 short at two sentences and starts with the main verb 'Order,' but the wording is convoluted ('Order what the estimate promised after reviewing it') and the final clause 'one reviewed page delivered' feels disconnected. It is compact but not maximally clear.

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

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

With no output schema and four parameters, the description should clarify what the agent receives after ordering, how layout_objective is used, and the relationship to estimate_id. It mentions billing and a delivered page but omits return behavior and key parameter semantics, so the tool remains incompletely specified.

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, but it only loosely maps to parameters: 'library tools' hints at tool_names and 'bespoke build' hints at bespoke. estimate_id and layout_objective are not explained, leaving a required parameter and a core layout option underspecified.

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

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

The description names a specific verb ('Order') and a resource ('what the estimate promised'), and clarifies the deliverable: library tools, a bespoke build, or both. It is distinguishable from siblings like request_estimate and review_estimate by placing the action after review, though it is somewhat cryptic.

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 'after reviewing it' gives a rough temporal condition, but there is no explicit guidance on when to use this tool versus alternatives like rerun_package, adjust_estimate, or review_estimate. No when-not-to-use conditions or alternative tool names 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying the return contents (status, runs, report link), but it does not disclose details like whether the report link is only present after delivery or how status values are represented. This is acceptable given 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 a single, compact sentence that front-loads the action ('Read an analytics package back') and then lists the key return elements. Every word earns its place, and there is no redundancy with the schema or annotations.

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

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

For a simple read tool with one parameter, strong safety annotations, and no output schema, the description covers the essential return values. It could be slightly more explicit about the package_id parameter mapping, but the overall context is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the single parameter package_id. The description names the resource ('an analytics package') but does not explicitly state that package_id identifies which package to read. However, with only one required parameter and a clear resource name, the meaning is easily inferred. 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 ('Read') and resource ('an analytics package'), and clearly enumerates what is returned: status, every run under it, and the report link once delivered. This distinguishes it from siblings like rerun_package (which mutates) and build_status (which likely reports a different build/package 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 implies a read-only status-checking use case, and the readOnlyHint/idempotentHint annotations reinforce that it is safe to call for checking package status. It does not explicitly name alternatives or exclusions, but the context of siblings like rerun_package and order_analytics_package makes the intended use 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds one genuinely new behavioral fact — results render inline in chat rather than as a data payload — but says nothing about pagination, card counts, or card-level filtering.

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 front-loaded sentence with zero filler; the resource and its clarifying examples come before any other 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 one-parameter, read-only browse tool with no output schema, the description adequately conveys what is fetched and how it is surfaced. It stops just short of noting whether all cards are returned at once or how a large report's cards are delivered.

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?

There is only one parameter and schema description coverage is 100%, with the schema itself noting the id comes from path_tool_run or build_status. The description adds no meaning beyond the schema, 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 (Browse) and resource (a delivered report's individual cards), and the parenthetical '(charts, tables, insights)' concretely defines what a card is. It does not, however, differentiate itself from close siblings such as reports_view or reports_list.

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 word 'delivered' hints that a report must already exist, but the description gives no explicit when-to-use guidance, no prerequisite on obtaining a processing_id, and no routing advice versus reports_view/reports_list. Usage is left entirely 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 already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds that results include status and links, giving a bit of output context. It doesn't contradict annotations, but it offers only modest additional behavioral detail beyond what annotations provide.

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

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

Two compact sentences with no filler. The core purpose is front-loaded, followed immediately by the optional search usage. Every word earns its place, and the structure makes it easy to scan.

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 with no required parameters and no output schema, the description covers the main purpose and the optional search. It omits potential details like pagination or default limit, but those are minor given the tool's simplicity. It is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%: both limit and semantic_query have descriptions. The description re-emphasizes semantic_query but adds nothing about limit or parameter interaction. Baseline of 3 is appropriate since the schema already documents the parameters adequately.

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 all reports with status and links, using a friendly 'your report library' framing. It also introduces the semantic_query search capability. However, it doesn't explicitly differentiate from siblings like reports_view or report_cards, though the list-oriented purpose is evident.

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 tells when to use semantic_query (for natural-language content search) but gives no guidance on when to use this tool versus alternative report tools. Usage context is implied rather than explicitly stated, and no exclusions or alternative routing 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, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds a genuinely non-obvious behavioral trait beyond them: the returned link is viewable without authentication, which is security-relevant information an agent cannot get from the annotations. It omits link expiry/persistence, so not a full 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?

A single front-loaded sentence with zero filler; the verb, the output, and the key constraint all appear immediately.

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 read-only tool with full annotation coverage, one documented parameter, and no output schema, the description is nearly sufficient – it states what is returned and the auth posture. Only the lifetime/durability of the generated link is left 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?

Only one parameter and schema coverage is 100%, so the baseline is 3. The description adds no meaning about processing_id (source tools are documented in the schema itself), so it neither compensates nor detracts.

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

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

The description names a specific action and resource: producing a shareable browser link for a report. It is clearly distinct from sibling reports_list (which enumerates reports) and report_cards, though it never explicitly contrasts itself with them.

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 stated outcome (a shareable, no-auth link) implicitly signals when to reach for this tool rather than an authenticated view or reports_list, but there is no explicit when/when-not statement or named alternative. Usage must be inferred from the effect it produces.

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

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

With no positive annotations, the description carries the behavioral disclosure burden. It adds useful traits: free, roughly 30 seconds, provisional/sample-based output, a package layout, and a page link. It does not explicitly state whether a record or draft is persisted, so it stops 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?

The entire definition is two compact, information-dense sentences with no filler. Every phrase earns its place: timing, cost, output shape, page link, and the next tool to call.

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

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

Given there is no output schema, the description usefully describes what will be returned: a rough answer, sample, package layout, and page link. The workflow with review_estimate is also covered. It omits no critical choice point for this first-step tool, though some optional-parameter behavior is left to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters and the baseline is 3. The description lightly maps "new question" to objective and "sample" to dataset_ref, but adds no added semantics for tool_names or layout_objective.

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 "START HERE for a new question," making both the action and the entry-point role explicit. It names the concrete deliverables: a rough answer over a sample, the complete package layout, section labels tied to the question, and a page link. It also distinguishes itself from review_estimate by calling that tool the next step.

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?

"START HERE" and "for a new question" explicitly state when this tool should be invoked before alternatives. "Then review_estimate with the user" provides the follow-up path and makes the boundary with review_estimate 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 provide no behavioral hints (all false), so the description carries the full burden. It discloses that the tool creates a new package with its own link, implying the original package is not modified. However, it does not mention side effects, resource consumption, or whether the operation is idempotent. This is partial transparency but leaves gaps.

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 that front-loads the primary action ('Run a delivered package again') and packs essential details without waste. Every clause adds value, and the structure is clear and scannable.

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

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

Given the simple two-parameter schema and lack of output schema, the description covers the core purpose and outcome (new package with its own link). It does not mention prerequisites (e.g., package must be delivered) or error conditions, but for a straightforward rerun operation, it is fairly complete. Minor gaps remain around parameter constraints and execution behavior.

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

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

Schema description coverage is 0%, so the description must compensate. It hints at dataset_ref by saying 'on its own data or new data,' but does not explicitly map dataset_ref to 'new data' or explain its format. package_id is not mentioned at all, though it is required. The description adds some meaning but does not fully clarify 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?

The description clearly states the action: 'Run a delivered package again' and specifies the outcome: 'as a new package with its own link.' This distinguishes it from sibling tools like run_analysis or modify_analysis, which serve different purposes. The verb 'run' and resource 'delivered package' are specific and 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 implies the usage scenario: when you want to rerun an existing delivered package, either on its original data or with new data. It does not explicitly mention alternatives or when not to use this tool, but the context is clear enough for an agent to infer the appropriate use case. Lacks explicit exclusions like 'if you need to modify the package, use modify_analysis.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds useful content context (a marked sample answer, per-place questions, page link, review checklist), but says nothing about auth needs, pagination, or whether a missing estimate_id errors — modest value 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?

It is short and front-loads the core idea, but the embedded list of returned items is crammed into a single run-on sentence, and the trailing 'Before path_bespoke' fragment is telegraphic. Readable but not cleanly 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?

With no output schema, the description does useful work enumerating what comes back (question as understood, marked sample answer, places, page link, checklist). It leaves the sole input parameter and any error/empty-state behavior unexplained, so it is only partially complete for the tool.

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

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

Schema description coverage is 0% and the single required parameter estimate_id is never mentioned in the description. With one undocumented parameter, the description should carry the burden, but it only alludes to 'the estimate' without explaining the identifier's format or source.

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 identifies the resource (an estimate) and frames it as the review-oriented view 'as you review it WITH the user,' which loosely separates it from request_estimate and adjust_estimate. However, it is written as a noun phrase describing the payload rather than a clear verb+resource statement of what the tool does, so the action itself is only implied.

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?

'Before path_bespoke' supplies a workflow-ordering cue, telling the agent this precedes a later step. There is no statement of when NOT to use it and no comparison against the obvious alternatives (request_estimate, adjust_estimate), so the guidance is implied rather than 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 indicate this tool is not read-only (readOnlyHint=false), implying it has side effects. The description does not mention side effects such as writing results to the user's workspace or making the report shareable, which likely creates objects. It does state the output is an interactive report URL, which is useful, but it doesn't disclose that the run may be persisted or have costs.

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 conveys the main purpose and output type. It is concise without fluff. The reading is front-loaded with the main action and the output benefit. The note about 'tools_schema' is integrated naturally.

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 moderately complex with nested objects and abstract parameters like 'column_mapping' and 'module_parameters'. The description points to 'tools_schema' for these, which is helpful. However, it does not explain the relationship to estimates (estimate_id) or how the output report integrates with the system. It is adequate but could carry more context.

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

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

Schema coverage is 100%, so parameters are documented. The description adds the important note to call 'tools_schema' for analysis-specific details within taskList.inputs. It does not add extra meaning beyond this, but the schema covers the basics. 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 states that the tool runs an analysis and returns a shareable report URL, which is clear in purpose. However, it is not specific enough to distinguish it from siblings like 'create_analysis' or 'modify_analysis'—the description does not mention that the tool executes an existing analysis definition, while create_analysis may set one up.

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 says to call 'tools_schema' first for analysis-specific fields, which is a usage hint. However, there is no guidance on when to use this tool versus 'create_analysis', 'modify_analysis', or 'rerun_package'. The distinction between these is not addressed.

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 flag destructiveHint=true, so the description does not need to restate that. It adds useful behavioral context beyond the schema: reports are emailed after each run, and create requires a re-runnable reference (connector:// or https://). There is no contradiction between the description and 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 a single compact sentence with the main purpose front-loaded. It packs a lot of useful information without redundancy, though the parenthetical list is slightly dense.

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

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

The description covers the main actions and some create-specific details, but there is no output schema and no explanation of what 'list' returns or how schedule_id is obtained other than indirectly via the schema. For a multi-action tool with a nested object parameter, this leaves some operational ambiguity.

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 67% schema description coverage, the schema handles some parameters, and the description adds meaning for action values, cadence (weekly/monthly), and dataset_ref (connector:// or https://). However, tool_name, schedule_id, and especially column_mapping receive no additional explanation in the description, leaving gaps for an agent to infer.

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

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

The description states the resource ('standing re-runs of analyses you own') and the specific verbs/actions ('create', 'list', 'cancel'). It clearly distinguishes this tool from one-off execution tools like run_analysis by emphasizing 'standing re-runs'.

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 implies the tool is for recurring, scheduled re-runs and mentions weekly/monthly cadences, but it never explicitly contrasts with alternatives such as run_analysis or rerun_package, nor states when not to use this tool. The usage context is present but the guidance against/versus alternatives 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds a sequencing dependency, but says nothing about what the returned schema contains or how to interpret it, which is the tool's entire 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?

Two short sentences with the action first and the mandatory sequencing constraint second. Zero 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?

There is no output schema, and for a tool whose sole job is returning a schema, the description does not hint at the returned structure or how the agent should consume it. The prerequisite note covers workflow but leaves the payoff of the call undescribed.

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 tool_name parameter is documented in the schema as the analysis name. The description adds no syntax, format, or naming detail beyond that, 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 (Get) and resource (analysis's parameter schema) with clear scope. It does not explicitly differentiate itself from siblings like discover_tools or check_tool_fit, but the purpose is unambiguous on its own.

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 imperative prerequisite: 'ALWAYS call before path_tool_run.' That is strong when-to-use guidance. It lacks a when-not clause or named alternative, keeping it below a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description isn't required to repeat safety traits. It does add a condition: 'Requires warehouse enablement (business plans),' which is useful operational context. However, it doesn't disclose other behaviors like rate limits or error handling, which is a gap given the tool's multi-action nature.

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 main verb and resource, followed by a compact list of capabilities and a constraint. There is no filler or repetition. Slightly more organization (e.g., separating capabilities from prerequisites) could make it a 5, but it is already efficient.

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

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

The description gives a solid high-level overview of the tool's purpose and use cases, and it mentions the prerequisite. However, it omits details about the 'params' and 'question' fields, and doesn't explain the distinction between 'query' and 'question'. Given the tool's multiple actions and 4 parameters with no output schema, this leaves the agent partially blind about how to use each action effectively.

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 bears full responsibility for explaining parameters. It maps some action enum values (catalog→browse, find→semantically find, ask→plain-language ask, queries→named templates) indirectly, but it never clarifies the purpose of 'query', 'params', or 'question'. This partial mapping is insufficient for an agent to construct correct invocations.

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 primary function: 'Query your org's data warehouse free.' It enumerates specific capabilities (browse catalog, semantically find data, plain-language ask, named templates) that distinguish it from generic query tools. However, it does not name any sibling tool or explicitly contrast itself, so it stops short of a 5.

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 a usage scenario (querying the warehouse) but offers no explicit guidance on when to use this tool vs. alternatives like ask_library or run_analysis. It mentions a requirement (warehouse enablement) but lacks 'use this instead of X' or 'do not use when...' instructions. The agent is left to infer suitability.

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