supplier-directory

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

Annotations already indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.

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. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential 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 single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent 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?

The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in the schema.

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

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

The description uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.

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

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

The description provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the workflow.

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. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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 dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.

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

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

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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 call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.

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

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

Annotations already mark this as a non-read-only, non-idempotent write. The description adds genuinely useful behavioral details beyond that: the operation returns a generated supplier number, and the free tier is capped at 10 suppliers with removal freeing a slot. It does not cover duplicate handling or quota-exceeded errors, but it clearly adds context beyond the annotations.

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

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

Two sentences, front-loaded with the core purpose and return value. The field enumeration is slightly redundant with the schema but serves as a compact summary; nothing is extraneous or rambling.

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 fills the key gap by specifying the returned ID format. It also adds the free-tier limit and hints at the required fields (name, category). It does not describe error behavior for duplicates or quota overflow, but the rich input schema and annotations carry most of the load, making this nearly complete.

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

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

Schema description coverage is 100%, so the input schema already documents all 10 parameters thoroughly. The description's list of fields (name, what they supply, contact, payment terms, lead time, notes) summarizes the schema but does not add new semantic meaning. 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 clear action ('Add a supplier') and a specific resource ('the directory'), and distinguishes itself from siblings like supplier_update and supplier_remove by naming its unique return value, the SUP-YYYY-NNNN number. 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?

The description implies this tool is for creating a new supplier and adds useful quota context (free tier of 10, removal frees a slot). However, it never explicitly contrasts with sibling tools such as supplier_update for modifications or supplier_remove for deletions, so the agent must infer the boundary from tool names rather than guidance.

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

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

The description discloses ordering, default days, the never-reviewed rule, and that this is a Pro featureachable. However, annotations provide no read-only or destructive hints, and the description does not confirm whether invoking this report modifies any records or requires an activated license—only that it is a 'Pro feature.'

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

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

The description is compact and front-loaded with the core definition, then moves to default, ordering, and the key edge case. The 'keeps the directory from rotting' line is slightly stylized but still reinforces the tool's purpose, and 'Pro feature' is useful placement information.

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

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

For a one-parameter report tool, the description is nearly complete: it covers the parameter default, the due criteria, ordering, and the never-reviewed edge case. It does not spell out the output fields or pagination, but 'every supplier whose record...' conveys the basic return shape and no output schema is present.

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 schema already explains the days parameter and its 90-day default. The description restates this naturally and adds the never-reviewed behavior, but it does not add substantial new meaning about parameter formats or constraints beyond the schema.

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

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

The description states exactly what the tool does: it reports suppliers whose records have not been reviewed within a configurable window, with a clear default and sort order. It also specifies the never-reviewed edge case, which differentiates it from a plain supplier_list and from supplier_mark_reviewed.

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 context is clear: use this report when you need suppliers that are overdue for review, rather than all suppliers. It does not explicitly name sibling alternatives or say when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: exact output shape, sort order, format suitability (spreadsheets vs docs/wiki/README), and the licensing difference between CSV and Markdown. This goes well beyond what annotations alone communicate.

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 short sentences with zero filler. The core action is front-loaded, and each sentence contributes a distinct fact: output shape and ordering, format use cases, filtering guidance, and pricing/licensing. This is an appropriately sized, well-structured description.

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 export tool with no output schema, the description explains what is returned, the ordering, how to narrow results, and a key licensing constraint. It is sufficient to guide a correct call, though it leaves file-delivery mechanics (e.g., inline content vs attachment) 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?

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds genuine meaning: CSV is positioned for spreadsheets, Markdown for docs/wikis/READMEs, and q/category are described as subset filters. It does not add syntax-level detail, but it improves practical understanding of the parameters.

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

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

The description opens with a specific verb and resource: 'Export the supplier directory as CSV or a Markdown table.' It adds concrete scope details—every field, one row per supplier, A to Z by name—making the tool's purpose unmistakable and clearly distinct from sibling tools like supplier_list or supplier_get.

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 a concrete usage condition: filter by category and free text first if only part of the directory is wanted. However, it never explicitly contrasts this with alternatives such as supplier_list or supplier_get for lightweight viewing, so tool-selection guidance is mostly implied rather than stated.

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

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

Annotations already carry the read-only, idempotent, non-destructive profile, so the description needs to add only what those signals do not. It adds the lookup-by-key and full-record scope plus the 'Reads only' statement, which is consistent but not heavily behavioral 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 with a second short safety clause; every phrase contributes scope, lookup key, or returned fields. There is no fluff.

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

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

For a simple one-parameter read tool with full annotations and schema coverage, the description tells an agent what it reads, how to address the record, and what fields to expect. No critical invocation detail 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 explains the supplier id or unique-name format. The description's 'by SUP number or name' largely restates that parameter documentation, adding no new semantic detail.

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 begins with a specific verb and resource ('Read one supplier record in full') and enumerates the returned content, which clearly distinguishes it from list-style or mutation siblings like supplier_list or supplier_update. The title reinforces the one-record scope.

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

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

The description makes clear that it is for retrieving a single full supplier record by SUP number or name, which implies when to choose it over supplier_list or supplier_due_review. However, it does not explicitly name alternatives or state when not 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces this with 'Reads only.' It adds meaningful behavioral context beyond annotations by specifying the sort order (A to Z by name), the exact fields returned, and the filtering capabilities, which helps set expectations for the tool's output.

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

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

The description is a single, front-loaded sentence that efficiently communicates the core action, sort order, returned fields, and filtering options. There is no redundancy or filler; 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?

With no output schema, the description adequately covers return values by listing the fields included in the directory listing. It also covers sorting and filtering behavior. Minor gaps exist, such as whether the filters are combined or the result limit behavior, but these do not prevent correct invocation for typical use.

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

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

Schema description coverage is 100%, and both the q and category parameters already have detailed descriptions in the schema. The tool description mentions 'Filter by category and by free text across every field,' which aligns with the schema but does not add substantial new meaning beyond what the parameter descriptions already provide.

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: 'List the supplier directory A to Z by name,' making the tool's purpose immediately clear. It also enumerates the returned fields (contact, payment terms, lead time, review dates) and mentions filtering, which distinguishes it from sibling tools like supplier_get or supplier_add.

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 usage context explicit: this is the directory-listing tool with category and free-text filters, so an agent can infer it is the right choice for browsing or filtering suppliers. It does not explicitly name alternatives or state when not to use it, but the context is clear enough 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 signal a write operation (readOnlyHint=false) and non-idempotent/non-destructive behavior. The description adds the meaningful consequence that the stamp is read by supplier_due_review and makes a reviewed record stop being stale, which an agent cannot infer from the schema alone.

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 focused sentences; the core action and default are front-loaded, and the second sentence explains integration and effect without filler or redundant detail.

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

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

For a two-parameter, no-output-schema stamp operation, the description covers what, when, precondition, and downstream effect. It could mention what happens if the supplier is already reviewed or not found, but that is a minor gap.

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

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

The input schema already covers both parameters at 100% with formats, defaults, and examples. The description restates the default-today behavior but adds no new parameter-level meaning, so it stays at the baseline for complete schema coverage.

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 leads with a specific verb ('Stamp'), the resource ('supplier's record'), and the temporal behavior ('on a date, today by default'). It also names the downstream consumer (supplier_due_review) and the effect (no longer flagged stale), which clearly distinguishes this tool from sibling tools in the supplier_* family.

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 states the precondition explicitly: the user has checked contact, terms, and lead time. It also explains the relationship to supplier_due_review, which reads the stamp. It doesn't enumerate exclusions or alternatives, but the context is clear enough for an agent to decide when to invoke it.

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

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

Annotations already mark the tool as destructive and non-idempotent. The description adds valuable context: the prior record is returned so nothing is lost silently, SUP numbers are never reissued, and free-tier slots are freed. This goes well beyond the structured hint data and gives the agent a realistic model of side effects.

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

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

The description is three tight sentences with no filler. The primary action and lookup method are front-loaded, and each additional sentence adds distinct behavioral information. It is compact without sacrificing useful detail.

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 a single documented parameter and no output schema, yet the description explains what will be returned and key side effects. The destructive behavior is covered by annotations and expanded in the description. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

The schema already documents the supplier parameter fully, including the SUP format example and the name-only-when-unique condition. The description repeats the 'by SUP number or name' idea but adds little beyond the schema. With 100% schema description coverage, the baseline of 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 and resource: 'Remove a supplier from the directory'. It further clarifies lookup by SUP number or name and notes that the removed record is returned. This clearly differentiates the tool from siblings like supplier_add, supplier_update, and supplier_list.

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

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

The intended context is explicit: this tool removes a supplier from the directory, and the lookup mechanism is described. It does not explicitly name alternative tools or state when not to use it, but the removal purpose is clear enough against the CRUD sibling set. A small deduction for lacking an explicit 'use supplier_update instead for edits' type exclusion.

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 are all false, so the description carries the burden of behavioral disclosure. It compensates well by explaining partial-update behavior, the at-least-one-field rule, and that identification can be by SUP number or name. It does not mention error or return behavior, but nothing 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?

Three sentences, front-loaded with the operation and identifier, then the partial-update rule and a cross-reference to a sibling. Every sentence earns its place, and there is no 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 an 11-parameter update tool with no output schema and neutral annotations, the description covers the essential semantics: identifier format, partial-update behavior, minimum field requirement, and off-limits fields. A note on return value or validation errors would make it even more complete, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds one genuinely useful constraint not present in the schema: at least one writable field must be passed beyond the required supplier. It also reinforces that the supplier parameter accepts either an id or a name, which is already in the schema but is central to correct use.

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 exactly what the tool does: change any of a supplier's fields by SUP number or name, and it enumerates the writable field groups. It also differentiates the tool from supplier_mark_reviewed by explicitly saying the review stamp is handled there. No ambiguity about the operation or resource.

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

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

It gives explicit update semantics: only the fields you pass change, and you must pass at least one. It also provides a clear when-not by stating the SUP number and review stamp are not writable here and pointing to supplier_mark_reviewed for the stamp. This is sufficient to route an agent to the correct sibling.

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