SafetyChain MCP by usefulapi

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context: the GET endpoint and the full list of returned fields. It does not mention auth requirements, rate limits, or error behavior, 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?

Two efficient sentences. The core action and field list come first, followed by the id source and endpoint path; 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?

No output schema exists, so the description carries the burden of describing return content. It does so by listing the main CAPA fields, and it supplies the id source and endpoint. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100% and the schema already defines the id as a GUID. The description adds meaningful lineage by saying the id is the GUID `Id` obtained from safetychain_search_capas, which is not conveyed by the schema alone.

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 ('Get one CAPA's details') and enumerates the fields returned, which distinguishes it from sibling tools such as get_capa_activity or get_capa_history. It also names the exact REST endpoint, so the operation 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?

It clearly routes the agent to get this tool's id from safetychain_search_capas, establishing the correct lookup flow. It does not explicitly say when to use this versus get_capa_activity, get_capa_history, or get_capa_tasks, but the field list implies the core-record use case.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds what the activity contains (comments and events) and the underlying endpoint. It does not disclose pagination, volume limits, or ordering, so it adds moderate value beyond 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 action and the id-provenance, with zero filler. Every element (activity meaning, id source, endpoint) earns its place.

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

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

For a single-param, read-only list tool with annotations covering safety and no output schema, the description is largely complete—it names the id source, the content type, and the endpoint. Return shape/ordering is the only minor gap, acceptable since no output schema exists.

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 exceeds that by telling the agent that the id is the GUID `Id` sourced from safetychain_search_capas, providing the provenance and format that the bare schema string 'CAPA id (GUID)' does not.

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 a CAPA's activity (comments and events).' The parenthetical clarifies what 'activity' means. However, it does not distinguish itself from the sibling safetychain_get_capa_history, which plausibly returns overlapping data—an agent could confuse the two.

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 tells the agent where to obtain the required id ('the GUID Id from safetychain_search_capas'), which is a genuine usage hint. But there is no explicit when-to-use or when-not, and no guidance on choosing between this and safetychain_get_capa_history or get_capa.

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, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds the exact REST path and the field set returned, but says nothing about pagination behavior in the response (total counts, whether page/page_size matter), leaving a small gap.

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: the first front-loads what is returned, the second supplies the id provenance and endpoint. No redundant restatement of the title or annotations.

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

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

With no output schema, describing the returned fields (name, extension, link, creator, date) is exactly the right compensation. It is nearly complete for a simple read tool; only pagination semantics for the response are unaddressed.

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 an extra point by clarifying that `id` is the `Id` GUID obtained from safetychain_search_capas, which the schema only calls 'CAPA id (GUID)'. Pagination params are left entirely to the schema.

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

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

States a specific verb and resource ('List a CAPA's attachments') and enumerates the returned fields, which cleanly separates it from siblings like get_capa_linked_records and get_capa_tasks.

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

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

It explicitly tells the agent where the required id comes from ('the GUID `Id` from safetychain_search_capas'), which is real routing guidance. It stops short of stating when not to use this tool or what to use if attachments are all you need alongside other CAPA sub-resources.

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 but does not describe what a history entry contains or how pagination behaves, though the schema covers paging parameters.

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 the main action front-loaded and the ID provenance immediately after. 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?

With no output schema, the description could say more about what history entries return, which is the one remaining gap. For a simple read-only list tool with fully documented parameters, it is otherwise complete enough to call 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 parameters are already documented (baseline 3), and the description adds genuine value by tying the `id` parameter to its source tool (search_capas). Page and page_size get no extra context, but nothing is missing.

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 a CAPA's history entries') that an agent can distinguish from get_capa and search_capas. However, it does not clarify how 'history' differs from the sibling safetychain_get_capa_activity, leaving a near-twin ambiguous.

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 helpfully specifies where to obtain the id (the GUID `Id` from safetychain_search_capas), which is real usage guidance. But it offers no when-to-use versus activity/attachments siblings and no prerequisites or exclusions.

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 GET endpoint and readOnlyHint/destructiveHint=false annotations make the safe-read profile unambiguous, so the description doesn't need to repeat it. Beyond that it only restates that results are a list; nothing about pagination behavior, empty results, or whether linked CAPAs include transitive links.

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 with the core operation front-loaded, followed by the id provenance and the raw endpoint. Every sentence carries information; the endpoint path is marginally useful but not 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?

For a simple paginated read with full schema coverage and read-only annotations, this covers purpose, id sourcing, and endpoint. The only gap is the meaning of a 'linked CAPA' relationship, which an agent could get wrong without domain context.

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 an extra point by naming the authoritative source of the required id (the `Id` returned by safetychain_search_capas). Pagination parameters are left entirely to the schema, which is fine given their documentation.

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 a CAPA's linked CAPAs'), which clearly separates it from siblings like get_capa and get_capa_activity. It doesn't explicitly distinguish itself from safetychain_get_capa_linked_records, so an agent must infer the CAPA-vs-record distinction from the 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 tells the agent where the required id comes from (the GUID `Id` from safetychain_search_capas), which is genuinely useful pre-call guidance. It does not say when to prefer this over safetychain_get_capa_linked_records or what to do if a CAPA has no links.

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 clear. The description adds the backing GET endpoint and the source of the id, but it does not disclose the nature or format of the returned linked records or pagination behavior beyond what the schema already shows.

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, front-loaded with the primary action and followed by essential context for obtaining the id and the endpoint. Every sentence contributes useful information without 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?

For a simple list operation with rich annotations and a fully documented schema, the description covers the essential purpose, id source, and endpoint. It omits mention of pagination and return value structure, but those are implied by the schema and not critical for correct 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 all parameters. The description adds meaningful context for the 'id' parameter by specifying that it is the GUID 'Id' from safetychain_search_capas, which helps an agent obtain the correct value.

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

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

The description clearly states a specific verb ('List') and resource ('a CAPA's linked records'), and it identifies where to obtain the required id. It does not explicitly differentiate from the sibling tool that lists linked CAPAs, so an agent must infer that 'linked records' and 'linked capas' are distinct resources.

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 when you have a CAPA id and need its linked records, but it does not state when to use this tool versus alternatives like get_capa_linked_capas or get_capa_attachments. No explicit exclusions or conditions are provided.

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, openWorldHint=true, destructiveHint=false, so the safety profile needs no restating. The description adds the underlying endpoint (GET /clientapis/capamanagement/v1.0/capa/{id}/tasks) and a preview of the returned fields, which is useful, but says nothing about pagination totals, rate limits, or what happens when a CAPA has no tasks.

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 with zero padding. The purpose and returned fields come first, the id provenance second, and the endpoint last — a clean front-loaded 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 read-only list tool with no output schema, the field enumeration effectively substitutes for return-value documentation, and pagination is covered by the schema. It stops short of explaining ordering, empty-result behavior, or pagination totals, which leaves a small gap for an openWorldHint listing tool.

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

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

Schema coverage is 100% and the page/page_size defaults and limits are fully documented in the schema, so the baseline is 3. The description adds genuine value beyond the schema by specifying that the `id` is the GUID `Id` returned from safetychain_search_capas, giving the agent a sourcing path the schema doesn't 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?

States a specific verb and resource ("List a CAPA's tasks") and enumerates the returned task attributes (step, form, location, resource, workgroup, assignee, due date, status), which in practice separates it from get_capa_activity, get_capa_attachments and get_capa_history. It never explicitly contrasts itself with those siblings, so the differentiation is inferential rather than stated.

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 prerequisite chain: the `id` must be the GUID `Id` obtained from safetychain_search_capas, which tells the agent how to reach this tool. It does not describe when to prefer get_capa_activity or get_capa_attachments instead, so no exclusions or alternatives are 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the REST endpoint path and id provenance, but says nothing about error behavior for a missing category or response shape. Modest added value over the annotations, hence a 3.

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?

One compact sentence front-loads the action and resource, with the id source immediately after and the endpoint path appended as a trailing detail. Nothing is wasted and nothing important is buried.

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 annotations covering safety and no output schema, the description supplies what an agent needs to select and invoke it. The only gap is what a returned category contains, which is low-stakes for a straightforward get-by-id.

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 as 'category id', so the baseline would be 3. The description earns a bump by explaining the provenance of that id (comes from safetychain_list_categories), which is meaning the schema does not carry.

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 ('Get one category by id') and scopes it to a single item, which cleanly separates it from safetychain_list_categories. The parenthetical naming the sibling list tool removes any ambiguity about which tool returns a single record.

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?

Tells the agent exactly where the required id must come from (safetychain_list_categories), which is the key prerequisite for calling it. It doesn't state when not to use it or what happens on an invalid id, so it stops short of full when/when-not guidance.

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

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 raw endpoint path, which signals a plain REST GET but reveals nothing about missing-id behavior or auth needs. Adequate but thin 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?

One sentence, front-loaded with the verb and resource, followed by the id-provenance hint and endpoint. No filler or restatement of the title.

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 this is close to sufficient, but with no output schema the description says nothing about what a customer record contains or what happens when the id does not exist. Those gaps matter for an agent deciding how to handle 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 coverage is 100%, so the baseline is 3, and the description earns extra credit by explaining the provenance of the 'id' value (it comes from the customer list tool). This is meaningful guidance the schema's 'customer id' text does not 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?

States a specific verb and resource ('Get one customer by id') and scopes it as a single-record fetch, which cleanly distinguishes it from the sibling 'safetychain_list_customers'. An agent can select it 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 parenthetical '(an id from safetychain_list_customers)' tells the agent where to obtain the required identifier, effectively routing to the listing tool first. It does not state exclusions or error behavior, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the underlying endpoint path and the single-entity scope; it says nothing about missing-id behavior or response shape, which would be the genuinely additive context here.

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?

One sentence with the retrieval scope front-loaded and the provenance hint adjacent to it; the endpoint path is mild extra baggage but the whole thing is short and skimmable.

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 leaves the agent without any idea of what the equipment record contains or how a failure surfaces. Adequate to invoke, but incomplete for interpreting results.

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 id parameter is documented there, so the baseline is 3. The description goes beyond it by stating the id's provenance (from safetychain_list_equipment), which tells the agent how to obtain a valid value.

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 ('Get one equipment by id'), and explicitly distinguishes it from the list sibling by saying the id comes from safetychain_list_equipment. It doesn't distinguish itself from the many other get_* tools beyond the resource name, but the resource name 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?

The parenthetical '(an id from safetychain_list_equipment)' implies the correct workflow — list first, then fetch — but never states when to use this versus alternatives or what happens if the id is unknown. Usage is inferable rather than explicit.

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 (GET /clientapis/resourcemanagement/v1.0/form/{id}), which signals a thin API passthrough, but it says nothing about not-found behavior or what a form contains. With annotations carrying the behavioral load, a 3 is appropriate.

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

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

One tightly written sentence with the operation and the id source front-loaded, followed by the endpoint. Nothing is redundant, though the raw REST path is of limited value to an agent selecting the tool.

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

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

There is no output schema, so the description is the only place an agent could learn what a form object contains, and it omits that entirely. For a simple single-parameter read this is a modest gap, but the return shape remains unknown before 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 coverage is 100% and the id parameter already has a description and a pattern constraint, so the baseline would be 3. The description adds genuine meaning beyond the schema by naming safetychain_list_forms as the source of valid ids, discouraging fabricated identifiers.

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 ('Get one form by id') and explicitly scopes the result to a single entity, which distinguishes it from safetychain_list_forms and the many other safetychain_get_* siblings that target different resources (capa, customer, equipment, record). An agent can pick this tool 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 parenthetical '(an id from safetychain_list_forms)' gives concrete guidance on how to obtain the required argument, which is the main usage question for a get-by-id tool. It stops short of stating exclusions (e.g., that it should not be used to enumerate forms or to fetch records), so it is not a full when/when-not statement.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the HTTP endpoint and id provenance, but no auth, rate-limit, error, or return-shape details.

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?

One compact sentence with the core action and id source front-loaded; the endpoint is appended without disrupting readability. There is no wasted 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 simple single-resource read tool with complete input schema coverage and safety annotations, the definition is nearly sufficient. It does not describe return value or not-found behavior, but the core invocation path is clear.

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 useful provenance for the sole id parameter by saying it comes from safetychain_list_items. That meaning is not captured by the schema's generic 'item id' 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?

States a specific verb and resource: get one item by id. It also distinguishes the operation from safetychain_list_items by noting the id comes from that listing tool.

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 clear context by telling the agent to obtain the id from safetychain_list_items. It does not explicitly state when not to use this tool or name other alternatives, but the usage path 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?

The annotations already declare this as a read-only, non-destructive, open-world operation. The description adds the API endpoint and id provenance but does not describe return shape, authorization needs, or rate limits; with annotations covering the safety profile, this is adequate but not rich.

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, starting with the tool's core purpose before adding the id source and endpoint. Every element earns its place without repetition.

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

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

For a simple single-resource read with full schema coverage and annotations declaring its safety profile, the definition is complete enough to call correctly. The only additional detail would be return values, which are not essential for this straightforward get operation.

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 required parameter is documented as 'location id.' The description adds useful meaning beyond the schema by noting that the id comes from safetychain_list_locations, helping the agent obtain a valid value.

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: 'Get one location by id.' It also distinguishes this single-resource fetch from the sibling list operation by explicitly sourcing the id from safetychain_list_locations.

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 tells the agent where to obtain the required id, namely from safetychain_list_locations, which gives clear usage context. It does not explicitly state when not to use this tool or name other alternatives beyond that listing tool.

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 the safety profile (readOnlyHint true, destructiveHint false, openWorldHint true). The description adds value beyond that by enumerating what comes back — form, submitter and timestamp, location, resource, field values, verifications — which matters since no output schema exists, plus the underlying REST path.

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

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

One front-loaded sentence carrying purpose, scope, return contents, and id provenance, followed by the endpoint. No filler; every clause adds 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 one required param, no output schema, and annotations covering safety, the description supplies exactly what is missing: what the returned payload contains and where the id comes from. Nothing needed to invoke it correctly is absent.

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 parameter, so the baseline would be 3. The description earns the extra point by specifying the id is a GUID obtained from safetychain_search_records, giving provenance the schema's 'Record id (GUID)' does not.

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 + scope: 'Get one submitted record in full by its record id'. The phrase 'in full' implicitly delineates it from safetychain_get_record_summary and safetychain_get_record_fields, and it names safetychain_search_records as the source of the id.

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 tells the agent where the required record_id comes from (the GUID from safetychain_search_records), establishing the search-then-fetch workflow. It stops short of explicitly saying when to prefer this over safetychain_get_record_summary or safetychain_record_exists, so a sibling-selection rule is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the bar is lower, but the description still adds value by noting the call is a POST that is nonetheless a read ("POST /clientapis/v2.0/getRecordsWithFields (a read)") — pre-empting an agent's assumption that POST mutates. It also warns about heavy payloads per record, though it says nothing about pagination limits or rate behavior.

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

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

Three tightly packed sentences: what it returns, how to filter, and how it is transported. The returned-field list is front-loaded and every clause earns its place; nothing is repeated 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 21 params and no output schema, the description usefully enumerates the field entry keys the caller will receive, which compensates for the missing output schema. Remaining gaps are minor (pagination expectations, whether all records are returned or only those with fields), but for a read-only filtered query this is close to 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% and all 21 parameters are documented in-schema, so the description correctly defers by saying "same filters as safetychain_search_records". The narrowing advice adds some practical meaning, but no parameter-level detail beyond what the schema already provides — baseline 3.

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 ("Get the field-level values of records") and explicitly spells out the per-record shape (name, short name, type, value, unit, compliance, min, max, target...). This cleanly separates it from sibling safetychain_get_record (which presumably returns record-level data) and from safetychain_search_records.

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

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

Gives concrete usage direction: reuse the safetychain_search_records filter set but "narrow strongly (a record number or one form and a short date range)", with the reason that each record carries many fields. It doesn't explicitly state a when-not-to-use case against safetychain_get_record or search_records, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful non-obvious context: the endpoint is a POST but is "a read", which preempts an agent mistaking the HTTP verb for a mutation. It notes performance ("Fast") but says nothing about result limits or cost on large datasets.

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 plus an endpoint reference; the output contents are front-loaded in sentence one and the routing advice in sentence two. No filler or restated title.

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 17 optional parameters and no output schema, the description carries the return-shape burden well by naming the exact summary fields (first/last date, counts by forms/resources/locations/users) and by clarifying the read-only nature of the POST endpoint. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema documents far more than the description does — date_type enum semantics, start/min_ago mutual exclusivity, time_zone_offset, identifier pairing. The description only says "records matching the filters" without adding any parameter meaning, so the baseline 3 for a fully documented schema is correct.

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 (summarize records matching filters) and enumerates exactly what the summary contains: first/last date plus counts of forms, resources, locations and users. It also distinguishes itself from the sibling it is not, naming safetychain_search_records explicitly, so an agent can route 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?

"Use it to size a request before safetychain_search_records" gives clear when-to-use context and names the alternative. It stops short of an explicit when-not clause (e.g., don't use this to retrieve record contents, don't replace search), so it lands at clear-context-without-exclusions rather than full 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered structurally. The description adds the underlying HTTP endpoint and id provenance but says nothing about failure behavior (e.g., invalid or missing id) or response shape, which is the minimum extra value expected here.

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?

A single front-loaded sentence with the key constraint (singular, id-based) first. The endpoint path is extra but compact and not distracting.

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 read-only lookup with full schema coverage and annotations covering the safety profile, the description supplies what an agent needs to call it. Only error/not-found behavior is left unstated, which 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?

Schema coverage is 100%, so the baseline is 3; the description adds real value by telling the agent where the id comes from (safetychain_list_resources) and that it is a path parameter in the endpoint template, beyond the schema's bare 'resource id'.

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 ('Get one resource by id') and clarifies singular scope against the list sibling by naming safetychain_list_resources as the id source. Clear enough that an agent can distinguish it from the list tool, though it does not explicitly contrast with other get_* siblings.

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

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

The parenthetical '(an id from safetychain_list_resources)' implies the prerequisite and when to use it, but there is no explicit statement of when not to use it or what alternatives exist for fetching multiple resources.

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 and scope profile is fully covered. The description adds only the REST path, which slightly reinforces that this is a plain read but offers no extra behavioral context (e.g., what is returned, error behavior for invalid ids).

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?

One compact sentence plus an endpoint reference; the essential action and id source are front-loaded with zero 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 one-parameter read tool with no output schema and annotations covering safety, the definition supplies everything needed to invoke it correctly. Only the shape of the returned supplier record is left implicit, which is acceptable given the read-only hints.

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 as 'supplier id'. The description adds provenance value beyond the schema by tying the id to safetychain_list_suppliers, which helps an agent obtain a valid value.

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 ('Get one supplier by id') and even includes the underlying endpoint, making the single-record fetch unambiguous. The parenthetical naming safetychain_list_suppliers cleanly distinguishes it from the sibling list tool.

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 tells the agent where the required id comes from ('an id from safetychain_list_suppliers'), which is the key prerequisite for calling this tool. It does not state when to prefer other get_* siblings (customer, item, location), but for a single-resource fetch that gap is small.

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, non-destructive and open-world, so the safety profile is handled. The description adds genuinely new behavior: the API does not page, all matches are returned truncated at the limit, and the reply reports how many rows were cut — exactly the kind of trap an agent needs warned about.

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: purpose and payload, filtering, then the paging caveat and endpoint. Front-loaded, no filler, every clause carries 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 correctly compensates by listing the returned fields (ids, names, enabled flags, created/modified dates) and the truncation semantics. Minor gap: it doesn't note that results are tenant-scoped or how hierarchy/parent-child ordering appears in the output.

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 every parameter including limit, is_deleted, is_enabled and parent_category_id is already documented in the schema. The description only restates the name filter and hints at the limit truncation behavior, adding little 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 ('List categories used to group resources of the SafetyChain tenant'), enumerates the returned fields, and gives the underlying endpoint. The singular sibling safetychain_get_category is implicitly distinguished by 'list' versus single-record retrieval.

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 'list' and the filter guidance, but the description never says when to prefer this over safetychain_get_category (single fetch) or safetychain_list_resources (the resources being grouped). No explicit exclusions or alternatives are named.

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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description only needs to add operational context — and it does: the API does not page, all matches come back, and results are truncated at the limit with the count of cut rows reported. That is exactly the kind of non-obvious behavior an agent calling a list endpoint needs and cannot infer from annotations.

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

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

Three tight sentences: what it returns, how to filter, then the important non-paging caveat, closing with the endpoint for reference. Nothing is redundant and the load-bearing constraint is placed before the boilerplate.

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, four-optional-parameter list tool with no output schema, the description supplies the returned field set, the filtering behavior, and the truncation semantics — everything needed to call it correctly and interpret the reply. No material gap remains.

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 name, limit, is_deleted and is_enabled are already documented with bounds and defaults. The description reinforces name filtering and the truncation behavior of limit but adds no syntax, format or interplay detail beyond what the schema states; baseline 3 is right when the schema carries the load.

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 customers of the SafetyChain tenant) and enumerates the fields returned: ids, names, enabled flags, created/modified dates. It also names the filter and the underlying endpoint, so an agent can distinguish it from the singular safetychain_get_customer sibling 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 description makes the list-vs-get split reasonably clear by describing bulk retrieval with an optional name filter, and it tells the agent to expect all matches rather than a paginated crawl. It never explicitly says 'use safetychain_get_customer for a single record' or states prerequisites, so it stops short of full when/when-not guidance.

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

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

Annotations already declare this as a read-only, non-destructive, open-world operation. The description adds useful behavioral context beyond annotations: the API does not page, all matches come back, and results are cut at the limit. It does not cover auth, rate limits, or exact truncation signaling, but the key non-paging behavior is disclosed.

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

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

The description is three tight sentences with zero waste. It front-loads the core purpose, then the filter, then the important non-paging behavior and endpoint.

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 parameter schema coverage and clear annotations, the description supplies what the agent needs: returned fields, filter behavior, truncation behavior, and the endpoint. No output schema exists, and the description adequately covers the return contents without needing more.

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 all four parameters are already well documented in the schema. The description restates name filtering and clarifies that the limit causes truncation, but adds little semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ("List equipment of the SafetyChain tenant") and lists the returned fields, making the operation clear. It does not explicitly distinguish itself from the sibling `safetychain_get_equipment`, though the list-vs-get distinction is strongly implied by the name and description.

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 is the listing operation and notes that results can be filtered by name. However, it gives no explicit guidance on when to use this tool versus `safetychain_get_equipment` for a single record, nor any exclusions or alternative-routing advice.

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 the safety profile is covered. The description adds genuinely new behavioral context beyond that: the API does not page, all matches are returned truncation-cut at limit, and the underlying endpoint is disclosed. It stops short of describing the truncation metadata format, 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?

Two sentences, front-loaded with purpose and returned fields, followed by the non-paging caveat and endpoint. Zero filler and nothing an agent must wade through.

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 carries the burden of describing returns, and it does list the key fields. For a 4-param read-only list tool this is nearly sufficient; only the shape of the truncation/limit metadata is left implicit.

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 all four parameters are already documented, which sets a baseline of 3. The description adds value by explaining that limit is a hard cut with no paging ('all matches come back (cut at limit)'), which clarifies a semantic the schema only gestures at with 'the reply says how many were cut'.

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 forms') and disambiguates the domain term by explaining that forms are the checklists and data-entry forms operators fill in. It also names the returned fields (ids, names, enabled flags, created/modified dates), which lets an agent distinguish it from safetychain_get_form 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?

The description implies browse/list usage versus the sibling get_form by naming the returned collection and the name filter, and 'Filter by name' hints at when to narrow results. However, it never explicitly says when to prefer this over safetychain_get_form or safetychain_search_records, 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 and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the API does not page, all matches come back truncated at limit, and the reply reports how many rows were cut — precisely the surprises an agent needs warned about.

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: what is listed, how to filter, then the paging caveat, then the endpoint. Nothing is repeated and the most decision-relevant fact (no paging, truncation) is not buried.

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 supplies the return shape (ids, names, enabled flags, created/modified dates) and the truncation semantics, which is enough to call it correctly. The only real omission is guidance on the is_deleted/is_enabled filters, which live in the schema anyway.

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 all four parameters are already documented in structured form. The description restates the name filter and the limit truncation, adding little beyond the schema; is_deleted and is_enabled are not mentioned at all, so 3 is the correct 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 ('List items') and enumerates what the resource covers (products, ingredients, materials) plus the fields returned. It is clearly distinct from safetychain_get_item, though it never names that sibling or the other list_* tools to draw the boundary 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?

The description implies usage by mentioning name filtering, but gives no explicit when-to-use/when-not guidance and does not point at safetychain_get_item for single-record lookups or at sibling list tools. The reader must infer the routing.

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

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

Annotations already carry readOnlyHint, openWorldHint and destructiveHint, so the safety profile is covered. The description adds genuinely useful context beyond that: the API does not page, all matches are returned, results are truncated at limit, and the reply reports how many rows were cut.

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 purpose and output shape, then filtering, then paging behavior and endpoint. No redundant 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?

With no output schema, the description still names the returned fields and explains the truncation and cut count, which is exactly the information an agent needs to call and interpret this read-only list 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 name, limit, is_deleted and is_enabled are already documented. The description adds value by clarifying the no-pagination truncation semantics of limit ('cut at limit'), which is more than the schema conveys.

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 locations') plus the domain entities it covers (plants, sites, areas) and what each row contains (ids, names, enabled flags, created/modified dates), which sharply separates it from the singular safetychain_get_location sibling. The endpoint is included as well.

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 implies usage by noting 'Filter by name' and that results are cut at limit, but it never states when to pick this over siblings such as safetychain_get_location or safetychain_list_resources, nor any exclusions. Adequate but leaves routing 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 cover read-only/non-destructive/open-world safety, and on top of that the description discloses the return shape (ids, names, enabled flags, created/modified dates), the lack of paging, and the truncation-at-limit behavior, plus the underlying endpoint. Missing only auth/rate-limit 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?

Three tight sentences: scope first, then filtering, then result semantics, then endpoint. Every sentence carries information and nothing is repeated 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 no output schema, the description steps in to say what fields come back and that results are unpaged but capped. For a 3-parameter read-only lister that is everything an agent needs 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?

Schema description coverage is 100%, so `name`, `limit` and `is_enabled` are already fully documented and the baseline is 3. The description's 'cut at limit' line adds a small amount of meaning about how the limit behaves, but it does not explain the name-match semantics or the enabled-filter interaction.

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 plus the exact scope: 'resources of every type (customers, equipment, items, suppliers, lists) of the SafetyChain tenant'. The enumeration implicitly separates it from the per-type siblings like safetychain_list_customers, though it never names them 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 via the 'every type' framing and 'Filter by name'. There is no explicit statement of when to prefer this cross-type lister over safetychain_list_customers or safetychain_list_equipment, nor any prerequisite or 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 already declare readOnlyHint, openWorldHint and destructiveHint, so the safety profile is covered. The description adds real value beyond that: the no-pagination behavior and the fact that results are truncated at limit, plus the underlying endpoint path. It stops short of describing response shape or error behavior, so a 4 rather than 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 zero filler: scope and returned fields first, then the filter, then the paging caveat and endpoint. Every sentence carries information the agent needs.

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, and the description compensates by listing the returned fields and explaining the truncation behavior. Combined with the 100%-covered input schema and existing annotations, nothing essential for a correct call is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the limit truncation semantics. The description's 'filter by name' and 'cut at limit' only restate what the schema already says, adding no new 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 ('List suppliers of the SafetyChain tenant') and enumerates the returned fields (ids, names, enabled flags, created/modified dates), so the agent knows exactly what it gets back. The 'list' vs 'get_supplier' split is conveyed by the tool name and the plural scope, making it distinguishable 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?

Gives clear usage context: filter by name, and the explicit warning that the API does not page so all matches come back cut at limit. It does not explicitly name an alternative (e.g. get_supplier for a single record) or state when not to use it, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint path (GET .../Exists), which is minor context, but says nothing about what comes back or rate/auth behavior.

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

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

Two short sentences, front-loaded with the purpose and followed by the endpoint. The endpoint path is arguably surplus for an agent but does no real harm.

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 should say what an existence check returns (boolean? 404 vs true?) and it does not. For a tool whose entire value is its return signal, that is a meaningful omission even though the input side is fully covered.

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 is a single required parameter with 100% schema description coverage, so the schema carries the semantics. The description merely repeats 'record id (GUID)' without adding format, validation, or error-case guidance beyond the pattern already 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 states a specific verb+resource: check whether a record exists, keyed by a GUID. This is naturally distinguishable from siblings like safetychain_get_record or safetychain_search_records, though it never explicitly contrasts itself with them.

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

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

Usage is only implied by the verb 'check existence' — an agent can infer this is the cheap pre-flight call before get_record, but the description names no alternative and gives no condition for choosing it over a full record fetch.

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, and the description adds genuinely useful context beyond that: the operation is a POST endpoint that is nonetheless a read-only search, which prevents an agent from mistaking the HTTP verb for a mutation. It also lists returned fields and the default page size.

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

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

The description is dense but front-loaded, leading with what is searched and how filters combine, then covering return fields, pagination, and follow-up usage. Every sentence earns its place, including the clarification that the POST endpoint is read-only.

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 11 optional parameters, no required fields, and no output schema, the description fills the key gaps: it summarizes returned fields, states the page size, explains filter combination, and points to sibling tools for retrieving a single CAPA. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by stating that filters combine with AND, which is a parameter-interaction detail not captured in the schema. It also notes the 50-per-page default. Slight ambiguity remains around the returned GUID Id versus the numeric capa_id parameter, but the overall value exceeds 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?

The description names a specific verb (Search) and resource (corrective and preventive actions, including CAPA, SCAR, and CCAR), and it is clearly distinguished from the get-by-id sibling tools. An agent can tell exactly what this tool retrieves without opening the schema.

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

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

It gives clear workflow guidance: use the returned Id with safetychain_get_capa and related tools, implying search first and then fetch details. It also explains that filters combine with AND. It stops short of explicitly naming when to prefer safetychain_search_records instead, so it is strong but not fully exclusionary.

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, and the description reinforces this ('a read: it only searches') while adding real value: a scale warning (millions of records), the non-snapshotted pagination caveat, and the POST endpoint mapping. The main remaining gap is return shape and pagination totals, but overall this goes meaningfully 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?

Five short sentences, front-loaded with the resource, then filters, then the scaling constraint, then the pagination caveat and the sibling pointer. No filler; each sentence carries a distinct operational instruction.

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 19-parameter, no-required, no-output-schema search tool, the description covers scope, returned headers, narrowing strategy, pagination stability and the field-values alternative, which is enough to call it correctly. Minor incompleteness: no mention of paging limits (max page 100000, page_rows 500) beyond the schema, and no guidance on result totals.

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 goes further by grouping the filter families ('date range, form, location, resource, identifier and compliance') and stating the mandatory narrowing strategy. It does not explain individual parameters like time_zone_offset or date_type, but those are already documented 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?

Opens with a specific verb+resource ('Search submitted records') and immediately enumerates the header fields returned (record number, compliance, submitted date, location, form/version, resource, submitter, signed, verifications, ids). It also names the sibling it does not return field values for (safetychain_get_record_fields), so an agent can distinguish it from get_record/get_record_fields 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?

Gives hard usage rules: 'Always narrow by a date range or a name: the tenant can hold millions of records', and routes field-value retrieval to safetychain_get_record_fields. It also supplies a when-to-do-what condition for pagination ('for a stable multi-page read use a closed date range'), which is exactly the kind of alternative/exclusion guidance that prevents misuse.

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