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

No annotations are provided, so the description carries the full burden. It usefully discloses the return values (busObRecId and public ID) and that field keys may be either field names or display names, but says nothing about failure behavior, validation errors for unknown fields, permission requirements, or what happens when required fields are omitted.

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, zero filler, front-loaded with the action. Each sentence adds a distinct piece of information: purpose, how to pass fields, prerequisite lookup, and return contract.

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

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

For a two-parameter create tool with full schema coverage and no output schema, the description covers the essential contract: what it creates, how to shape the fields map, how to discover required fields via a sibling, and what identifiers come back. Only error/validation semantics are 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%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that the fields map accepts either field names or display names, which the schema does not state, and names the concrete return identifiers. The businessObject parameter itself gets no extra explanation beyond the schema's own 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+resource ('Create a new business object record') that immediately distinguishes it from siblings like update_business_object, delete_business_object, and search_business_objects. 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?

Gives a concrete prerequisite workflow: call get_business_object_template with requiredOnly=true to learn which fields are mandatory before creating. It does not state when-not to use it (e.g. use update_business_object for existing records), but the create-vs-update split is implied by the verb and sibling names.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses irreversibility ('This cannot be undone'), which is important for a destructive operation, but says nothing about required permissions, whether related records cascade, or what is returned on success.

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 operation and scope, ending with the irreversibility warning. 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?

For a simple two-parameter, fully documented delete with no output schema, the description covers the essential action and the key risk (permanence). It is nearly complete, with only auth/cascade behavior and error semantics left unaddressed — meaningful for a destructive op with no annotations.

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 both parameters (recId and businessObject) are already documented in the schema, including the busObRecId naming and the object-name-or-id convention. The description restates the record-ID concept without adding 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?

The description gives a specific verb and resource ('Permanently delete a business object record') plus the identifying key (busObRecId), so the agent immediately knows what the tool does. The verb 'delete' cleanly separates it from the sibling set, which is otherwise all get/list/create/update/search tools.

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

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

The description offers no when-to-use or when-not-to-use guidance, no mention of prerequisites, permissions, or alternatives such as update_business_object for reversible modifications. At best the destructive verb implies intent; it is not 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?

No annotations are provided, so the description carries the full behavioral burden. It implies a safe read and discloses that all field values are returned, which is useful, but says nothing about permissions, behavior when the ID is invalid, or record-not-found handling.

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 tight sentence that leads with the verb and resource, then the addressing options, then the exclusivity constraint. 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 simple single-record read with no output schema, the description tells the agent what it gets back (all field values) and how to address the record. Adequate; only failure/permission behavior is 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, and the description adds the mutual-exclusivity rule ('exactly one of recId / publicId') that the schema does not encode as oneOf/anyOf. That is genuine added meaning beyond the structured fields.

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

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

States a specific verb (Read) plus resource (a single business object record) and the addressing schemes (busObRecId or public ID). The singular 'single record / addressed by ID' framing contrasts implicitly with list_business_object_summaries and search_business_objects, 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 implied (fetch one record when you already have its ID) but never contrasted with siblings like search_business_objects or list_business_object_summaries. The one explicit rule — 'Provide exactly one of recId / publicId' — is a parameter constraint rather than a when-to-use 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?

With no annotations the description carries the full behavioral burden; it correctly conveys a read-only retrieval and specifies the returned structure. It does not disclose error behavior for an unknown businessObject, whether the name lookup is case-sensitive, or any auth/permission requirements.

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 tight sentences with zero filler: the return payload is front-loaded, followed by the motivating use case. Nothing repeats the name or 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?

No output schema exists, but the description compensates by listing the return fields, so an agent knows what a call yields. The remaining gap is failure/pagination behavior for an invalid object name, which is minor for a read-only lookup.

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

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

Schema description coverage is 100%, so both businessObject and requiredOnly are fully documented in the schema itself. The description adds no syntax or format detail beyond that, which is the expected baseline when the schema does the work.

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 schema (template) of a business object") and enumerates exactly what that schema contains: field IDs, names, display names and required flags. This differentiates it from get_business_object, which would not return the field template.

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 this to learn which fields exist before creating, updating or searching records" gives a clear when-to-use context and implicitly ties the tool to the write/search siblings. It stops short of naming alternatives or stating when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It discloses the response contents (names and busObIds), which is useful since no output schema exists, and 'List' implies a safe read. It says nothing about permissions, pagination, or result size 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?

Two tight sentences with the purpose and the returned fields front-loaded, followed by the intended usage. No filler or repetition.

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

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

With no output schema, the description usefully names the fields returned, and the single parameter is fully documented in the schema. As a read-only discovery tool the remaining gap (pagination, auth) is modest.

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%: the single 'type' parameter has an enum, a default, and an explanatory description. The tool description adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('List Cherwell business objects') and names the returned fields (names and busObIds). It implicitly distinguishes itself from get/create/delete/update siblings by framing itself as a discovery operation, though it never names a sibling explicitly.

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

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

Gives a clear use condition: discover which objects exist and obtain the busObId or exact name that other tools require. There is no explicit when-not guidance or named alternative, but the intended role in the workflow is unambiguous.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the Cherwell AND/OR filter-combination semantics, paging support, and the default-all-fields return behavior, but says nothing about permissions, result-size implications, or the shape of returned results. Adequate but incomplete for an annotation-free tool.

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

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

Two dense sentences, front-loaded with the operation and immediately followed by the most error-prone detail (filter combination semantics). No filler, though the parenthetical '(Cherwell semantics)' is mildly redundant.

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 5-parameter search tool with no output schema and no annotations, the description covers query construction and field selection but omits the returned result structure (e.g., whether total counts or paging metadata come back). The gaps are moderate rather than severe since the query semantics, the trickiest part, are 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?

Schema coverage is 60%, and the description compensates well: it explains the AND/OR semantics of the filters array, which the schema does not convey, and notes that the fields list defaults to all fields. pageSize/pageNumber behavior is left to the schema, which documents defaults and bounds.

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: search business object records with field filters. This differentiates it from the CRUD siblings (get/create/update/delete_business_object), though it does not name an alternative explicitly. The core purpose 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 description implies usage through its filter semantics (OR within a field, AND across fields), which tells the agent how to build a query, but it never states when to prefer this tool over siblings like list_business_object_summaries or get_business_object. No when-not or exclusion guidance is 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?

With no annotations, the description carries the full burden. It valuably discloses partial-update semantics ('Only the provided fields are changed'), but says nothing about permission requirements, error behavior when neither/both IDs are supplied, or the effect of unknown field names. Meaningful but incomplete for a mutation tool.

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

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

Three tight sentences, front-loaded with the action and addressing mechanism, then the partial-update rule and the ID exclusivity rule. 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?

A mutation tool with no annotations and no output schema relies on the description, which covers addressing and partial-update behavior but omits permissions, failure modes, and return expectations. Adequate but with clear gaps for a write 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 already 100%, so baseline is 3, but the description contributes information the schema does not express: the mutual-exclusivity rule for recId/publicId (the schema has no oneOf). That added constraint meaningfully improves correct invocation.

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

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

States a precise verb+resource ('Update fields of an existing business object record') and clarifies the addressing scheme (busObRecId or public ID). It's clear what the tool does, though it does not explicitly contrast itself with siblings like create_business_object or delete_business_object.

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

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

The description gives no when-to-use/when-not-to-use guidance and never names an alternative tool. The 'exactly one of recId / publicId' note is an argument constraint, not usage routing, so an agent must infer that this is the mutation counterpart to create/delete.

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