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

With no annotations, the description carries the whole burden and does so well: it declares read-only behavior ('It creates nothing'), that drafts mark nothing made or consumed, that PROCESS is never carried and must be finished by a person in EBMS, and that EBMS does NOT auto-add consumed materials via the API. It also discloses the Track Count acceptance check and the warehouse fallback rule.

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 a precise statement of what it does, and every clause is substantive (the Track Count check, the BOM quantity caveat, the draft-is-not-a-write warning). It is a dense single paragraph with a couple of long parentheticals that would read better as a short list, but little is wasted.

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

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

No output schema exists, and the description explains what comes back (the exact POST body per draft) and how to use it (show each draft, get a clear yes). It does not describe the shape of the returned draft list beyond that, a minor gap for a tool with this much behavior to convey.

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 all four parameters. The description restates the warehouse defaulting rule ('the one given, else where the product was last made') and the company-match requirement, both of which already appear in the schema, so it adds little beyond the baseline.

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

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

States a specific verb and resource: turn approved MAKE rows of an MRP worksheet into manufacturing-batch drafts, read-only. That is clearly distinct from mrp_plan (which produces the worksheet) and ebms_write (which performs the POST), so an agent can separate it from siblings without opening a 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 gives the precondition (rows approved in the mrp_plan worksheet), names the follow-on tool ('returns the exact body to POST to INMFG with ebms_write'), and rules out human-only steps. It does not state explicit when-not conditions or contrast against import_from_csv/po_from_csv, so it falls just 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?

With no annotations, the description carries the full burden and delivers strong transparency: it discloses the HTTP POST method, the fact that EBMS rejects even an empty {} for no-dialog commands, server-side allow-list restrictions (nothing that posts, processes, pays or sends), and that commands return little data. This gives an agent a clear behavioral profile before invoking.

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?

Every sentence earns its place: purpose, endpoint, body rules, restrictions, and return behavior are packed into a compact, front-loaded description with no redundancy. The critical nuance about omitting the body is stated early, and the allow-list restriction is explained clearly.

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 5 parameters, a nested body, and no output schema, but the description covers all tricky invocation details: body omission, allow-list restrictions, and the fact that commands return little, directing the agent to read the record back. This compensates for the missing output schema and leaves the agent well-equipped to call 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%, so the baseline is 3, but the description adds meaningful nuance: it explicitly says to omit the body for no-dialog commands and that EBMS rejects even {}, which goes beyond the schema's generic 'Dialog fields, only for commands that have a dialog.' It also adds the configured-company/sandbox restriction and gives concrete command values for the command parameter.

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

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

The description opens with a specific verb-resource pair, 'Run a bound action on one record,' and gives the exact endpoint pattern, POST /ENTITY('<AUTOID>')/Model.Entities.<Command>. Concrete examples like MarkAllAsShipped and ChangeCustomer differentiate this from sibling tools such as ebms_write or ebms_get, so an agent can identify its purpose 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?

The description explains when the command will be refused (unconfigured company, non-sandbox during testing, actions not on the allow-list) and advises reading the record back afterwards, implying a follow-up read via another tool. However, it never explicitly names sibling tools or states when to choose this over ebms_write/ebms_get; the alternative usage is implied rather than 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?

With no annotations provided, the description carries the full burden and does well: it discloses that no credentials are needed, and it surfaces the key limitation that nothing marks a company as live or test. The 'list' verb implies read-only and the output fields are enumerated. It stops short of explicitly stating a lack of side effects, but coverage is strong for a listing 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?

Three sentences, each earning its place: what it lists, when to call it, and the live/test caveat. The most important scoping information is front-loaded and there is no filler or repetition of schema content.

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

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

For a zero-parameter tool with no output schema and no annotations, the description is complete. It enumerates the returned fields in prose, covers authentication requirements, gives trigger conditions, and flags ambiguity about live vs. test copies. Nothing an agent needs to invoke 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?

The tool takes zero parameters and the schema is empty, so there is nothing to elaborate. Per the baseline for 0-parameter tools, a 4 is appropriate; the description correctly avoids inventing input details.

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 companies (datasets) this server can reach') plus the exact fields returned (name, ID, version, write permission). The specifics of a company catalog listing clearly set it apart from siblings like ebms_get, ebms_write, and ebms_command, so an agent can distinguish it without opening schemas.

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

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

Gives explicit, actionable when-to-call guidance: 'Call it when the user names a company you haven't seen, or before the first write of a session.' It also warns that no marker distinguishes live vs. test copies and to ask when unsure. It does not name alternatives or when-not conditions, but the context is clear.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that the server pages internally, that it returns only path, row count, columns, five sample rows and numeric aggregates 'never the rows', that existing files are never overwritten, that ordering may fall back ('ordered: false'), and that it is read-only. That is substantive behavioral context beyond a bare verb.

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

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

Front-loaded with the core purpose and the file-vs-conversation distinction before the mechanics. Dense but nearly every clause carries information; the dash-heavy style is slightly compressed but not 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?

No output schema exists, so the description must explain the return shape — and it does precisely (path, row count, columns, five samples, per-numeric min/max/sum). For a 12-parameter export tool this covers everything an agent needs to call it and interpret 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?

Schema description coverage is 100% and the param descriptions already explain expand/explode examples, defaults and maxRows behavior, so the schema does the heavy lifting. The description reinforces field selection ('Select only the fields you need') but adds little parameter-level meaning beyond what the schema states. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read a whole EBMS collection') plus the destination ('to a file (CSV, Excel or JSONL)') and explicitly contrasts with the alternative of reading into the conversation. An agent can distinguish this from ebms_get without opening 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 explicit selection criteria ('anything more than a few hundred rows'), names the prerequisite/alternative ('Count first with ebms_get (top 1)'), and describes the downstream workflow ('Analyse the file with a script... never write a script that calls EBMS'). When-to-use and when-not-to-use are both present.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the 2-minute timeout risk from unselected reads, that count defaults to true for collections, that truncation is reported, that without top only 200 rows are shown, and that responses never exceed ~150 KB. These are exactly the behavioral traits an agent needs before invoking.

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?

Every sentence earns its place: what the tool reads, the mandatory select warning, the count/truncation default, the size-based alternative to ebms_export, and where to find query syntax. The critical constraints are front-loaded and there is no filler.

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

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

For a 9-parameter read tool with no annotations and no output schema, the description covers the operational essentials (path forms, select requirement, row/size limits, truncation signaling, alternative tool). It stops short of describing the response shape or auth/company requirements, which are partly left to the schema and the ebms-api skill.

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 56%, and the description adds crucial meaning for select (must always be passed) and top (default 200 rows, 150 KB cap) that the schema alone does not convey. It leaves filter, expand, orderby, skip, and company to the schema and defers query syntax to the ebms-api skill, so it does not fully compensate for every gap.

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

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

States a specific verb and resource ('Read from EBMS OData') and covers both modes (a collection or one record) with concrete path examples ('ARINV', "ARINV('<AUTOID>')"). An agent can immediately tell this apart from ebms_write (writes) and ebms_export (bulk).

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 names the alternative and the condition that selects it: 'For more than a few hundred rows use ebms_export instead.' It also mandates 'Always pass select' and explains the consequence of not doing so, so the when-to-use and how-to-call guidance is complete.

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

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

No annotations exist, so the description carries the full safety burden, and it discharges the most important part by declaring 'Read-only' and spelling out all three invocation modes (no args lists skills, skill returns one skill, file returns a reference file). It stops short of noting output size or pagination for the listing mode, which is a minor residual gap for a doc-fetch 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 core instruction and read-only declaration come early and the mode behavior is packed into one sentence. The domain enumeration is slightly long but earns its place by telling the agent what procedures are available before it calls.

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

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

With no output schema and no annotations, the description fully covers what the agent needs: when to call, what each argument mode returns, and that the operation is read-only. Nothing required 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 baseline is 3; the description earns above that by explaining the dispatch semantics between the two optional parameters and by describing the no-argument default behavior, which the schema cannot express. The example formats themselves live in the schema, not the 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?

The description names the resource precisely — the procedural/skill documentation for EBMS through this server — and enumerates the covered domains (sales orders, purchase orders, receiving, products, customers, vendors, MRP, imports, company setup). This makes it unmistakable against action siblings such as ebms_get, ebms_write, and mrp_plan.

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 an explicit call condition — 'before any task beyond a single read' — plus the exception ('unless the matching skill is already loaded in this app'). That is a concrete when-to-use rule an agent can apply without 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?

No annotations are provided, so the description carries the full burden and does so thoroughly: it discloses refusal conditions, that a 2xx is not proof, that EBMS silently ignores unknown @ids and unwritable fields, the exact verification payload shape (ok, mismatches, problems, notes), and the duplicate risk on resend. This is precisely the behavioral context an agent needs before a mutation.

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 operation-to-method mapping, then refusal rules, then verification and resend guidance in a logical progression. It is dense and reads as a long block, but nearly every clause carries actionable information, so waste is minimal.

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 a mutation surface, the description fully specifies the return contract (verification object with ok/mismatches/problems/notes plus stored rows) and the correct reaction to ok:false and uncertain. Nothing essential for calling this correctly is left unexplained.

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 67%, and the description compensates by explaining nested line semantics (Details for POST, Details@delta array for PATCH), path quoting by AUTOID, and the PROCESS-in-body rejection, none of which appear in the schema. It stops short of detailing every readBack subfield, but adds substantial meaning beyond the structured fields.

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

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

States a specific verb and resource (write to EBMS) and immediately enumerates the three operations with their targets: POST creates, PATCH updates by quoted AUTOID, DELETE removes one. This clearly separates it from the read-oriented sibling ebms_get without the agent needing to open a schema.

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

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

Gives explicit when-not conditions (company not configured, sandbox mismatch, PROCESS in body, duplicate EXTERNALID, APVENDOR POST missing ID) and routes the agent on what to do when the result is 'uncertain' (read back before resending). It also states the verify default and when to set false, so method selection and follow-up behavior are both covered.

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

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

With no annotations, the description carries the full burden and does so: it discloses that nothing is written to EBMS, that it writes an exceptions .xlsx beside the file, that existing/earlier-created rows are skipped (idempotent continuation), and that it reads EBMS's live metadata for mapping. It even names the downstream contract — a returned ebms_write call per remaining row.

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 every clause carries information — no filler. However, the first sentence is a very long run-on stacking validation steps, skipping rules, workbook writing and return values; bullets or shorter sentences would make the same content far more scannable.

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

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

For a 13-parameter, nested-object tool with no annotations and no output schema, the description covers the full lifecycle: mapping, validation checks, dedupe, exceptions output, draft return, and resumption. An agent can execute the correct sequence without opening any other documentation.

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

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

Schema coverage is 92%, so the schema already does most of the work and 3 is the baseline. The prose still adds real semantics the schema lacks: the importId continuation story (renamed file, newImportId after confirmation), the exceptions workbook destination, and the draft-per-row output loop — enough to lift it above baseline.

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

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

States a specific verb and resource: review a CSV/.xlsx file of records for one EBMS entity, validate it, and draft (not perform) writes. The scope is unambiguous, but it never distinguishes itself from sibling importers like po_from_csv or batches_from_csv, so an agent must infer which CSV importer applies to purchase orders or batches.

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

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

Explicit about the workflow: follow the ebms-import skill, get one clear yes, then call ebms_write per draft; nothing is written here. It also explains the re-run/continuation case (same file or corrected exceptions file) and which record types it covers. The missing piece is routing guidance against the other *_from_csv 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?

No annotations are provided, so the description carries the burden. It clearly discloses read-only behavior, the netting formula (on hand + incoming − on order), the branch-stopping rule for sub-assemblies, the once-only counting of parts used in two branches, and the canBuildWithoutBuying flag. This is rich behavioral context beyond a simple 'view' label.

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 read-only nature, then explains key behaviors. It is efficient and every sentence adds value, though it is slightly long and could be broken into two sentences for readability.

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 view tool with no output schema, the description explains the return shape (indented tree, what to make/buy, canBuildWithoutBuying) and the key calculation rules. It does not detail pagination or exact output fields, but the core semantics an agent needs to invoke and interpret the tool are present. The absence of annotations raises the burden, and the description mostly meets it.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds context for the overall semantics (e.g., how availability is calculated, how alsoMade/buyInstead affect the explosion) but does not add per-parameter details beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('view'), a resource ('one finished good'), and a precise scope: everything needed to build a quantity down every BOM level, against availability. It clearly distinguishes itself from siblings like mrp_plan by focusing on a read-only total view of one finished good.

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

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

The description implies when to use it: when you need a complete indented tree of what to make/buy for a single finished good and whether it can be built without buying. It does not explicitly name alternatives or exclusions, but the read-only framing and single-finished-good scope provide clear context. Sibling names like mrp_plan suggest a broader planning tool, but the description doesn't explicitly contrast them.

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

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

With no annotations, the description carries the full burden and does so: it declares the operation read-only, explains that only stocked products/lines are planned and that drop-ship, associated and sync lines are excluded, and documents the side effects — an Excel worksheet written to disk whose path must be given to the user, plus an attached read-only CSV copy. It also discloses where lead times come from (INVENDOR then APVENDOR, 0 means unset) and the resulting order-by vs needed-by distinction.

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 critical constraint — ask for time frame and scope first — is front-loaded, and nearly every sentence carries operational weight. It is a dense single block with no line breaks, though, which makes the lead-time sourcing and exclusion rules harder to scan than they need to be.

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 16-parameter planning tool with no annotations and no output schema, the description supplies what an agent needs: output shape in prose (buy/make, by when, why), the worksheet-first approval workflow, defaults, and the demand/exclusion rules. Nothing essential to calling it correctly is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: the lead-time precedence chain that leadTimes/leadTimeDays override, the rule that lead-time parameters are passed only when the user supplies figures, and that scope governs reporting while the whole company is always planned. It does not add anything for the remaining 13 parameters, which is acceptable given the schema already documents them.

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 and resource ('Material requirements plan for one company'), states the read-only scope, and specifies the mechanism (nets sales/job demand, batches and POs against stock through the BOM) and the return ('what to buy and make, by when, and why'). That is enough to separate it from mrp_item_view and the CSV import/export siblings without opening a 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 gives an explicit precondition — ALWAYS ask for the time frame and the scope first, never assume — and spells out the three scope choices. It also tells the agent which inputs are user-supplied only ('Pass leadTimes or leadTimeDays only for figures the user gives') and that minimumRule is a policy to ask once.

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

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

With no annotations, the description carries the full burden and does well: read-only ('It creates nothing'), validation of every vendor and product against EBMS, and idempotency guaranteed by ebms_write refusing duplicate EXTERNALID. It does not say what a draft looks like when a vendor or product fails validation, which is the one behavioral gap for a tool whose whole job is validation.

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

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

Four dense sentences, front-loaded with the core action and read-only guarantee, then workflow, then safety rule. Slightly run-on with the exclamation-free but long third clause, yet each sentence contributes distinct 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?

No output schema exists, so the description must describe returns and it does: one draft per vendor with the exact body to POST to APINV. Combined with the idempotency note and approval gate, an agent has enough to act; only error/partial-failure behavior is left unstated.

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

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

Schema description coverage is 100%, so the schema already explains csv, path and company, including the either/or between csv and path and the company-match requirement. The description adds only indirect meaning (the worksheet may have edited Qty/Vendor) and does not clarify formats or precedence beyond the schema.

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

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

States a specific transformation (worksheet -> purchase-order drafts) plus the read-only constraint in the first clause. It also implicitly separates its role from mrp_plan (which produces the worksheet) and ebms_write (which posts the drafts), so an agent can place it in the pipeline without ambiguity.

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 (planner approved BUY rows on the To order tab, possibly editing Qty or Vendor) and names the downstream step (POST drafts via ebms_write). It also states a procedural rule: show the drafts and get a clear yes per purchase order before writing.

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