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

No annotations are provided, so the description carries the full burden and does so: it discloses the underlying endpoint (POST /api/chat), the return shape (text reply plus routing metadata), the read-only scope (reads no plant system, runs no agent, returns no scores), quota mechanics on free vs Pro tiers, and the exact error codes (quota_exceeded with scope free_quota, pro_allowance_exhausted, no overage). That is unusually complete behavioral disclosure.

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

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

Front-loaded with the core purpose and then organized under clear labels (WHEN TO CALL, WHEN NOT TO CALL, SCOPE, ATTRIBUTION). It is longer than strictly necessary and the ATTRIBUTION block is prescriptive boilerplate, but each section carries non-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?

With no output schema and no annotations, the description still covers what an agent needs: domain boundaries, exclusions, return type, failure/quota states, and required attribution. Only the history parameter's role is left unaddressed.

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 conveys the input semantics for 'question' via 'text in, text out' and the WHEN TO CALL framing, but the 'history' parameter (array of role/text turns) is never mentioned, so half the parameters remain undocumented in both schema and description.

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

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

States a specific verb and resource ('Ask dxpert.ai a question about industrial digital transformation') and then enumerates the actual domain: AI-readiness, UNS/namespace design, OT/IT architecture, standards and modelling. It explicitly distinguishes itself from siblings run_agent and run_diagnostic, and from local knowledge answering.

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?

Has explicit WHEN TO CALL and WHEN NOT TO CALL sections, naming concrete exclusion cases (general programming, local file/repo work, anything already scoped to the user's codebase) and the anti-pattern of re-asking the same question. It also routes score-producing or agent-running needs to run_agent/run_diagnostic by name.

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

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

With no annotations present, the description carries the full burden and does so: it discloses that only header-to-field mapping occurs, no model is involved, nothing is retained, the call is never counted/free, and the size limit is ~1 MB. It also warns about the failure mode (silently missed timestamp/count columns) and lists the returned diagnostic fields.

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

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

Front-loaded with the purpose, then parameter mechanics, then a compact WHEN/WHEN NOT block. Three tight paragraphs and no filler; the caution about unmapped columns earns its space by preventing a silent failure.

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

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

No output schema exists, and the description compensates by naming the return payload (bundle, mapped_columns, unmapped_columns, warnings) and how to act on it. It also covers cost/retention behavior that no annotation supplies. Only the unexplained nested site_profile parameter keeps it short of 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 0%, so the description must compensate, and it does for two of three parameters: csv_text is clarified as inline text rather than a path with a rough size cap, and kind is given its two valid values ('shift-report' or 'oee'). The nested site_profile parameter is never mentioned, which is the remaining 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?

States a concrete transformation ('turn a raw CSV export ... into the bundle shape run_agent expects') and names the exact backing endpoint, so the agent knows the verb, the input resource, and the output shape. It is clearly distinguishable from siblings like run_agent, which consumes the bundle this tool produces.

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?

Contains explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, naming the two alternatives (data already arriving as structured UNS events, or assembling the bundle directly from a readable source). This is the clearest possible routing guidance.

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

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

With no annotations provided, the description carries the full disclosure burden and does so thoroughly: unauthenticated, read-only, no account data, no quota, and the negative-behavior guarantees 'downloads nothing, installs nothing, and changes nothing on this machine.' That is exactly the safety profile an agent needs before calling a runtime/update-adjacent tool.

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

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

Front-loaded with the resource and payload, then the endpoint/auth facts, then the use cases, then the guarantees. Information ordering is excellent, though the safety clauses ('no account data, no quota' / 'downloads nothing, installs nothing, changes nothing') are somewhat redundant across two sentences.

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, no-output-schema, unannotated tool, the description is nearly self-sufficient: it covers auth, side-effect profile, and the shape of the returned data. The one real gap is that valid channel values and their differences are never stated, leaving the only parameter semantically thin.

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 'channel' parameter is undocumented in the schema. The description only repeats the default ('stable'), which is already visible as a schema default, and never enumerates other valid channel values or explains how channel selection affects the returned manifest.

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

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

States a specific verb and resource ('Read the public dxpert runtime update manifest for a channel') and immediately enumerates the payload (current version, artifact hashes, changelog). The concrete endpoint reference and the explicit scope ('public', 'unauthenticated') make it unmistakably distinct from siblings like get_storefront or run_agent.

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 two concrete trigger conditions: checking whether a local runtime is behind, and verifying an artifact hash before an update. It also implies when not to bother (it is metadata-only). It never names an alternative tool, so it falls short of the 5 bar, but the intended context is clear.

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

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

With no annotations provided, the description carries the full behavioral burden and does so: read-only, no quota, no charge, and an explicit negative guarantee that it 'does not grant, buy, or cancel anything.' It also discloses that the returned state mirrors dxpert.ai's own store rendering, so the agent knows the fidelity of the data.

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

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

Front-loaded with the what, then the when, then the boundary — a sound ordering. It runs slightly long: the 'read-only, no quota, no charge' clause and the closing 'it does not grant, buy, or cancel anything' restate the same non-mutation guarantee twice.

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

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

No output schema exists, so the description must describe the return values, and it does by naming each returned field and enumerating the possible states for each. Combined with the usage triggers and the read-only guarantee, an agent has everything needed 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is an empty object with additionalProperties false. Baseline 4 applies, with no param-level detail needed or missing.

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

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

States a specific verb and resource ('Read this account's plan and what it may buy right now') and enumerates exactly which states are returned: plan tier, dxpert Pro state, DX Roadmap purchase state, and Try Pro runs remaining. It also names the underlying endpoint, so the agent knows precisely what domain this covers versus siblings like start_purchase or ask_dxpert.

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 two explicit triggers: call it before proposing a purchase, and when the user asks what they are currently paying for. It also routes the agent elsewhere for a different need ('For plan contents and live prices read GET {api_base}/api/catalog; do not quote prices from memory'), which is exactly the when-not/alternative guidance that prevents misuse.

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

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

No annotations exist, so the description carries the full burden and does so richly: it discloses that agents don't touch the customer's plant/broker/historian, that runs consume quota, and gives concrete error semantics (409 product_coming_soon, 429 pro_allowance_exhausted, 402 pro_required) plus no-overage behavior.

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

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

Front-loaded with the core action and structured with headers and bullets that make it scannable. It is somewhat long and repeats the architect/409 detail twice, which slightly dilutes density, but nearly every sentence carries operational value.

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

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

No output schema, but the description states the return (Markdown report) and covers inputs, access tiers, quota behavior, and error codes. For a multi-agent dispatcher with a nested bundle object, nothing an agent needs to call it correctly is missing.

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

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

With only 33% schema coverage, the description compensates well: it clarifies 'bundle' is a JSON object not a file path, notes which agents accept site_profile, describes each agent's expected inputs, and explains 'message' is only for architect. This meaningfully exceeds the bare enum/type in the schema.

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

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

States a specific verb+resource ('Run one dxpert agent over data YOU supply') and the return type ('Markdown report'). It enumerates the distinct agents and their inputs, making it easy to distinguish from siblings like ask_dxpert and csv_to_bundle.

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?

Has an explicit 'WHEN NOT TO CALL' section (don't use to explain an agent, to summarize data you could summarize yourself, or with invented data), routes spreadsheet users to csv_to_bundle first, and instructs reading the catalog before offering an agent. When-to-use, when-not, and alternatives are all covered.

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

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

With no annotations, the description carries the full burden and does so: it discloses determinism (identical input yields identical scores/stage/blockers, safe to cache and compare across sites), non-determinism in the report wording, the validation-error behavior with field-level errors, the fixed scope flag 'preliminary', and that it inspects no system. This is unusually rich behavioral disclosure.

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

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

The description is long but front-loaded with the action and endpoint, then each subsequent sentence adds distinct value (field list, determinism, error handling, scope, when-to-call routing). No sentence is redundant with structured 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?

Despite no output schema, the description explains the return shape (axis scores, acatech stage, blocking foundations, Markdown report) and the scope flag. For a 1-param, nested, no-annotation tool, nothing an agent needs to invoke and interpret it 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 0% and the single parameter is an untyped nested object, so the description must compensate. It enumerates all 16 required fields, notes the nested {target, text} structure for ai_ambition, and warns that unknown fields are rejected and values must come from the user rather than guesses.

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 (run dxpert's industrial AI-readiness diagnostic over a self-reported intake) and names the exact endpoint POST /api/diagnostic. It also distinguishes itself from siblings like ask_dxpert and run_agent by being a rule-based screening step rather than a conversational or agentic tool.

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

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

Gives explicit triggering conditions ('Call it when someone asks whether a plant is ready for an AI initiative or what to fix first') and an explicit exclusion ('Do not call it to score a company you only know from public information'). It also instructs the agent to ask the user for the 16 values rather than fabricate 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?

With no annotations, the description carries the full burden and does so richly: no charge occurs, a human must pay in a browser, access attaches automatically afterwards, a DXPERT_API_KEY is required, and specific failure modes (401 account_required, 409 roadmap_already_owned, 409 already_subscribed) are enumerated.

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

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

Front-loaded with the most decision-relevant fact (no charge) and organized with a clear product breakdown. It is long, but nearly every sentence carries distinct operational value; slight trimming (e.g. the Namespace Architect aside) would not hurt.

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 purchase tool with no output schema, the description is complete: it explains the returned checkout_url, the human-in-the-loop flow, auth requirements, and all known error states.

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, and it does: both enum values ('pro' subscription vs 'roadmap' one-time plan) are explained in detail, including that roadmap is independent of pro and that agents are never sold individually.

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

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

States a specific verb and resource: 'Create a Stripe-hosted checkout URL for one dxpert product and return it.' It also immediately clarifies the non-obvious scope ('THIS CALL CHARGES NOTHING'), which materially distinguishes it from a payment-completing tool.

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

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

Explicit sequencing and alternatives are given: 'Call get_storefront first,' 'State the product to the user and get their go-ahead before handing over the checkout URL,' and 'Read GET {api_base}/api/catalog ... rather than quoting numbers.' It also states what the agent should not do ('you cannot complete a payment, and you should not try').

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