Phasio

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

Annotations already establish that this is a safe, idempotent read, and the description goes well beyond them by disclosing two result-changing behaviors: datasets with a voided/deleted flag silently exclude those rows by default, and line-item datasets like requisition are NOT scoped by their parent order's status. Those are exactly the non-obvious traps that would otherwise produce quietly wrong revenue numbers, and it even points to the Scope line in describeQueryableFields.

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 half is well front-loaded and dense with value, but the 31-item dataset list consumes roughly a third of the text and simply repeats the `entity` property description verbatim from the schema — space that earns nothing. Removing it would shorten the description substantially without losing 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 seven parameters all documented, full schema coverage, and read-only annotations, the description covers the pieces an agent actually needs: valid metrics, how to find field names, and the scoping caveats that affect correctness. Return-shape detail is the only soft spot, and for an aggregate result (group keys plus metric value) its absence is low-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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning on top: groupBy can take one or more fields (omit for a single total), filter uses the same RSQL syntax as query, and field names must come from describeQueryableFields. The worked example with real field names (localPrice, customerOrganisationName) makes the metric/field/groupBy interaction concrete rather than abstract.

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 names a specific verb (aggregate) plus the exact metric set (sum/avg/count/min/max), optional grouping, and optional RSQL filter, so the operation is fully pinned down. It is clearly separable from the `query` sibling by being an aggregation rather than a row-returning read.

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

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

It supplies concrete use cases ('highest-value customers', 'revenue by process') plus a real invocation shape (metric=sum, field=localPrice, groupBy=[customerOrganisationName], filter="state==ORDER"), which tells the agent when this tool is the right pick. What is missing is an explicit negative case — e.g. 'use query instead when you need individual rows rather than totals' — so the boundary with `query` is only 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds real value on top: irreversibility, per-entity refusal logic, and a concrete example ('a live pricing equation is refused'), which is exactly the kind of behavioral nuance annotations cannot express.

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 action and scope, with the caution and refusal caveat following. The fourteen-item entity enumeration duplicates text already in the schema's entity description, which is the one place words could be saved.

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 2-parameter, no-output-schema destructive mutation, the description covers irreversibility, entity validation, and refusal behavior. It leaves unstated what a successful delete returns and how the idempotentHint manifests (e.g. deleting an already-removed id), which is the remaining 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?

Schema coverage is 100% and both parameters are fully described in the schema itself, so the baseline is 3. The description largely repeats the schema's entity enumeration verbatim, adding only the 'writable entity' framing and the pointer to describeDataModel for the live writable set.

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 (delete) and an exact resource scope: one row of an enumerated set of writable entities. The entity list makes the target unambiguous, though it never explicitly contrasts itself with siblings like save or import_write, so the agent must infer that this is the removal counterpart to those 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?

Provides a genuine pre-flight pointer ('see describeQueryableFields(entity)') and warns the operation is Irreversible, which implies caution before use. However, it never states when to choose delete versus alternatives (e.g. deactivating via save) or the conditions under which a delete should not be attempted beyond the vague 'each entity has its own refusals'.

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 this as read-only, idempotent, non-destructive, and closed-world. The description adds useful context about the kind of setup data returned and the operator-level settings that have no dataset. It does not describe response structure or pagination, but that is less critical for a configuration-description tool.

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

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

The description is front-loaded with the core purpose and is followed by specific content coverage and routing guidance. It is long but the length reflects the many configuration sections; most sentences earn their place, though the section list could be tightened.

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

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

For a read-only configuration-description tool with one optional parameter, full schema coverage, and no output schema, the description is nearly complete. It explains the covered domains and alternatives, though it could say more about the shape or granularity of the returned summary.

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 section parameter is already fully documented in the input schema, including the valid section names and the FACTORY_FLOOR/SCHEDULING module requirement. The description only adds a brief note to pass 'section' to read one part, which is essentially redundant with the schema.

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

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

The description states a specific verb and resource: 'Describe the manufacturer's setup', then enumerates the exact domains covered. It distinguishes this tool from siblings by naming query for row-level detail and lintConfiguration for setup problems.

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 when to use this tool versus alternatives: use query(entity=...) for row-level detail and lintConfiguration for setup issues. It also explains the optional section parameter as a way to read one part.

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?

Beyond the annotations, the description discloses the return contents, the workflow lifecycle, and the fact that publishEquation should only happen on explicit request. It also explains that equationId returns a specific equation's source with its live/not-live state, which is meaningful behavioral context for an otherwise read-only tool.

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

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

The description is front-loaded with the core instruction and then packs contract details, workflow, and parameter behavior without filler. It is dense but appropriately sized for a complex, high-context tool.

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

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

The tool has four parameters and no output schema, so the description must carry the return-shape burden. It does: it describes the contract contents, scope narrowing, the equation lifecycle, and how source retrieval works.

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 schema already documents every parameter. The description still adds useful usage meaning, especially for includeSource and equationId ('read back a draft before you test, revise or publish it'), though it does not add much beyond the schema for ownerId.

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 and resource: it returns the TypeScript contract for a pricing equation, narrowed by scope and ownerId. It also names the sibling operations save, generateQuote, and publishEquation, making it easy to distinguish from 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?

It explicitly tells the agent to 'Start here before reading, writing or changing a pricing equation' and lays out the workflow: save to validate/store a draft, generateQuote to test, and publishEquation only on explicit request. It also explains when to use includeSource=true versus equationId, which covers the main alternative invocation patterns.

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, so the bar is lower. The description still adds real context beyond them: it discloses the shape and variance of the result (enum values included; for write-only entities such as operatorSettings only the save() fields are returned), which is useful for interpretation.

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 primary purpose before the edge-case behavior. The second clause ('what delete() refuses') is slightly compressed but carries information that cannot be inferred elsewhere.

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 spends its words describing what comes back (field list plus enum values, save/delete field sets). Minor gaps remain — the format of enum values and any RSQL syntax hints are unstated — but the tool is well-covered for a single-parameter lookup.

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% — the entity parameter already enumerates every valid dataset, including the write-only ones. The description reinforces the queryable-vs-write-only distinction but introduces no new syntax or format information, so baseline 3 applies.

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

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

States a specific verb and resource ('List the filterable fields ... for a query dataset') plus the downstream purpose (building a valid RSQL filter). It also delineates the two entity modes (queryable vs write-only), so an agent can distinguish it from describeDataModel/describeConfiguration, which do not target RSQL filtering.

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

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

Gives a clear when-to-use condition: call this before constructing a query filter, and for writable entities it explains how the output relates to save() and delete(). There is no explicit exclusion naming siblings like describeDataModel, but the use context is unambiguous.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: it recomputes from actual configuration, compares against stored quotedPrice, reports newer pricing, and warns that returned variables may be overrides. It does not cover permissions or output format details, but the behavioral picture is unusually complete.

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 key purpose and scope are front-loaded, and every sentence adds substantive guidance about recomputation, overrides, or reconciliation. It is somewhat dense and long for a one-parameter tool, but the length is justified by the complexity of price explanation rather than 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?

With no output schema, the description still explains what is returned: price breakdown, pricing-equation variables, comparison to stored quotedPrice, and newer-pricing status. It also names the exact sibling tools needed to interpret the variables, making it complete for an agent to call and use the result.

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 has 100% description coverage for the single requisitionId parameter, and the description only restates that this is an existing requisition/order line. The schema already carries the lookup hint, so the description does not add meaning beyond what structured data provides; 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 first sentence states a specific verb ('Explain') and resource ('existing requisition/order line costs'), and the description distinguishes this from the hypothetical path by naming generateQuote. An agent can tell exactly what this tool does without opening the schema.

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

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

It explicitly directs hypothetical/what-if parts to generateQuote and explains how to reconcile returned variables using describePricingEquationApi(includeSource=true) and query materialPrices. This gives clear when-to-use and when-not-to-use guidance with named 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?

Beyond the annotations, the description explains the geometric distance semantics, rotation/scale invariance, practical distance thresholds, and the PRO subscription requirement. This gives the agent substantial behavioral context for interpreting results and knowing when the tool 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 front-loaded with purpose and metric semantics, then adds practical guidance and prerequisites. Every sentence carries useful information, with no redundant restatement of 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 read-only similarity lookup with fully described parameters and annotations, the description supplies the remaining needed context: distance interpretation, invariance, threshold guidance, UUID source, and subscription requirement. Nothing essential 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 coverage is 100%, so the parameters are already well documented. The description adds useful semantics by reinforcing that partRevisionId is a UUID and pointing to query(entity="partRevision"), plus a practical near-duplicate threshold for maxDistance.

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: 'Find the part revisions most similar in shape to a given one.' It distinguishes this from sibling tools by directing agents to inspectPartRevision for real dimensions and query for finding the UUID, so the intended scope is immediately clear.

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 explains the shape-similarity use case, provides the alternative inspectPartRevision for real dimensions, and tells agents how to obtain the required UUID via query. It does not explicitly state every when-not condition, but the usage context and prerequisite are well 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, and the description reinforces this with 'Purely a calculation — nothing is saved.' It also adds a real constraint beyond the annotations: equationId must belong to processId or one of postProcessingIds, and overrides change inputs, never the formula. It does not cover error behavior or performance, keeping it just short of the top.

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 return, then progressively narrower guidance (draft testing, then the alternative tool). Five sentences, none of which is filler, and the exclusion is placed last where it does not obstruct the primary 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?

For a 14-parameter, nested-object tool with no output schema, the description still tells the agent what comes back (price breakdown plus equation variables), that nothing persists, and how to compare draft vs live equations. The only gap is the pile of optional ids, which the 100%-covered schema handles.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: equationId's role as a draft-equation test harness, the ownership constraint on it, and the conceptual distinction that variables override inputs rather than the equation itself. The remaining 11 optional ids are left entirely to the schema.

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

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

Opens with a specific verb and resource — 'Price a part configuration on demand' — and states the return payload ('price breakdown plus the pricing-equation variables'). It explicitly separates itself from the sibling explainPrice, so an agent can route between them without reading either schema.

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

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

Gives concrete when-to-use conditions: a part not yet ordered, or testing a process/material/quantity/variable change. It also prescribes a specific workflow for equationId (call once with and once without to compare against live) and names explainPrice for the existing-order-line case.

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

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

Annotations already declare readOnlyHint=true, 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 cover safety (readOnly, idempotent, non-destructive), and the description adds what they cannot: a FACTORY_FLOOR subscription is required, scrap reasons are included in the output, impacted requisitions from the same build step are surfaced, and the anti-loop warning signals a per-requisition cost. That is substantive context beyond structured fields.

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

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

Front-loaded with the core capability, then the id-lookup, then the exclusions, then the prerequisite. Dense but every sentence carries operational meaning; nothing is filler.

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

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

No output schema exists, yet the description still tells the agent what the response contains (chronological moves, scrap events with reasons, co-impacted requisitions) and what access is needed. Nothing required 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 sole parameter already documents the query(entity="requisition") lookup. The description repeats that hint but adds no format or edge-case detail 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+resource+scope: a chronological production log for ONE requisition's parts, including batch moves, scrap events with reasons, and co-impacted requisitions. The single-requisition scoping is stated explicitly, which cleanly separates it from query and aggregate on the same entity.

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

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

Gives the prerequisite lookup (query(entity="requisition") for the id), names the alternatives for shop-floor scrap aggregation (query/aggregate on scrap with the dimensions they cover), and explicitly forbids looping this tool over requisitions. When-to-use and when-not-to-use are both spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds value beyond them by disclosing the subscription prerequisite and the shape of the result (per-operation quantities in routing order), though it says nothing about behavior when no progress exists or the subscription is missing.

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

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

Two short sentences, front-loaded with the purpose and followed by the prerequisite. Every clause carries information; nothing is padded.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description covers purpose, prerequisite, entitlement, and return shape. A note on error behavior for unavailable/missing requisitions would make it 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?

Only one parameter and schema coverage is 100%; the description's 'find a requisition id via query(entity="requisition")' merely restates the schema's own parameter description. No additional meaning (format edge cases, invalid-id behavior) is contributed.

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

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

States a specific resource and what it reports: quantity of a requisition's parts at each production step/operation, in routing order. That is concrete and distinguishable from getProductionHistory only implicitly via 'right now', which is clear enough but not spelled out.

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

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

Gives the prerequisite for obtaining the required id (query(entity="requisition")) and the entitlement condition (FACTORY_FLOOR subscription). It does not explicitly exclude or route to the sibling getProductionHistory, so the current-vs-historical boundary 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 readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely new behavior: error listing is paginated at 50 per page, plans include counts and first errors, and batches expose queue state and turn order. Auth requirements and full pagination semantics for non-error actions remain unstated.

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

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

Front-loads the one-line purpose, then organizes the remainder by action with zero filler. Every clause adds distinct information (return contents, pagination size, batch semantics) and the sibling pointer closes it in a single short sentence.

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 supplies return-value expectations per action (status, counts, first errors, files to upload, queue/turn) and the pagination size. Combined with the import_write pointer, an agent has everything needed to invoke and interpret this 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 0%, so the description must carry all parameter meaning and largely does: it enumerates the four action values and says what each returns, and explains planId's role for plan/errors. The page parameter's applicability is only implied ("50 a page" under errors), leaving some ambiguity about whether it applies to other actions.

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 ("Read import plans") and then breaks the capability down by action, so the agent knows exactly what each mode returns. It explicitly names the sibling import_write for the write side of the workflow, making the read/write split 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 action-by-action breakdown effectively tells the agent which action to pick for which need (list operations, list plans, inspect one plan's status, or page through errors). It names import_write as the workflow companion, but gives no explicit 'when not to use' or prerequisite/permission conditions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description substantially enriches that: undo is user-only and is refused once the first file is uploaded, uploads are rate-limited to 20/min with a 429 backoff, keys are replace-semantics, and batches form an ordered queue with a 'turn' concept. This is far more behavioral context than the annotations alone convey.

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

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

The purpose is front-loaded and most sentences carry real content, but the body is a single dense paragraph of ~250 words with repeated parentheticals ('in Phasio (Imports)' twice) and arrow-chained steps that are hard to scan. The workflow would benefit from clearer segmentation.

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 complex, destructive, no-output-schema tool this covers a great deal: workflow, batch semantics, upload mechanics, rate limits, and undo constraints. Gaps remain around the concrete return shapes of add/dry_run and the operation args (outsourced to import_read), but an agent has enough to call 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?

With 0% schema coverage the description carries the full burden, and it does well: key is defined as the source-system id, ref as a pointer to this or an earlier import, planId as the plan handle, keys as the fix target for add/remove, and note as the user-facing rationale. The nested operation args are deferred to import_read action=operations, which is a reasonable pointer but leaves that parameter family undocumented here.

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

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

The opening sentence names a specific verb (import) and enumerates the exact resource set: companies, contacts, addresses, parts with files, quotes, orders, and order history (routings, production, shipments, messages). It also distinguishes itself from the read counterpart by pointing to import_read for status and operation-arg documentation, so an agent can tell the write and read paths 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?

It lays out the full workflow (create -> add -> split -> dry_run -> fix -> user review/approve) and explicitly names the boundaries: 'you cannot approve or apply' and 'Only the user can undo an applied plan.' It routes status/arg inspection to import_read and gives error-specific guidance (IMPORT_BATCH_FULL, batch turn ordering), leaving little 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=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 flag destructiveHint=true and non-idempotency, but the description adds the crucial downstream effect: live storefront prices change immediately, the previous equation stops pricing at once, and every future customer quote changes. It also discloses the confirm requirement, mismatch refusal, the PROCESS_NO_LIVE_EQUATION state for unpublishing drafts, and a concrete reversal path.

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 SENSITIVE warning and the immediate price impact are correctly front-loaded, and every sentence carries procedural value. It is somewhat long and repeats the generateQuote/confirm requirement in the closing paragraph, which costs a point.

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, price-affecting mutation with no output schema, the description covers preconditions, side effects, failure/refusal behavior, the draft-no-live-equation state, an alternate invocation path, and rollback. Nothing an agent needs before calling this is missing.

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

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

Schema description coverage is 100% and already documents confirm, equationId, and replacesLiveEquationId (including NONE and how to look up the current live id). The description restates those semantics but adds little parameter-level detail the schema does not already carry, so baseline 3 applies.

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

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

States a specific verb (publishes/makes live) and resource (typescriptEquation turned into the live pricing equation), plus the exact scope: process, post-processing, or order level. It is clearly separable from generateQuote (tests a draft) and save (generic write) which are named explicitly.

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 precondition chain (manufacturer explicitly asked, generateQuote tested on several real parts, expectations communicated) and an explicit prohibition ('never publish to try it out'). It also names the alternative path via save(entity="typescriptEquation", ...) and the reversal procedure.

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 establish that this is a read-only, idempotent, non-destructive operation, and the description adds important behavioral context beyond them: rows are returned as field=value pairs, id and foreign keys are always included, omitted filters return recent rows, and several datasets require specific module subscriptions. No behavior contradicts 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 front-loaded with the core purpose, but it becomes an extremely dense single paragraph covering all 32 datasets. Much of the content is useful, yet the lack of headings or clearer hierarchy makes it harder to scan than it should be for a tool-selection surface.

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 high domain complexity and the absence of an output schema, the description is remarkably complete: it explains the return shape, default row inclusion, field selection, entity catalogue, module requirements, and where to go for field discovery. An agent has enough information to call the tool correctly and knows which companion tools fill remaining gaps.

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

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

Schema coverage is 100%, so the schema already documents `entity`, `filter`, `fields`, `sort`, and `limit`; baseline would be 3. The description adds real value by listing the full RSQL operator set and explaining dataset-specific filtering constraints, such as filtering `materialPrices` on `materialId`/`processPricesId` rather than the non-filterable `variables` text.

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 gives a specific verb and resource: querying the manufacturer's live data with an RSQL filter. The long dataset catalogue makes the scope concrete, but the boundary with the sibling `aggregate` tool is only implied inside dataset notes rather than stated up front.

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 substantial per-dataset usage guidance and some explicit exclusions, e.g. query `scrap` directly rather than iterating requisitions or `getProductionHistory`, and use `materialPrices` rather than reverse-engineering material rates from quotes. However, it never states a general rule for when to use `query` versus `aggregate` or when to prefer other siblings.

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

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

Goes beyond annotations by warning that some updates immediately change live behaviour (e.g. overwriting a live pricing equation) and that the response reports when that occurred — a genuinely useful side-effect disclosure that annotations (destructiveHint only) cannot convey. It stops short of stating whether updates patch or replace existing fields, or what permissions are required.

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

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

Two sentences, front-loaded with the create/update rule and the live-behaviour warning placed last where it belongs. The 14-entity enumeration is duplicated verbatim in the entity schema description, which is the main 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?

Covers the entity set, field discovery, upsert branching, and the live-side-effect caveat for a 3-param nested-object write with no output schema. The notable gap is whether the 'data' object merges with or replaces the existing row on update — a critical question for a partial-update write 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 description's id guidance and describeQueryableFields pointer largely restate what the schema already documents for id, data, and entity. It adds little new semantics beyond confirming the create/update switch, so baseline 3 applies.

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

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

States a precise verb pair and resource: 'Create (no id) or update (with id) one row of a writable entity', and enumerates the entities. The 'one row' scope cleanly separates it from bulk-write siblings like import_write, and the entity list separates it from query/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?

Explicitly gives the branch condition that selects create vs update (presence of id) and routes field discovery to describeQueryableFields(entity). It doesn't say when to prefer import_write or when a write should be avoided, so it falls short of full when/when-not guidance.

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