Safefood 360 MCP by usefulapi

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

Goes well beyond the annotations: it discloses that the call may trigger the site's complaint workflow and notifications, spells out the concrete consequence of non-idempotency (two complaints), and explains that server-side validation rejects requests missing required fields. This is exactly the side-effect context the destructiveHint=false / idempotentHint=false flags cannot 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?

Front-loaded with the operation mode and the highest-risk behavior (side effects, non-idempotency) before validation notes and the endpoint path. Three tight sentences plus endpoint, with 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 13-parameter write with a nested contact object and no output schema, it covers the critical gaps: side effects, idempotency, and where identifier values come from. It is slightly thin on the vague 'rejects a request that lacks required ones' phrasing (schema lists only description as required) and on the contact_person sub-fields.

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 field-level meaning is already handled; the description nevertheless adds the useful fact that ids like source, company and recorded_by are GUIDs drawn from the site's own lists, which is not obvious from the pattern constraint alone. It says nothing extra about the nested contact_person object or the date/risk formats.

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 an explicit 'WRITE: record a NEW complaint' verb+resource+mode, which cleanly separates it from all read-oriented siblings (get_complaint, list_complaints) and from the update tools. An agent can pick it without opening any 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 'WRITE:' marker plus the explicit 'not idempotent: calling it twice creates two complaints' tells the agent when to be cautious about repeating the call. It stops short of naming an alternative tool or stating prerequisites (e.g., fetch site lists first), so it is clear context without full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying REST path, but that path references a {siteId} segment that is not an input parameter, which raises a question about scoping rather than resolving one. Nothing is said about return shape, not-found behavior, or permissions.

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 padding, and the purpose is front-loaded. The trailing endpoint path is of marginal utility to an agent and introduces the unexplained siteId, but it is brief enough not to be wasteful.

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?

There is no output schema, so the description is the only place a caller could learn anything about the returned record, and it says nothing about fields or structure. For a simple read-by-id with full annotation coverage this is passable, but the dangling siteId in the path leaves the addressing model ambiguous.

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 single parameter is documented with its GUID pattern, so the schema carries the semantics. The description only restates that lookup is by id in GUID form, adding no format or validation detail beyond the schema.

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

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

States a specific resource ('one batching (traceability) record') and a specific retrieval key ('by its id (GUID)'), so the agent knows exactly what comes back. It does not explicitly contrast with siblings, but the get_* pattern and the singular-record framing separate it from list-style 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?

Usage is implied by the id-based fetch framing: use when you already have a record GUID. There is no statement of when not to use it, no alternative tool named, and no note on prerequisites or what to do if the id is unknown.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the underlying REST path, which implies site-scoped access but is not explained; it says nothing about error behavior (e.g. unknown GUID) or what a caller receives. This is adequate but thin for a tool where the schema is the only other context.

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 fragments with no filler, and the core ('one complaint by its id') is front-loaded. The appended endpoint URL is of marginal value and introduces a {siteId} path variable the schema doesn't expose, which slightly muddies rather than helps.

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 no output schema, the definition is minimally sufficient given the annotations and full schema coverage. It nonetheless omits what a complaint record contains and how failures surface, and the unexplained {siteId} segment in the path may confuse an agent mapping parameters to the endpoint.

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 complaint_id field already documents the GUID format, pattern and provenance from list_complaints. The description's phrase 'by its id (GUID)' merely restates that, adding no syntax or semantic detail. Baseline 3 applies when the schema does the heavy lifting.

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 identifies the resource (a single complaint) and its key (GUID), which cleanly separates it from safefood360_list_complaints. The verb is only implied by the title ('Get') rather than a full verb+resource phrase, and the raw endpoint adds noise rather than clarity, but an agent can still tell what this does.

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?

There is no explicit statement of when to use this versus safefood360_list_complaints or the other get_* siblings. The only hint about obtaining the id lives in the schema ('e.g. from safefood360_list_complaints'), not in the description. Usage is implied by the name alone.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds real value by listing the fields the payload contains and warning that no list endpoint exists, but it says nothing about not-found behavior or whether identifier is a name, code, or numeric ID.

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 terse sentences, front-loaded with what is returned, then the no-list caveat, then the endpoint path. The raw GET path is low-value for an agent but takes little space.

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 one required parameter, no output schema and full annotation coverage, the description is nearly sufficient: it enumerates returned fields in lieu of an output schema. The only real gap is identifier format/type, which matters because lookup failures would be silent.

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% for the single parameter, so the baseline is 3. The description's 'by its identifier (name, ...)' arguably muddies rather than clarifies whether the identifier is a name or an opaque key — it could be read as the identifier being the customer name.

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: fetch one customer by identifier, and parenthetically names the fields returned (name, addresses, phone, notes). It is distinguishable from sibling getters by resource, though it never contrasts with safefood360_update_customer, leaving the read-vs-write distinction to the annotation.

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 vendor offers no customer list' is a genuinely useful usage constraint — an agent knows it cannot enumerate customers and must already have an identifier. However, there is no explicit guidance on when to prefer this over safefood360_update_customer or what to do when the identifier is unknown.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the underlying endpoint, but says nothing about behavior on an unknown identifier (error vs. empty result), permissions, or the siteId scoping that the endpoint path implies but the input schema does not expose.

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 compact sentences with the payload description front-loaded and the endpoint appended as supporting detail. No filler, though the raw endpoint path is of marginal value to an agent that cannot control the site context.

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 compensates by naming the fields returned (title, description, version, folder, responsible person, workflow). It is thin on failure modes and on the unspecified siteId, but is sufficient for a single-parameter read.

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 there is only one parameter, so the schema already fully documents 'identifier' as shown in Safefood 360. The description adds nothing beyond 'by its identifier' and notably does not clarify where siteId comes from given the endpoint requires it.

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: retrieves a single controlled document by its identifier, and enumerates the fields returned. The phrase 'One controlled document' implicitly contrasts with the sibling safefood360_list_documents, though no sibling is 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?

Usage is only implied: an agent can infer this is the fetch-by-id counterpart to list_documents, and that a valid identifier from that listing is required. No explicit when-to-use/when-not, no mention of safefood360_get_document_review or safefood360_update_document as adjacent operations.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint path, which hints at site scoping, but says nothing about what is returned, error behavior, or pagination. Notably the path includes {siteId} while the schema exposes only review_no, an implicit-context detail left unexplained.

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 endpoint reference. No filler or 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?

This is a simple single-record read with full schema coverage and safety annotations, so little is required. Still, the description is essentially a restatement plus a URL, and gives no sense of the returned review object or what to do if the number is invalid.

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 single parameter is fully documented as 'Document review number.' The description's 'by its review number' restates the same meaning without adding format, source, or lookup guidance, 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 (get) and resource (one document review) plus the lookup key (review number), which distinguishes it from the sibling list_document_reviews by plurality. It does not name the sibling explicitly, but the singular framing is 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?

'One document review by its review number' implies the usage: fetch a single review when you already have its number, as opposed to listing. However, no alternative is named and no prerequisites or failure conditions (unknown number) are given.

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 readOnlyHint=true and destructiveHint=false, so the safety baseline is covered. The description adds genuinely new behavioral context beyond them: the record holds personal/sensitive HR data with a minimization obligation, and the underlying endpoint path is disclosed. It does not describe error behavior for unknown identifiers, which keeps it from a 5.

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 compact sentences with the resource and privacy constraint front-loaded before the routing/endpoint detail. The endpoint string is mildly operational rather than descriptive but is short and plausibly aids debugging; 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 with no output schema, the description supplies scope, data domain, privacy handling, and the absence of a list alternative — enough for correct invocation. The only gap is that the shape of the returned record is only loosely characterized as 'training/HR master data,' which an output-schema-less tool could have detailed further.

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

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

Schema coverage is 100% for the single identifier parameter, so the schema already carries the semantics. The description's 'by its identifier' merely restates the parameter without adding format, source, or resolution guidance (e.g., where identifiers come from, given no list endpoint exists). 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 — one employee record retrieved by identifier — and scopes the data domain (training/HR master data of the site). It also preempts confusion with list-style siblings by noting the vendor offers no employee list, so the retrieval path is 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?

Gives an explicit usage constraint: 'Contains personal data: use it only for the question asked,' which tells the agent to avoid broad or speculative lookups. It also states that no employee-list alternative exists, closing off a common wrong turn. It stops short of describing when a fetch is warranted versus refusing, 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?

Annotations already declare readOnly=true, destructive=false and openWorld=true, so the safety profile is covered. The description still adds real value beyond that: it discloses what the response contains (categories, specifications, constituent materials) and the absence of a list endpoint, both of which shape how the agent plans around this 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 with no filler: the returned fields come first and the endpoint path comes last as supporting detail. The fragmentary opening ('One final (finished) product...') costs a little clarity but wastes nothing.

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 compensates by enumerating the returned fields, which is exactly what an agent needs to decide whether to call it. The remaining gap is identifier format/siteId resolution — the path references {siteId} but the only parameter is identifier, leaving that mapping 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 100% and the single parameter is documented in-schema as 'Final product identifier.' The description restates the identifier-based access but adds no format, naming-convention, or siteId context beyond what the schema already establishes, 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 names the specific resource (one final/finished product) and enumerates its returned attributes (name, folder, categories, barcode, specifications, materials), plus the concrete endpoint GET /finalproducts/sites/{siteId}/v1/finalproducts/{identifier}. The retrieval verb is only implied by the noun phrase and the HTTP method, so it is slightly less crisp than an explicit 'Retrieves one final product by identifier'.

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 adds a useful operational constraint — 'The vendor offers no final-product list' — implying the agent must come in with an identifier rather than enumerate. However, it never distinguishes this from the closest siblings (get_material, list_materials) or states when a final product is the right target versus a material, leaving the choice 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 and destructiveHint=false, so safety is covered. The description adds only the underlying endpoint (GET /v1/materials/{externalId}) and nothing about not-found behavior, permissions, or response shape, so the added value is modest.

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?

Extremely compact and front-loaded — the resource and key come first, with no filler. The dangling '?siteId=.' fragment is the one piece that costs it a point on structure.

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 with annotations covering safety and no output schema, the essentials are present. However, the stray siteId reference and the absence of any not-found or return-content behavior leave a small but real 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 description coverage is 100% for the single parameter, so the schema already documents external_id and the description merely restates it as 'external id'. The trailing '?siteId=' references a parameter that does not exist in the input schema, which adds ambiguity rather than meaning.

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 (retrieve one material) plus the lookup key (external id), which implicitly separates it from the sibling list_materials. It stops short of naming the list/search alternative for sibling differentiation, keeping it at 4 rather than 5.

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?

Usage is only implied: an agent can infer this is the single-record lookup versus safefood360_list_materials for browsing, but the description never says so explicitly and gives no prerequisites or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete endpoint path and reveals a siteId scoping query parameter, but says nothing about missing-record behavior or return shape.

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 fragments with the identifying constraint front-loaded and no filler. The trailing '?siteId=.' is slightly cryptic but costs almost nothing.

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?

There is no output schema, so the description carries the burden of explaining what is returned for a single-supplier fetch, and it does not. For a simple one-parameter lookup with annotations covering safety this is thin but not fatal.

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 single parameter is documented in-schema, so the baseline of 3 applies. The description restates the external id concept and surfaces a siteId query parameter that is not in the schema, which adds a little context but also leaves that scoping unclear.

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: retrieves a single supplier identified by its external id, and the endpoint template reinforces that. It is implicitly distinct from safefood360_list_suppliers ('One supplier'), though the sibling is never named.

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?

There is no explicit when-to-use guidance, no mention of safefood360_list_suppliers as the alternative, and no prerequisites or failure conditions. Usage is only inferable from the word 'One'.

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 establish that this is a read-only, non-destructive, open-world operation. The description adds useful behavioral context by listing the returned complaint attributes and confirming OData query support plus the endpoint shape, though it does not mention prerequisites such as site scoping or rate limits.

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: it names the resource, lists returned fields, then summarizes query support and the endpoint. There is no redundant or filler text.

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 list tool with full schema coverage and no output schema, the description is largely complete: it names returned fields and query capabilities. One gap is that it references a site-scoped endpoint without explaining how siteId is supplied, which could matter for invocation.

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 top, skip, count, filter, and orderby in detail. The description confirms that OData $filter, $orderby, $top, $skip, and $count are supported, but adds no syntax or constraints beyond what the schema already 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 states a specific verb and resource: 'List customer complaints', and it enumerates the complaint fields returned. It is clearly distinguishable by resource from siblings like create_complaint and get_complaint, but it does not explicitly say how it differs from the singular get_complaint sibling.

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 usage by saying it supports OData query options, which suggests filtering, sorting, and pagination scenarios. However, it gives no explicit when-to-use guidance, no exclusions, and no alternative such as using get_complaint for a single complaint.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: OData query support, the underlying endpoint, and the practical due/overdue use case. It does not describe result shape or ordering defaults, which keeps it below a 5.

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 compact sentences: what the resource is, what query features are supported and why to use it, then the endpoint. Front-loaded with the definition and free of 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 paginated, filterable read tool the description covers purpose, query capabilities and a use case, and the schema fills in limits, examples and the next_skip pagination convention. No output schema exists, but the reply shape is a simple list of records, so nothing essential 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%, with descriptions for top, skip, count, filter and orderby including examples, so the schema carries the parameter burden. The description only restates that the OData operators are supported, adding little beyond the schema; 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 document reviews') and defines the resource parenthetically as 'the periodic review records of controlled documents', which separates it from list_documents and from the singular get_document_review. It does not explicitly name those siblings, but the list/get distinction and the resource definition make the purpose 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?

Gives a concrete usage context: 'use it to find reviews that are due or overdue', which tells the agent when this tool is the right choice. It stops short of explicit exclusions or naming alternatives (e.g., use get_document_review for a specific record), so it is clear context without full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description adds the concrete endpoint (GET /documents/sites/{siteId}/v1/documents/) and the supported OData query surface. It does not mention rate limits or auth requirements, but for a read-only list endpoint the added context is solid.

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, no filler: resource and returned fields first, then the query capabilities and endpoint. Every clause carries information an agent would otherwise have to infer.

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 field enumeration in the description usefully substitutes for a return-value spec, and pagination semantics live in the schema (skip/next_skip). Still missing: whether results are site-scoped only, default ordering, and what the reply envelope looks like.

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 each parameter (top, skip, count, filter, orderby) is documented in-schema with bounds and examples. The description only restates that $filter/$orderby/$top/$skip/$count are supported, adding no syntax or caveat beyond the schema, 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?

Specific verb + resource: 'List controlled documents of the Safefood 360 site', followed by an enumeration of the fields each record carries (title, version, folder, responsible person, review/approval workflow, timestamps) and the underlying endpoint. An agent can tell this is a paged collection read rather than a single-record fetch, though no sibling (e.g. get_document or list_document_reviews) is 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?

Usage is only implied: the OData operator list and the 'controlled documents' scope suggest browsing/filtering a document register. There is no statement of when to prefer this over safefood360_get_document for a known ID, nor any exclusion or prerequisite (site access, permissions).

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description adds useful behavioral detail about page sizing and the exact paging cursors returned. It doesn't cover rate limits or auth, but the bar is lower with annotations present.

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 with the returned-field list and paging contract front-loaded, no filler. The trailing 'GET /v1/materials/?siteId=.' fragment is an incomplete dangling artifact that adds little since siteId isn't a declared parameter.

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 compensates by naming the response envelope fields (recordCount, next_start_index) an agent needs to page correctly. Only the unimplemented siteId reference and absent filtering guidance keep it from being fully complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds response-side semantics by explaining that the reply carries recordCount and next_start_index, which gives the paging parameters meaning the schema alone doesn't convey. It doesn't clarify sort/order or is_archived behavior 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 verb and resource ('List materials/ingredients') and enumerates the returned fields (code, supplier code, category, countries of origin, risk, archived flag), which distinguishes it clearly from the sibling get_material/get_final_product single-record 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 pagination contract ('paged with start_index and limit; the reply carries recordCount and next_start_index') implies how to page through results, but there is no explicit statement of when to choose this over get_material or how to filter archived vs active records.

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 readOnly/openWorld/non-destructive, so the description's added value is the paging contract and the fact that the response carries recordCount and next_start_index — essential behavior with no output schema to cover it. It omits auth requirements and the dangling "GET /v1/suppliers/?siteId=" introduces a siteId concept that no parameter exposes and never explains.

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, front-loaded with the resource and its returned fields, with zero filler. The trailing raw endpoint fragment "GET /v1/suppliers/?siteId=." is terse to the point of being cryptic and references a parameter absent from the schema.

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

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

With five fully optional parameters and no output schema, the description covers the essentials an agent needs: what a record contains, how paging works, and how to continue. Missing only minor context such as default sort order or the semantics of the risk/approval-status values.

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 sort, order, limit, is_archived and start_index are all already documented, including the "pass the previous reply's next_start_index" hint which the description merely repeats. Baseline 3 applies since the description adds no meaning 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?

Specific verb+resource ("List suppliers") with an explicit enumeration of the fields returned (name, code, addresses, contacts, approval status, risk, establishment numbers), which tells an agent exactly what comes back. It does not distinguish itself from the sibling get_supplier, so an agent must infer single-vs-collection usage from names alone.

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 the list/collection use case and explains the pagination protocol ("the reply carries recordCount and next_start_index"), but never states when to reach for this instead of safefood360_get_supplier, nor that the only available narrowing is the is_archived flag. Usage is implied rather than guided.

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 (which already flag destructiveHint=true and idempotentHint=true), the description discloses the crucial semantic that omitted fields are preserved while 'notes REPLACES the existing notes' – exactly the destructive behavior an agent needs to know. It adds no permission/auth or rate-limit detail, keeping it at a 4.

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 compact clauses with the write nature front-loaded, the patch semantics second, and the endpoint last. Every sentence earns its place with no 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?

No output schema exists, but annotations cover the safety profile and the description covers mutation scope, replacement behavior, and the underlying endpoint. Nothing essential for correct invocation is missing, though a note on response or error behavior would round it out.

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 genuine value by framing all five parameters as an optional partial patch where unlisted fields remain unchanged – context the per-field schema descriptions do not convey.

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 a specific verb ('change'), the exact resource ('customer in Safefood 360'), and enumerates the mutable fields (name, phone, mobile, notes). It is immediately distinguishable from sibling read tools like safefood360_get_customer and from the update_document sibling.

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 'WRITE:' prefix plus 'JSON patch of those fields; others stay as they are' makes the partial-update use case explicit. It doesn't name an alternative tool or state when not to use it, so it falls 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 give destructiveHint=true and idempotentHint=true, but the description adds important context: it is a JSON patch where omitted fields are preserved, it returns the updated document, it is an idempotent PATCH to a specific endpoint, and it explicitly scopes out version publishing and workflow changes. That goes well beyond what the annotations declare and clarifies why the operation is safely repeatable.

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 short sentences, front-loaded with the WRITE marker and the mutated fields, followed by boundaries and return behavior. 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 4-parameter mutation tool with no output schema, it covers purpose, patch semantics, exclusions, return value and the underlying endpoint. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds partial-update semantics ("fields you leave out stay as they are") that the schema alone cannot convey. It also names the three mutable fields, though it does not discuss the identifier parameter beyond the endpoint path.

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?

Specific verb plus resource ("change the title, description and/or folder of a controlled document in Safefood 360") and an explicit WRITE prefix. It is immediately distinguishable from read siblings such as safefood360_get_document and safefood360_list_documents.

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?

Draws clear boundaries in the negative: it does not publish a new version or alter the review workflow, which tells the agent when this is the wrong tool for versioning or review changes. It does not name the specific alternative sibling to use for those cases, so it falls 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.