Phasio

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 valuable behavioral context beyond that: default exclusion of voided/deleted rows, the line-item scoping caveat, and the default sort/limit behavior (desc, 20). It does not describe the exact return shape, but with no output schema and a read-only aggregation tool, the added context 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 dense but well-organized: the core operation and examples come first, followed by the scoping caveat and dataset list. The dataset list is long but necessary since the schema repeats it and the tool needs valid entity names. Every sentence earns its place, though the list could arguably be trimmed by pointing to describeQueryableFields.

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 aggregation tool with 7 parameters and no output schema, the description covers the key decision points: which metric needs which field, how grouping works, how filtering works, and the voided/deleted scoping caveat. It does not describe the response format, but for an aggregation tool the return shape is fairly predictable and the description already points to describeQueryableFields for field discovery.

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 every parameter. The description adds meaning by explaining the metric-field relationship ('field required for all metrics except count'), giving a concrete groupBy/filter example, and clarifying that omitting groupBy yields a single total. It also points to describeQueryableFields for valid field names, which is useful cross-tool 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 opens with a specific verb and resource ('Aggregate a dataset') and immediately enumerates the supported operations (sum/avg/count/min/max), optional grouping, and optional filtering. It also names concrete use cases (highest-value customers, revenue by process) and lists the valid datasets, which distinguishes it from sibling tools like query and explainPrice.

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

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

The description explicitly says when to use this tool ('Use this for cross-cutting questions like...') and gives a concrete example with parameters. It also warns about a subtle scoping issue: datasets with a voided/deleted flag exclude those rows by default, and line-item datasets like requisition are NOT scoped by parent order status, so the agent must filter explicitly. This is exactly the kind of when/why guidance an agent needs.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description aligns with that. It adds value by stating the operation is irreversible and by explaining that each entity has its own refusal rules (e.g., live pricing equation), which is 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 sentences, front-loaded with the action and entity list, and includes the critical irreversibility warning immediately. No wasted words.

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

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

For a destructive tool with two parameters and no output schema, the description covers the core operation, entity set, irreversibility, and refusal mechanism. It does not mention the return value or error handling, but these are not strictly necessary for a delete operation given the annotations and simple parameter set.

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% (both 'entity' and 'id' have descriptions). The description adds a note that the server validates the entity value and that describeDataModel names the current writable set, which is a minor enhancement but does not materially expand on parameter semantics beyond the schema.

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

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

The description states a specific verb ('Delete') and resource ('one row of a writable entity') and enumerates the exact entities it applies to. This clearly distinguishes it from sibling tools like 'save' or 'update' by specifying the operation and scope.

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

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

The description provides clear context for when to use it (to delete a row) and cautions about irreversibility and entity-specific refusals, referencing describeQueryableFields for details. It does not explicitly name alternative tools or exclusion conditions, but the context is sufficient for an agent to decide.

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 context that these are operator-level settings with 'no dataset' and that section limits the output, but it does not address return format or pagination. No contradiction with annotations.

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

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

The first sentence is dense but information-rich, enumerating coverage areas without filler. The two follow-up sentences are crisp and provide usage and routing. Minor redundancy with the schema's section list prevents a 5.

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

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

Given no output schema, the description covers all major content areas and explains how to scope a read. It doesn't specify the exact return envelope or formatting, but for a read-only describe tool with one optional parameter, that is a minor 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 description covers 100% of the single parameter, including the list of section values and the default behavior of omitting section. The description's 'Pass section to read one part' adds no new semantic detail beyond the schema.

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

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

The opening phrase 'Describe the manufacturer's setup' names a specific verb and resource, then enumerates the content scope clearly. It also distinguishes itself from row-level and lint tools by naming query and lintConfiguration, so an agent can tell it apart from siblings.

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

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

The description explicitly says to pass 'section' to read one part, and gives clear routing rules: use query(entity=...) for row-level detail and lintConfiguration for setup problems. This provides both when-to-use and when-not-to-use 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 safe read-only nature is fully covered by structured data. The description adds no additional behavioral context such as authentication or rate limits, but none is needed here; it provides conceptual rather than behavioral transparency.

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

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

Two sentences, each earning its place: the first defines the tool's content and structure, the second gives a precise invocation directive. The description is information-dense 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 an introductory, zero-parameter, read-only explanatory tool, the description is complete. It tells the agent exactly what will be learned, how datasets relate, and when to call it first, without needing to document parameters or return formats.

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

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

The tool has zero parameters and the input schema is empty with 100% schema description coverage, so no parameter documentation is required. The description correctly avoids inventing parameter details, and the baseline for a zero-parameter tool is satisfied.

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 a specific verb ('Explain') and resource ('the manufacturer's data model'), and details the content: what each query dataset means and how they relate. The part -> specification -> requisition -> order chain with production and pricing distinguishes this from sibling tools like describeQueryableFields and describeConfiguration.

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 instruction 'Call this first to understand how to traverse between datasets' gives explicit usage context and temporal placement among sibling tools. It does not name alternatives or exclusions, but the 'first' guidance is strong enough for an agent to know when to use it.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds that it returns the contract and optionally the live source or a specific version, and explains the workflow loop. It does not contradict the annotations and provides useful context beyond the safety flags, such as the fact that it returns source only when requested.

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 dense paragraph but front-loads the critical instruction ('Start here') and then enumerates the contract and workflow. While long, every sentence adds value—no filler. It could be broken into bullets, but the structure is logical and 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?

With no output schema, the description must explain what the tool returns, which it does thoroughly by listing contract components and explaining the workflow. It also covers optional parameters and their effects. For a complex tool that serves as an entry point, this is complete.

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

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

The schema covers all four parameters with detailed descriptions, so the baseline is 3. The description adds value by explaining the interplay: 'Pass includeSource=true to also get the live equation's source, or equationId=<id> to get the source of one specific version' and clarifying ownerId omission for ORDER scope. This goes beyond the schema's individual parameter descriptions.

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 before reading, writing or changing a pricing equation,' immediately establishing its role as an entry point. It clearly states it 'Returns the TypeScript contract the equation runs against' and enumerates the contract contents, which is a specific verb and resource. This distinguishes it from sibling tools like save, generateQuote, and publishEquation, which are part of the workflow it describes.

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

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

It explicitly says to start here before any other pricing-equation operation, then outlines the sequence: save to validate, generateQuote to test, and publishEquation only on explicit request. It also clarifies when to use includeSource and equationId, and that ownerId is omitted for ORDER scope. This gives clear when-to-use and alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description aligns with that. It adds valuable conditional behavior: writable entities also get save/delete field info, while write-only entities like operatorSettings only get the save-related fields. This goes 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 tightly written sentences with no filler. The main purpose is front-loaded, and the conditional behavior is stated compactly. Every clause earns its place.

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

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

For a single-parameter, read-only describe tool with no output schema, the description fully covers what the tool returns: filterable fields, enum values, save() fields, delete() refusal fields, and the write-only exception. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% for the single entity parameter, so the baseline is 3. The description adds meaning beyond the schema by explaining entity categories ('writable entity', 'write-only entity'), giving operatorSettings as an example, and tying the parameter to RSQL filtering and save/delete behavior.

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: 'List the filterable fields (and enum values) for a query dataset.' It states the purpose ('so you can build a valid RSQL filter') and further distinguishes itself by covering save() accepted fields and delete() refused fields, making it clear how this differs from sibling describe tools.

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

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

The description gives clear usage context: use it to construct RSQL filters for query datasets, and for writable entities to learn what save() and delete() accept or refuse. It does not explicitly name alternatives or say when not to use it, but the intended scenarios are well implied.

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

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

The description goes well beyond the annotations. While annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds critical behavioral context: it recomputes the price from actual configuration, returns a price breakdown plus pricing-equation variables, compares against stored quotedPrice to flag staleness, and warns that individual variables may be manually overridden. This is rich behavioral disclosure that the annotations alone do not 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?

The description is a single dense paragraph that front-loads the core purpose and then provides necessary detail about overrides and reconciliation. It is not overly long given the complexity of the tool's behavior. It could arguably be split into clearer sections, but every sentence earns its place and the structure is logical: purpose, behavior, caveat, reconciliation guidance, alternative.

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 rich behavioral complexity, the description is remarkably complete. It explains what the tool does, what it returns, how to interpret the results, how to reconcile against other tools, and when to use a different tool. There is no obvious missing information that an agent would need to call this tool correctly.

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

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

The schema already provides 100% coverage for the single parameter requisitionId, including a description of how to query it. The tool description doesn't need to add much parameter-level detail. It does add context by explaining that the requisition is an existing order line, which reinforces the parameter's meaning. Since the schema covers the parameter fully, a baseline of 3 applies, and the description's contextual reinforcement earns a 4.

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

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

The description opens with a specific verb and resource: 'Explain why an existing requisition (order line) costs what it does.' It then distinguishes itself from the sibling generateQuote by explicitly stating that hypothetical/what-if parts should use generateQuote instead. This makes the tool's purpose unmistakable and clearly differentiates it from related tools.

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

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

The description provides explicit guidance on when to use this tool versus alternatives. It states that for hypothetical or what-if parts, one should use generateQuote instead. It also gives a detailed reconciliation workflow, telling the agent to examine variables against describePricingEquationApi(includeSource=true) and query materialPrices. This is exactly the kind of when-to-use and how-to-use guidance that helps an agent select and invoke the tool correctly.

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

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

Adds meaningful behavioral context beyond the readOnlyHint and idempotentHint annotations: it explains rotation/scale invariance, the numeric distance scale (0 to ~1.414), and a rule of thumb for near-duplicates. No contradictions with annotations.

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

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

Well-structured with the purpose stated first, followed by the similarity metric, threshold guidance, and prerequisite. Every sentence provides essential information without fluff, making it easy for an agent to parse.

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 sufficiently explains what to expect (similar parts) and how to interpret distances, plus provides a threshold. It covers the input requirement and the core semantics, making it complete for a read-only tool. The annotations already handle safety.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter semantics by explaining the meaning of maxDistance (distance cut-off, with ~0.05 for near-duplicates) and ties it to the distance scale. It also gives guidance for obtaining partRevisionId via query, which is beyond the schema's simple 'UUID' 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?

Clearly states it finds part revisions most similar in shape, with a precise definition of similarity as a geometric distance. It also explicitly distinguishes itself from inspectPartRevision by noting that real dimensions are covered there, so an agent can tell them apart.

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

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

Provides concrete guidance on when to use it (shape/proportion matching) and when not to (if real dimensions are needed, use inspectPartRevision). Also explains the prerequisite (UUID) and how to obtain it via query(entity='partRevision').

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 true/false, lowering the bar. The description adds meaningful behavioral context beyond those flags: 'Purely a calculation — nothing is saved', plus how equationId tests non-live versions without persisting anything. No contradictions or hidden side effects are disclosed.

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 dense but every sentence earns its place: purpose, use cases, equationId testing workflow, no-side-effects guarantee, and sibling routing. It is front-loaded with the primary action and contains no filler or repetition of the input schema.

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

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

For a 14-parameter tool with no output schema, the description covers the essential context: what it returns, when to use it, how to test equations, that nothing is persisted, and which sibling handles the existing-order case. With 100% schema parameter coverage handling the field details, nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns higher by adding semantics for equationId (non-live version from save(entity=typescriptEquation), comparison workflow) and variables ('Changes the equation's inputs, never its formula'). This adds meaning beyond the schema's field-level text, especially for the trickier parameters.

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 concrete verb and resource: 'Price a part configuration on demand and return the price breakdown plus the pricing-equation variables.' It clearly distinguishes the tool from explainPrice by positioning generateQuote for un-ordered parts or hypothetical changes, not existing order lines.

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

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

It gives explicit when-to-use guidance ('Use for a part not yet ordered, or to test a change'), a concrete test procedure (call once with equationId and once without to compare against live), and names the sibling alternative for the opposite case: 'To explain the price of an EXISTING order line, use explainPrice instead.'

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 beyond annotations by specifying that results are scoped to one customer organisation and listing what is returned, without contradicting any annotation.

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

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

The description is two sentences with no filler: the first sentence states scope and enumerates what is returned, and the second provides a concrete use-case question. Every clause adds useful 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, one-parameter tool with no output schema, the description is complete: it identifies the required input, defines the scope precisely, and explains the return contents well enough for an agent to know what to expect. No additional context is 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 input schema already documents customerOrganisationId fully at 100% coverage, including its type and semantic reference. The description reinforces the parameter by mapping it to 'customer X' in the use-case sentence, but adds no new parameter-level detail beyond what the schema 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 opens with a specific verb and resource: 'Return the pricing configured specifically for one customer organisation.' It clearly contrasts this with storefront defaults and enumerates the exact types of overrides included, making the tool's purpose unambiguous and distinct from broad pricing tools.

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

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

The description explicitly states when to use it: 'Use it to answer "does customer X have special pricing?"' It also establishes the boundary against storefront defaults. It does not explicitly name alternative sibling tools, but for a single-purpose getter the usage context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds value by explaining exactly what data is returned (type, language, page size, HTML content) and the scope (for confirmations, invoices, estimates, etc.), which is behavioral context beyond the annotations. It does not mention error handling or rate limits, but for a simple read operation this is sufficient.

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 no filler. The primary purpose is front-loaded, followed by a precise retrieval hint. Every word earns its place, and the structure helps an agent parse the information quickly.

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 tool with strong annotations and a clear schema, the description covers the purpose, the key data returned, and how to obtain the required ID. It does not describe the exact output format (e.g., JSON structure), but since there is no output schema and the listed fields are intuitive, this is a minor gap. Error conditions are also not mentioned, but the read-only, idempotent nature minimizes risk.

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 already fully explains the documentTemplateId parameter (integer, the template's ID, found via query). The description reinforces this by mentioning query, but does not add any new semantics about the parameter. With 100% schema coverage, a baseline of 3 is appropriate; the description does not further enrich parameter understanding.

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 (Return), the resource (document template), and the specific content (type, language, page size, HTML content). It also differentiates from query by indicating this returns the full template rather than a list. The purpose is unmistakable and distinct from siblings like query or delete.

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

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

The description provides practical usage guidance by instructing the agent to first list templates with query(entity='documentTemplate') to obtain the ID. This establishes a clear workflow. However, it does not explicitly state when to prefer this over alternatives (e.g., 'use this to get full details, not query'), though the intent is obvious. Slight gap in explicit alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the read-only safety profile. The description adds value by specifying the exact return content—status and completion time per onboarding step—and the relationship to lintConfiguration findings, which is behaviorally useful beyond the annotations.

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

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

The description is a single front-loaded sentence that begins with the core action and then provides a complete list of steps without redundancy or filler. Every element earns its place, including the useful lintConfiguration tie-in.

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 parameters, the description carries the burden of explaining return semantics and it does so adequately: it names all steps and the fields returned (status, completion time). It could add details about status value formats or how to interpret missing steps, but the current information is sufficient for most calling contexts.

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

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

The tool has zero parameters, so there is nothing for the description to add about parameter meanings. The description focuses on what is returned, which is appropriately aligned with the empty input 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 uses a specific verb ('Return') and a precise resource ('manufacturer's onboarding-wizard progress'), enumerating the exact steps returned. This clearly separates it from siblings like getProductionProgress, which concerns production rather than onboarding.

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

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

The description makes the use case clear: it returns onboarding step statuses and completion times, and explicitly links to lintConfiguration findings by noting those findings reference these step ids. It does not explicitly mention alternatives or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds useful behavioral context by detailing what the output contains (log of moves, scrap events with reasons, and impacted requisitions). It does not contradict annotations and provides enough insight into the tool's 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?

The description is dense but efficient. The first sentence packs the core purpose and output, and the second sentence gives usage guidance. It is slightly long but every clause adds value, so it earns a 4 rather than a 5.

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

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

For a tool with no output schema, the description clearly explains what the return includes (chronological log, scrap reasons, impacted requisitions). It also explains how to obtain the input, the scope, and alternatives. An agent has everything needed to call it correctly without further research.

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 only parameter, requisitionId, has a schema description that already explains it and how to find it. The tool description repeats that hint without adding new meaning. Since schema coverage is 100%, the baseline is 3, and the description does not elevate it further.

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

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

The description clearly states the tool's function: it returns a chronological log of batch moves and scrap events for a single requisition, including scrap reasons and other impacted requisitions. It explicitly distinguishes itself from siblings like query and aggregate by scoping to one requisition.

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

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

The description explicitly states when to use this tool versus alternatives: for single-requisition history, and explicitly says to use query/aggregate for shop-floor-level scrap analysis, and warns not to loop this tool over requisitions. This is unambiguous and 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavioral context by specifying that results are current quantities at each production step and that ordering follows the routing sequence, which is not available from annotations.

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

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

The description is two sentences with no wasted words. The core behavior is front-loaded, and the prerequisite lookup instruction earns its place.

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

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

For a single-parameter read-only tool, the description covers what is returned, how results are ordered, and how to obtain the required id. It does not specify the output structure, but the high-level return content is adequately described.

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

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

The single parameter requisitionId is fully documented in the schema, including how to find it via query. The description repeats this hint but adds little beyond the schema, so the baseline of 3 applies.

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

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

The description clearly identifies the resource (a requisition's parts) and the specific information returned (quantities at each production step/operation, in routing order). The phrase 'right now' helps distinguish it from getProductionHistory. Although no explicit verb like 'retrieve' appears, the intent is 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 gives a clear prerequisite: find a requisition id via query(entity="requisition"). However, it does not explicitly state when to prefer this tool over siblings such as getProductionHistory or query, leaving the selection context mostly implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral detail beyond annotations by specifying exactly what is returned: the metric list and the image with six orthographic views, which helps the agent understand the tool's output shape and side-effect-free 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?

Two sentences front-load the core purpose and output, then give usage guidance and the input requirement. There is no filler and every sentence earns its place.

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

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

For a single-parameter read-only tool with no output schema, the description fully covers what the tool returns, what questions it answers, and what input is required. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the single parameter partRevisionId is already described as 'The UUID of the part revision to inspect.' The description only restates that a UUID is required, adding no new semantics 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?

The description opens with a specific verb and resource: 'Inspect a single part revision' and then enumerates the exact outputs: geometric metrics and a labelled six-view image. This clearly differentiates it from siblings like findSimilarParts or query by stating the resource and result set.

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

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

The description explicitly says 'Use this to answer any question about a part's geometry, manufacturability, size, or appearance,' giving clear when-to-use context. It does not name alternative tools or exclusion conditions, but the stated use case is strong enough for an agent to route correctly.

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, so the safety profile is covered. The description adds useful behavioral detail beyond annotations by specifying that findings are categorized by severity and that each finding names the onboarding step and entity involved.

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

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

The description is front-loaded with the core purpose and then provides structured severity definitions. Every sentence earns its place: the severity taxonomy, the finding content note, and the usage trigger are all directly useful for correct invocation.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains what the tool does, what findings contain, and when to call it, while annotations cover the read-only, idempotent, non-destructive 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?

The schema already documents the single optional 'level' parameter and its default, so baseline credit applies. The description adds semantic weight by defining what BLOCKER, WARNING, and INFO actually mean and what types of issues fall into each category.

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 action and resource: 'Check the manufacturer's setup for problems' and report them by severity. It defines BLOCKER, WARNING, and INFO with concrete conditions, making it clear this is a validation/linting tool rather than a describe or query tool. It also ties the purpose to setup completeness and quoting failures, which distinguishes it from siblings.

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

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

The description gives an explicit trigger: 'Call this first when asked whether the setup is complete or why quoting fails.' This clearly tells an agent when to use the tool, but it does not explicitly mention when not to use it or name any alternative sibling tools.

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 set destructiveHint=true and readOnlyHint=false, but the description adds critical context: it changes live prices immediately, stops the previous version from pricing, requires confirm=true and replacesLiveEquationId, explains the reversal (republish previous version), and clarifies that a new version prices nothing before publishing. This goes well beyond annotations, covering side effects, prerequisites, and recovery.

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 dense but every sentence earns its place: it front-loads the sensitive nature, lists prerequisites, testing, alternatives, reversal, and the alternative save action. It is structured logically and avoids filler. Length is justified by the complexity and risk of the operation.

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

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

For a mutation tool with no output schema and high risk, the description covers prerequisites, exact side effects, how to verify the current live version, reversal strategy, and a non-destructive alternative. Nothing an agent needs to call it safely and correctly is missing.

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

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

The input schema already documents all three parameters at 100% coverage, so baseline is 3. The description adds extra semantics: the meaning of 'NONE' for replacesLiveEquationId, the instruction to query the current live id first, and that a mismatch is refused. It also ties confirm to the prerequisite testing. These additions add real value beyond the schema descriptions.

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 precise verb ('makes ... the LIVE pricing equation') with a specific resource (typescriptEquation version) and scope (its process, post-processing, or order level). Clearly distinguishes from generateQuote (testing) and save (alternative action) by naming them. An agent can tell exactly what this tool does and what it does not do.

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

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

Provides explicit when-to-use (only after manufacturer request, testing with generateQuote on real parts, and informing the manufacturer) and when-not-to-use (never for 'try it out', instead use generateQuote). Names the alternative action (save with isLive: true) and the prerequisite of reading the current live id. This is exemplary 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?

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so with that bar lowered the description adds genuine behavioral detail beyond them: rows return as 'field=value' pairs, always include id and foreign keys, fields selects columns but id/FK stay included, limit defaults to 20, and filter combines with ';'=AND / ','=OR. No contradiction with any annotation.

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

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

Purpose is front-loaded and the body is consistently organized dataset-by-dataset with a parallel structure, which is a strength. However, the description runs several thousand words; while each parenthetical adds semantic value, the aggregate length strains an agent scanning for selection and pushes against 'every sentence earns its place.' Dense and defensible, but heavy for orientation.

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?

Exceptionally complete for a 29-dataset query tool with 100% schema coverage and no output schema: it covers dataset semantics, operator set, result format, default limit, and routes deeper access to describeQueryableFields, describeDataModel, describePricingEquationApi, inspectPartRevision, and explainPrice instead of duplicating exhaustive field lists. Nothing needed to pick a dataset or compose a filter is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds the tool's real value: semantic distinctions the schema's enum list cannot convey — price vs localPrice for cross-currency revenue, requisition.name vs partRevision.designName for user reference matching, source INBOUND/OUTBOUND for channel splits, materialPrices 'variables' not being filterable, and the price vs quotedPrice staleness note. The RSQL operator syntax is also expanded well beyond the schema's single example.

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

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

The opening sentence states a specific verb (query), resource (manufacturer's live data), and mechanism (RSQL filter), making the tool's role unambiguous before the 29-dataset enumeration. It also delimits what it is not by pointing to describeDataModel and describeQueryableFields, and it is clearly distinct from sibling aggregate (aggregation) and the various describe/lint/save tools.

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

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

Routing guidance is explicit and recurring: 'do not gather scrap by iterating requisitions or getProductionHistory' tells the agent to query scrap directly; 'Rates are NOT here — query materialPrices (materialId==<id>)' redirects to the correct dataset; every typescriptEquation/postProcessing points to describePricingEquationApi(includeSource=true) for live source; stale quotedPrice is handled via 'use explainPrice to recompute'; and describeQueryableFields/describeDataModel are named for field and relationship questions. These are concrete when-vs-alternative decisions, not vague context.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds valuable context that some updates change live behavior at once and that the reply signals such events, which goes 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?

Two sentences with zero fluff. The create/update distinction and entity list are front-loaded, and the behavioral caution is placed at the end. Every sentence earns its place.

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

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

For a write tool with no output schema, the description covers operation semantics, entity scope, field lookup, and a behavioral caveat about live changes. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and each property has a meaningful description (entity lists allowed values, data explains to call describeQueryableFields, id explains create/update distinction). The description adds no new parameter-level semantics beyond what the schema provides, so baseline 3 applies.

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

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

The description states a clear verb (create/update), a specific resource (one row of a writable entity), and enumerates the entity list. It distinguishes itself from siblings like delete, query, and publishEquation by focusing on the create/update write operation.

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

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

It gives explicit guidance on when to create vs update (presence of id) and points to describeQueryableFields for field rules. It does not name alternative tools or exclusion criteria, but the operation is self-explanatory and the reference to describeQueryableFields serves as a helper.

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