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 a key authorization requirement and a uniqueness constraint, which are meaningful behavioral traits. It stops short of describing success/failure behavior or side effects, but the most important guardrails are present.

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

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

Three dense sentences with no filler. The action, key constraints, and permission requirement are front-loaded and every sentence adds value.

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

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

The description covers authorization, uniqueness, and type identification, which are essential for a create call. But with no output schema, it does not explain return values or error behavior, and the optionality ambiguity around securableTypeId/securableTypeName remains unresolved.

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?

With 0% schema coverage, the description must clarify parameters, and it does explain the either/or relationship between securableTypeId and securableTypeName plus the uniqueness rule. However, it leaves ambiguity: the schema only requires name, yet the wording 'Provide securableTypeId OR securableTypeName' could imply one of them is mandatory without explicitly saying so.

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

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

The description opens with a specific verb and resource: 'Add a new Applicable Operation.' This clearly distinguishes the tool from its delete/get siblings without needing to inspect schemas.

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

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

The 'Provide securableTypeId OR securableTypeName (not both)' constraint gives concrete input guidance. It doesn't explicitly name alternative tools, but the Add verb and the per-type uniqueness rule make the intended usage 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?

No annotations are provided, so the description carries the full burden. It discloses two important behaviors: the operation fails if permissions are attached, and it requires 'Write' on 'Security'. This goes beyond the schema and gives the agent meaningful expectations about preconditions and failure modes.

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, no filler. The primary action is front-loaded, followed by the two most important behavioral constraints. Every sentence 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 simple one-parameter delete operation with no output schema and no annotations, the description covers the essential invocation details: the ID, the permission requirement, and a key failure condition. It does not describe return behavior or side effects, but those are less critical for this straightforward destructive 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% for the single 'id' parameter, which is documented as 'Integer ID'. The description reinforces that the ID is the target for deletion, but adds little beyond what the schema already 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?

Description clearly states 'Delete an Applicable Operation by ID', naming the exact action and resource. It is immediately distinguishable from sibling applicable_operations_add and applicable_operations_get_by_type_id/get_by_type_name tools.

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

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

Usage is implied: use this tool when deleting an Applicable Operation by ID. The description gives constraints (fails if permissions attached, requires Write on Security) but does not explicitly state when to prefer an alternative or when not to use this tool. However, as the only delete operation for this resource, the intended use is reasonably inferable.

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 behavioral burden. It discloses that this is a read operation ('Returns') and states the required permission ('Requires Read on Security'). It does not cover error behavior or output format, but for a simple one-parameter lookup this is meaningful disclosure.

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 core purpose front-loaded and the permission requirement appended efficiently. No filler or redundant repetition of the parameter 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?

For a single-parameter read tool with no output schema, the description provides the essential details: what it returns, how the securable type is identified, and the authorization requirement. It is complete enough for correct invocation, though it could mention response shape or invalid-ID behavior.

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

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

Schema coverage is 100%, with the parameter already described as 'Securable type ID' and typed as integer. The description only reinforces this with 'by numeric ID,' adding no substantial meaning beyond the schema.

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

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

The description clearly states the verb ('Returns'), the resource ('all operations applicable to a securable type'), and the key identifier ('by numeric ID'). This distinguishes it from the sibling tool applicable_operations_get_by_type_name without needing to inspect 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 makes clear this is the variant for numeric securable type IDs, which is a specific and useful usage context. It does not explicitly name the alternative get_by_type_name or state when not to use it, but the numeric-ID qualifier provides enough routing guidance for an agent.

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 that the operation is a read ('Returns') and states the required permission ('Read' on 'Security'). It does not describe return shape or error behavior, but for a simple one-parameter lookup this is reasonable context.

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

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

Two short sentences with no filler. The main purpose is front-loaded, and the permission requirement is a separate, useful addition.

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 read operation with one parameter, no annotations, and no output schema, the description provides the essential context: what is returned and what permission is needed. It could add a more explicit pointer to the ID-based variant, but that gap is minor.

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 only parameter is already documented as 'Securable type name'. The description only restates this as 'by name' and adds no additional format, case-sensitivity, or usage details, so the baseline score 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 clear verb ('Returns'), a specific resource ('operations applicable to a securable type'), and the lookup key ('by name'). This differentiates it from the sibling tool applicable_operations_get_by_type_id without needing to inspect 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 '(by name)' qualifier makes clear this is the name-based variant, and the sibling list reveals the ID-based alternative. However, it does not explicitly name that alternative or state when one should be preferred over the other, so it stops short of full routing guidance.

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

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

With no annotations, the description must carry the behavioral burden. It meaningfully discloses authorization requirements and the self-approval restriction, which are important operational constraints. However, it doesn't state what approving/rejecting does to the instruction state, whether the action is reversible, or any response/error 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 sentences with no filler: the first states the action, the second lists the two key constraints. The most decision-relevant information is front-loaded and every sentence contributes.

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

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

This is a mutation tool with no annotations, no output schema, and only partial parameter documentation. The description omits side effects, return value, and routing to related approval tools, leaving an agent without enough context to predict the outcome of a successful approve/reject call.

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 only 33%: only 'approved' is documented. The description adds no parameter-level meaning and fails to explain 'comment' or 'instructionId'; it also doesn't note whether comment is expected when rejecting. Since coverage is below the compensation threshold, this is a real gap.

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

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

Description uses a specific verb ('Approve or reject') and names the resource ('an Instruction'), and the boolean parameter confirms the dual action. It does not explicitly differentiate from the sibling approvals_approve_scheduled_instruction and approvals_approve_persistent_instruction, though the plain 'Instruction' wording implies the base/non-scheduled/non-persistent variant.

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 two concrete constraints that guide call eligibility: self-approval is forbidden and the caller needs 'Approve' permission on the Instruction Definition. It does not state when to choose this tool over the scheduled/persistent approval siblings or suggest checking approvals_can_approve_instruction first, so usage context is implied 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?

With no annotations present, the description carries the full burden of behavioral disclosure. It adds useful context: the required 'Approve' permission and the API version constraint. However, it does not describe side effects, reversibility, or whether the persistent instruction must be pending approval, which limits transparency for a state-changing operation.

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

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

The description is two sentences with no filler. It front-loads the action and then adds a concise permission/version constraint, making every word earn 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 simple three-parameter mutation with no output schema, the description covers the core action and a key prerequisite. However, it omits parameter explanations and does not describe the result or post-conditions of the approval, leaving the definition minimally viable but not fully complete.

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

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

Schema description coverage is 0%, and the description does not compensate. The boolean 'approved' is partially inferable from 'Approve or reject,' and persistentInstructionId is inferable from the tool name, but the optional 'comment' parameter is entirely undocumented. The description does not meaningfully clarify the parameter semantics.

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 action, 'Approve or reject a Persistent Instruction', making the tool's purpose clear and identifying the resource. It implicitly differentiates from sibling approval tools by naming Persistent Instruction and noting API v26.2+, but does not explicitly name alternatives, so it narrowly misses a 5.

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

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

The description gives no guidance about when to use this tool versus siblings like approvals_approve_instruction or approvals_approve_scheduled_instruction. The permission note is a prerequisite, not a usage rule, leaving the agent to infer the appropriate context from the tool name.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It does add meaningful context by clarifying that the tool can either approve or reject and by stating the needed permission. However, it does not disclose side effects, reversibility, whether only pending scheduled instructions can be acted on, or what happens after an approval or rejection.

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 short sentences with no filler. The core action is front-loaded, and the permission requirement is the only additional sentence, both of which earn their 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 mutation tool with no annotations and no output schema, the description is thin. It covers the basic action and a permission requirement but leaves out workflow context such as checking pending scheduled instructions first, verifying approval rights, implications of rejection, and whether comments are expected or required.

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

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

The input schema has 0% description coverage, and the description gives almost no parameter-level detail. The words 'approve or reject' imply the role of the 'approved' boolean, and 'Scheduled Instruction' maps to 'scheduledInstructionId', but the 'comment' parameter is completely unexplained and no format or constraints are provided.

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 the action ('Approve or reject') and the resource ('a Scheduled Instruction'), so an agent can tell what the tool does. It does not explicitly contrast with the sibling tools for regular or persistent instructions, but the resource type is named in both the title and description, making the purpose unambiguous.

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

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

The description provides a usage-relevant prerequisite: it requires 'Approve' permission on the Instruction Definition. However, it does not explicitly say when to use this tool instead of related tools like approvals_approve_instruction, approvals_can_approve_scheduled_instruction, or approvals_get_pending_scheduled_instructions, leaving some inference required.

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?

There are no annotations, so the description carries the full burden. It does convey that this is a non-mutating permission check, which is useful, but it does not disclose the return value, error behavior for an invalid instructionId, or what 'can approve' depends on. 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 a single, tightly worded sentence that front-loads the core capability. There is no filler, redundant wording, or irrelevant detail.

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

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

Given the tool's simplicity, a short description is appropriate, but the lack of an output schema and annotations leaves return semantics and side-effect behavior unstated. The agent must infer that this is a boolean-style permission check and that no approval occurs, which is reasonable but not fully explicit.

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 0%, so the description must compensate. The phrase 'the given Instruction' connects instructionId to an Instruction resource, but the description never names the parameter or explains where to find it or how an invalid ID is handled. The parameter is mostly understood from its self-explanatory name and integer type.

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 the action ('check whether') and the resource ('the given Instruction'), so an agent can understand this is a capability check rather than an approval action. It is partially distinguished from siblings like approvals_approve_instruction and the scheduled/persistent variants by the word 'can' and 'Instruction', though it does not explicitly call out those alternatives.

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?

No guidance is provided about when to use this tool versus approvals_approve_instruction, or when to use approvals_can_approve_scheduled_instruction / approvals_can_approve_persistent_instruction instead. The intended use as a pre-approval permission check is only implied by the word 'can', not stated explicitly.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. 'Check whether' implies a non-mutating read-style operation, and the API version note is a useful constraint. However, it does not explicitly state return values, side-effect absence, or required authorization context, leaving some behavior implicit.

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

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

The description is a single, front-loaded sentence with no filler. The API version note is a small but useful addition. It could be slightly more informative while still staying concise, but it is well-structured and efficient.

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

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

This is a simple one-parameter check tool with no output schema, so the description is fairly complete for basic invocation. It correctly identifies the resource type and version constraint. It could improve by explicitly noting the return type (e.g., boolean indicating approval permission), but the current description is adequate for a low-complexity 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 only parameter 'id' already has a description ('Persistent Instruction ID'). The description adds nothing beyond 'given Persistent Instruction' to clarify the parameter's meaning or expected format. This matches the baseline for fully schema-covered parameters.

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

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

The description uses a specific verb ('Check whether') and a clear resource ('the calling user can approve the given Persistent Instruction'), which distinguishes it from the sibling approvals_can_approve_instruction and approvals_approve_persistent_instruction. The API version note adds useful precision. It is clear this is a permission check, not an approval action.

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 explicit guidance on when to use this tool versus alternatives like approvals_approve_persistent_instruction or approvals_can_approve_instruction. The tool name implies the use case, but the description itself does not state when to choose it or when not to. An agent must infer the appropriate context from the name and sibling list.

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 burden of behavioral disclosure. It conveys a non-mutating read-only check through the verb 'Check whether' and the phrase 'can approve' rather than 'approve'. It does not describe the return format or error behavior, but the predicate nature is clear and sufficient for a simple permission check.

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 short, front-loaded sentence with no filler. Every word contributes to explaining the tool's purpose and scope.

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

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

The tool is simple: one required id, no nested objects, and no output schema. The description states the action, resource, and actor ('calling user'), providing enough information for an agent to invoke it correctly. Explicit return-type and error details are absent but not critical given the straightforward predicate semantics.

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

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

The input schema already fully documents the single 'id' parameter with 'Scheduled Instruction ID', providing 100% schema description coverage. The description adds minimal semantic value beyond confirming the target is 'the given' Scheduled Instruction, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Check'), a specific resource ('Scheduled Instruction'), and a precise scope ('whether the calling user can approve'). It clearly distinguishes itself from sibling tools like approvals_approve_scheduled_instruction (which performs the approval) and approvals_can_approve_instruction / approvals_can_approve_persistent_instruction (different instruction types).

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 clear context: use this tool when you need to determine if the calling user is permitted to approve a specific Scheduled Instruction. It does not explicitly mention alternatives or exclusions, but the resource type is unambiguous and the agent can infer when to use it from the name and description.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It correctly signals a read operation ('Returns') and adds the useful scoping trait that results are limited to what the calling user can action. It does not disclose return shape, grouping, ordering, or pagination behavior, but the zero-parameter surface keeps this a moderate rather than severe 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?

The entire description is one front-loaded 18-word sentence: the verb and resource come first, the type enumeration is parenthetical, and the scope qualifier closes it. There is no filler, redundancy, or restatement of the tool name.

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 no-parameter, no-output-schema list tool, the description is largely complete: it states the resource, enumerates the covered request types, and scopes results to the caller's actionable items. The only omissions — result format and ordering — are minor for a list-all operation and partially inferable from the sibling getter names.

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

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

The tool takes zero parameters and schema coverage is trivially 100%, so there is no parameter meaning for the description to add. Per the baseline rule for zero-parameter tools, a 4 is appropriate — the description's silence on parameters is correct and 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?

The description uses a specific verb and resource — 'Returns all pending approval requests' — and enumerates the three types (Instructions, Scheduled Instructions, Device Authorizations), which maps directly to the per-type sibling getters. The scope qualifier 'the calling user can action' adds further precision. An agent can distinguish this aggregate tool from approvals_get_pending_instructions, approvals_get_pending_scheduled_instructions, and approvals_get_pending_persistent_instructions 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 phrase 'the calling user can action' implies the tool surfaces the caller's actionable approval queue, which gives reasonable context for when to call it. However, the description never explicitly states when to prefer this aggregate over the three type-specific sibling getters, nor does it name alternatives or exclusions. Usage guidance is implied rather than stated.

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

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

With no annotations, the description carries the disclosure burden. It conveys that this is a read-only listing operation filtered by the calling user's approval permissions, which is useful. However, it does not mention ordering, pagination, authentication requirements, or whether the result includes only base Instructions versus all instruction types.

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 one short, front-loaded sentence with no filler. Every word contributes to the meaning.

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 zero-parameter read tool, the description is mostly sufficient, but it leaves ambiguity around the scope of 'Instructions' relative to scheduled and persistent instructions, and it does not mention the all-pending alternative. Given the absence of annotations and output schema, a bit more context would improve completeness.

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

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

The tool has zero parameters and the schema description coverage is 100%, so the description has no parameter details to add. Per the baseline for zero-parameter tools, this is handled appropriately.

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 the operation (returns), resource (Instructions), and the specific filter (pending approval that the calling user can approve). It is not a tautology and conveys a concrete purpose, though it does not explicitly distinguish itself from the scheduled/persistent/all-pending sibling 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?

No guidance is given about when to use this tool versus approvals_get_all_pending, approvals_get_pending_scheduled_instructions, or approvals_get_pending_persistent_instructions. The sibling names suggest alternatives, but the description itself leaves the selection decision 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds an API version constraint and the approval filter, but does not mention read-only status, pagination, ordering, authentication requirements, or any side effects. The 'get' verb hints at safety, but the description alone does not provide rich behavioral 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?

A single, well-structured sentence that leads with the action and resource, then adds the permission filter and version note. No filler words or duplicated information.

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

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

For a no-parameter list tool, the description fully conveys what is returned and under what condition. It omits details like response format or pagination, but those are less critical when there is no output schema and the operation is a simple fetch.

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

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

The tool has zero parameters and 100% schema description coverage, so there is no need for parameter-level detail. The description correctly focuses on the output scope rather than inputs.

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

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

The description uses a specific verb (Returns), a precise resource (Persistent Instructions pending approval), and the key qualifier 'that the calling user can approve.' It clearly distinguishes itself from siblings like approvals_get_pending_scheduled_instructions and approvals_get_pending_instructions by specifying 'Persistent' and the user-approval filter.

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

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

The description implies the use case - retrieving pending persistent instructions the caller may approve - but does not explicitly name alternatives or state when not to use it. An agent can infer the context from the wording and sibling tool names, but there is no direct routing guidance.

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

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

There are no annotations, so the description carries the full transparency burden. 'Returns' implies a read-only operation and the caller-scoping is disclosed, but pagination, ordering, empty-result behavior, and any authentication nuances are not covered. This is adequate for a simple zero-parameter read tool, though not thorough.

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

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

The description is a single sentence with no filler. The key qualifiers—'Scheduled Instructions', 'pending approval', and 'calling user can approve'—are front-loaded and every word 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 zero-parameter, no-output-schema listing tool, the description supplies the essential selection and authorization filters. The exact return shape is not documented, but the intended result set is clearly defined, which is sufficient for an agent to decide whether to call it.

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

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

The tool accepts zero parameters, so there is no parameter semantics burden for the description to carry. Schema description coverage is trivially 100%, and the zero-parameter baseline applies.

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

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

The description uses a specific verb ('Returns') and identifies the exact resource and scope: Scheduled Instructions that are pending approval and approvable by the calling user. This clearly separates it from sibling tools like approvals_get_pending_instructions and approvals_get_pending_persistent_instructions.

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

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

The description makes the usage context clear: use this tool to retrieve the scheduled-instruction approval queue for the current user. It does not explicitly name alternatives or state when not to use it, but the resource type and caller-scoping are specific enough to guide selection.

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 of behavioral disclosure. It only states that entries are added and notes an API version; it does not mention permissions, validation rules, response behavior, idempotency, or any side effects beyond mutation.

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

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

The description is a single concise sentence with no filler. It front-loads the core action and includes a relevant version constraint without waste.

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

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

The tool accepts a nested entries array with multiple undocumented fields, has no output schema, and no annotations. The description is far too minimal for an agent to construct a valid request or understand the expected entry structure, so the definition is incomplete.

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 0%, yet the description provides no parameter-level meaning. The entries array and fields like comment, message, and detailMessage are left unexplained, so an agent cannot determine what content is expected or how these fields differ.

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

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

The description uses a specific verb ('Add') and resource ('audit log entries'), and adds useful qualification ('one or more', 'API v24.9+'). This clearly distinguishes it from the sibling audit_logs_search, making the tool's purpose unambiguous.

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

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

The description implies the tool is for writing audit log entries, but it does not state when to use it versus alternatives such as audit_logs_search. No exclusions, prerequisites, or conditions are mentioned, so guidance is only implicit.

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 discloses the permission requirement and enumerates filterable/sortable fields, but it does not cover pagination limits, default behavior, or failure modes for invalid filters. This is adequate but not comprehensive.

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

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

Two sentences, no filler. The core action and field list are front-loaded, and the permission requirement appears in the second sentence. Every word 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 search tool with five optional parameters, the description covers the essential context: permission requirement and allowed fields. However, with no output schema, it does not describe the shape or content of the returned audit log entries, and pagination semantics remain 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 80% with only minimal descriptions for each parameter. The tool description adds value by constraining which fields can be used in the filter and sort parameters, which the schema itself does not specify.

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

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

The description opens with the specific verb-resource phrase 'Search audit logs,' immediately identifying what the tool does. Listing the filterable/sortable fields adds precision and helps distinguish it from the sibling audit_logs_add.

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

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

The description states the required permission (Read on Security), which is a clear precondition for use. It implies the tool is for searching/filtering rather than adding audit logs, but it does not explicitly name an alternative or provide when-not-to-use guidance.

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

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

With no annotations, the description carries the behavioral burden. It does disclose that the token is one-time and that caller identity is restricted, but it does not explain what happens on success or failure, whether the token is consumed, or how the instruction state changes after authentication.

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 short sentences with no filler. The primary action is front-loaded, and the access restriction earns its place by preventing misuse.

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 security-sensitive two-factor authentication operation, the description is thin. It lacks the expected success/failure behavior, token validity details, and enough guidance for an agent to understand the full authentication flow, especially with no output schema to clarify return values.

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

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

Schema description coverage is only 50%: token is documented as 'One-time token' but instructionId has no description. The tool description does not clarify what instructionId refers to or how it relates to the token, so it fails to compensate for the undocumented parameter.

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

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

The description states a clear action ('Submit a one-time token') and a specific resource ('Instruction Two-Factor Authentication'). It also adds a scope constraint ('Only the instruction creator can call this'), which helps distinguish this from the related sibling authentication_authenticate_scheduled_instruction.

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 an access precondition ('Only the instruction creator can call this') and implies it is for authenticating an instruction rather than a scheduled instruction, but it never explicitly says when to use this tool versus the scheduled-instruction sibling or describes the surrounding authentication flow.

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

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

No annotations exist, so the description must carry behavioral information. It discloses two meaningful traits: the token is one-time and the call is creator-only. It does not say what happens on success or failure, whether the token is consumed on failed attempts, or what the response contains, which leaves gaps for an authentication 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 sentences, no filler, with the core action and the key restriction front-loaded. Every clause contributes 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?

The tool is simple and the two parameters are named clearly, but there is no output schema and no mention of expected success or error behavior, or the exact role of scheduledInstructionId. The description gives a usable start, but an agent would still have to guess about outcomes.

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?

With 0% schema coverage, the description must compensate. It adds real meaning to token ('one-time') but says nothing directly about scheduledInstructionId beyond what can be inferred from the resource and tool names. For a two-parameter schema this is borderline adequate.

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

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

The description names the exact action ('Submit a one-time token') and the resource ('Scheduled Instruction Two-Factor Authentication'), so an agent can tell it apart from generic approval tools. It does not explicitly contrast it with the sibling authentication_authenticate_instruction, leaving differentiation to the word 'Scheduled'.

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 usage context: this is the 2FA step for scheduled instructions and is restricted to the creator. It does not name alternatives or state when not to use it, but the context is unambiguous enough for the main 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does state that the tool is a write operation requiring 'Write' on 'Security', which is useful. However, it says nothing about cache semantics, idempotency, or side effects despite the 'cached' prefix in the tool name.

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 concise sentences with no filler. The action is front-loaded, followed immediately by the required permission, making it efficient and easy to parse.

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 mutation with no output schema and no annotations, the description covers the core action and authorization requirement. Missing details such as return value or caching behavior are minor but would round out an otherwise adequate definition.

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 0%, so the description must add meaning to the parameters. It clarifies that userId and groupId are the two sides of the membership, but this is largely inferable from the parameter names and tool name. It does not explain constraints, referential integrity, or duplicate behavior.

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

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

The description uses a specific verb ('Create') and resource ('user–group membership'), and states the required permission. It clearly indicates the operation being performed, but it does not explicitly distinguish this tool from the sibling add_groups_for_user, which also creates user–group memberships.

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?

No guidance is provided about when to use this tool versus alternatives such as cached_user_group_memberships_add_groups_for_user or the get/delete variants. The only extra information is a permission requirement, which is a prerequisite rather than a usage condition.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It usefully discloses that existing memberships are skipped and that Write permission is required. However, it does not describe return values, cache side effects despite the 'cached_' prefix, or failure behavior for invalid group 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?

The description is a single compact sentence that front-loads the core action, includes the key behavioral detail, and appends the permission requirement. Every element earns its place with no redundancy or 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 two-parameter mutation with no output schema, the description covers the essential invocation details: what action is performed, on what resource, with what permission, and a key behavioral edge case. Missing return/error details are minor for this complexity level.

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

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

The input schema has no property descriptions and schema coverage is 0%, so the description's 'a user' and 'multiple groups' provides a minimal semantic bridge to userId and groupIds. It adds only conceptual mapping, not detailed semantics like whether groupIds must be unique or how invalid IDs are handled.

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

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

The description uses a specific verb-resource pair: 'Batch-add a user to multiple groups' and adds the behavioral qualifier 'skips existing memberships'. This clearly distinguishes it from related siblings like cached_user_group_memberships_add (which implies single-add) and cached_user_group_memberships_remove_groups_for_user (which removes).

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

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

The description implies the tool is for batch membership additions and states the required 'Write' on 'Security' permission. However, it does not explicitly name alternative tools or state when not to use it, such as when adding a single group or when needing to overwrite existing memberships.

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

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

The description discloses an important behavioral requirement: it requires 'Delete' permission on 'Security'. Since no annotations are provided, this is valuable context. However, it does not mention whether the deletion is permanent, idempotent, or how errors or non-existent memberships are handled.

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

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

The description is a single concise sentence followed by a necessary permission note. Every word contributes meaning, and the core action is front-loaded.

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

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

For a simple two-parameter delete operation with no output schema, the description is largely sufficient: it names the action, the affected entities, and the required permission. It could be more complete by clarifying the distinction from remove_groups_for_user or noting cache side effects, but these are minor gaps given the tool's simplicity.

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

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

The schema provides only type information for userId and groupId, so the description must compensate. It does clarify that the operation involves a 'user' and a 'group', which maps naturally to the two parameters. Still, it adds little beyond the parameter names and does not explain identifier formats, constraints, or behavior when either ID is invalid.

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 action and resource: 'Remove the membership between a user and a group.' It also distinguishes itself from sibling operations like add or get by explicitly describing deletion, making the tool's purpose immediately obvious.

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

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

The intended use is inferable from the action 'Remove', and the permission requirement provides some operational context. However, the description does not explicitly state when to use this tool versus alternatives such as cached_user_group_memberships_remove_groups_for_user, nor does it describe exclusions or preferred scenarios.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It does add a meaningful permission prerequisite ('Requires Read on Security') and the verb 'Get' implies a read operation. However, it says nothing about not-found behavior, return structure, or side-effect absence, which would be useful for a tool without annotation hints.

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 succinct sentences deliver the core purpose and the permission requirement without any fluff. The essential behavior is front-loaded and every phrase 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 simple two-parameter read tool, the description covers purpose and authorization. It lacks detail on error behavior and return format, especially given there is no output schema, but the simplicity of the operation makes the definition reasonably 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 0%, so the description must compensate. It clarifies that userId and groupId are not independent filters but together identify a specific membership record. This adds relational meaning beyond the bare integer types in the schema, though it does not elaborate further on each parameter's semantics.

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 ('Get'), a precise resource ('membership record for a specific user+group pair'), and the two-parameter composition clearly distinguishes it from sibling tools like get_groups_for_user or get_users_in_group. No ambiguity about what this tool does.

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

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

The description implies the use case: when you need a single membership record for one user+group pair. However, it does not explicitly mention when to prefer an alternative tool, such as get_groups_for_user, nor does it state exclusions for bulk listing scenarios.

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 does add an authentication requirement and states the output is group IDs, but it fails to explain the 'cached' behavior—such as potential staleness or whether results reflect recent membership changes. Return format and error behavior are also undisclosed.

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 short sentences with no fluff. The primary action and result are front-loaded, and the permission requirement is a useful second sentence. Every word 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 simple one-parameter lookup, the description covers the purpose, the permission, and the result shape, which is reasonably complete. However, the explicit 'cached' aspect is left unexplained and there is no mention of whether the result is limited to group IDs only or includes additional metadata. With no output schema, a bit more detail would make it fully complete.

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

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

Schema coverage is 0%, so the description must compensate for the meaning of userId. The phrase 'a user belongs to' implicitly points to userId, and the parameter is a single obvious integer, but the description doesn't explicitly state that userId is the user's identifier or give any further constraints. This is adequate but not fully compensating.

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 all group IDs a user belongs to.' This clearly identifies the operation and result. It doesn't explicitly differentiate from the sibling 'cached_user_group_memberships_get', but the tool name and object relationship make the purpose distinct enough.

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?

No guidance is given about when to use this tool versus alternatives like cached_user_group_memberships_get or cached_user_group_memberships_get_users_in_group. The permission note 'Requires Read on Security' is a prerequisite, but there is no context about choosing this over a sibling or any exclusion cases.

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 a permission requirement but does not mention that this is a cached read (despite the tool name including 'cached'), nor does it describe potential staleness, pagination, or return format beyond 'user IDs'. The behavioral footprint is minimal and leaves key operational details unstated.

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 short sentences that convey the core purpose and a permission requirement with no wasted words. It is appropriately concise and front-loaded.

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

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

For a single-parameter read tool with no output schema, the description is minimally adequate. It states the operation and permission, but does not mention caching behavior (despite the name), return type details (e.g., array of integers), or any limits. Given the low complexity, this is acceptable but not comprehensive.

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 0%, so the description must explain the parameter. It only refers to 'a specific group' without explicitly mapping that to the groupId parameter or providing any additional context (e.g., that it is an integer identifier). The description adds little semantic value beyond what the parameter name suggests.

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 the operation: get all user IDs that are members of a specific group. It names the resource (user IDs) and the condition (membership in a group). It is distinguishable from sibling tools like get_groups_for_user by explicitly indicating the direction (users in a group).

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

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

The description provides the permission requirement ('Read' on 'Security'), which is useful for when the tool can be used. It implies that this is for listing members of a group, but does not explicitly contrast it with the inverse operation (get_groups_for_user). The context is clear enough for an agent to infer usage, but it lacks an explicit 'when not to use' clause.

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 present, so the description carries the disclosure burden. It reveals that the tool is mutating, that it tolerates non-existent memberships by skipping them, and that it requires specific permissions. It could further clarify error behavior or reversibility, but the core behavioral traits are clearly 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 a single sentence with the action front-loaded, followed by a behavioral nuance and the permission requirement. Every part adds value and there is no filler or repetition of the tool name.

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 mutation tool with no annotations and no output schema, the description covers the essential information: the operation, a key edge-case behavior, and required permissions. It stops short of explicit alternative routing and return/error semantics, but those are relatively minor for this 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 description coverage is 0%, yet the description only loosely maps 'a user' to userId and 'multiple groups' to groupIds. It does not add meaningful parameter-level detail such as ID formats, constraints, valid group references, or behavior for invalid inputs, so it under-compensates for the missing schema descriptions.

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 operation ('Batch-remove a user from multiple groups'), names the target resource (user-group memberships), and adds a distinguishing behavior ('skips non-existent memberships'). This makes the tool's purpose unambiguous and clearly differentiates it from sibling add/get/delete membership 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 implies a batch-removal use case and gives the required permission ('Delete' on 'Security'), which is helpful. However, it does not explicitly state when to prefer this tool over cached_user_group_memberships_delete or how the tools differ in scope.

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 full responsibility for behavioral disclosure. It only states that a new cached user is created, but does not mention whether creation is idempotent, whether username must be unique, what happens on conflict, whether cached data is persisted, or what response to expect.

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

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

The description is a single sentence with no filler and the action verb is front-loaded. It is concise, though it achieves this by omitting useful detail rather than by summarizing rich content.

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

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

For a write operation with no annotations and no output schema, this description is incomplete. An agent still cannot determine conflict behavior, return value, or the semantic difference between a cached user and a regular consumer, which are essential 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 0%, and the description provides no parameter meaning at all. It does not mention username, email, or displayName, nor clarify that username is required or what values are expected for email and displayName.

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

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

The description identifies a specific action ('Create') and resource ('cached user'), which clearly differentiates it from cached_users_update, cached_users_delete, and cached_users_list. It does not explain what a 'cached user' is, but the verb+resource pairing is unambiguous enough for basic selection.

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

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

There is no guidance about when to use this tool versus alternatives such as consumers_add or cached_users_update. No context, prerequisites, or exclusions are provided, leaving the agent to infer usage purely from the name.

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 disclosure burden, but it only states that a user is deleted. It does not say whether deletion is permanent, affects only the cache, requires the ID to exist, or cascades to related cached memberships.

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 no filler. Every word contributes to the core purpose.

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

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

The tool is simple, one parameter, and the description covers the essential operation, but with no annotations it leaves behavioral details such as permanence and cache-only scope unstated. Adequate but with gaps.

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 `id` parameter, so the schema already documents it. The description's 'integer ID' adds no meaning beyond what the schema provides, so baseline 3 applies.

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

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

States a specific action ('Delete'), a resource ('cached user'), and the identifier type ('integer ID'). This clearly distinguishes it from sibling operations like cached_users_list, cached_users_get_by_id, and cached_users_update.

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?

Provides no guidance on when to use this tool versus alternatives or any conditions/prerequisites. The use case is only implied by the verb and resource; there are no exclusions or comparisons to related deletion tools.

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

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

Annotations are absent, so the description is the only source of behavioral context. It reveals that the data is cached, implying possible staleness, and that the operation is a read. However, it does not explain cache refresh behavior, error semantics if the ID is missing, authentication requirements, or return format.

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 short sentence that front-loads the verb and resource. Every word is necessary; there is no filler, ambiguity, or buried caveat.

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, the description is mostly complete: it names the resource, the lookup key, and implies a single user is returned. It lacks explicit not-found behavior and return shape, but given the tool's simplicity this is a minor gap. Since no output schema exists, a bit more detail about the returned user object would push it to 5.

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

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

Schema coverage is 100% with the id parameter fully described as an integer with description 'Integer ID'. The description adds no further meaning beyond restating the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Get'), a specific resource ('cached user'), and the lookup key ('integer ID'). This clearly separates it from sibling getters like consumers_get_by_id, scheduled_instructions_get_by_id, and list operations like cached_users_list.

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

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

No guidance on when to use this tool versus cached_users_list, consumers_get_by_id, or other user lookups. The description is purely a statement of function; no exclusions or alternative selection criteria 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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It indicates a read-only list operation with pagination, but does not mention whether it reads from a live source or a cache, what ordering is applied, whether results are snapshots, or any side effects. For a tool without annotations, this is a notable 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?

A single, front-loaded sentence that states the core purpose and mentions pagination with no wasted words. Every part of the description contributes directly to understanding the tool's function.

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-with-pagination tool, the description covers the essential behavior and the schema covers the parameters. The main missing element is clarification of what the response looks like and whether the list is sorted or reflects a cached snapshot, but the overall definition is sufficiently complete for an agent to invoke it correctly.

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

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

The input schema already documents both skip and take with defaults, achieving 100% schema description coverage. The description adds only the concept of pagination and does not provide additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'List', the resource 'all cached users', and the pagination behavior. It distinguishes itself from cached_users_get_by_id by emphasizing the 'all' scope.

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

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

The description implies this is the tool for enumerating all cached users, and the pagination parameters indicate batch retrieval. However, it does not explicitly state when to prefer this over cached_users_get_by_id or when pagination should be used, leaving some usage context implicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only notes that the user's ID must be included, but does not reveal whether the update is partial or full, what happens for nonexistent IDs, or any side effects or permissions required.

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

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

The description is a single concise sentence with no redundancy, and it front-loads the required-ID constraint. It is efficient, though it is arguably under-specified rather than elegantly complete.

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

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

The definition is incomplete for a 4-parameter mutation tool with no annotations or output schema. It omits partial-update semantics, return behavior, error handling, and prerequisites, leaving significant gaps for an agent deciding whether and how to invoke it.

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

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

Schema description coverage is 0%, and the description only explains the id requirement. The email, username, and displayName parameters remain completely undocumented in both the schema and the description, so the agent has to guess their formats or constraints.

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 clear verb and resource: 'Update a cached user.' It is specific enough to distinguish from non-cached user tools like consumers_update, though it does not explicitly contrast with sibling cached_users operations such as add or delete.

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?

No guidance is given on when to use this tool instead of cached_users_add, cached_users_delete, or consumers_update. It does not mention that the user must already exist, whether this is appropriate for partial updates, or any context where another tool should be preferred.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses the required permission level, implies a read-only operation, and specifies the output format (PEM). It does not mention error behavior, but for a straightforward download operation the key traits are covered.

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 concise, front-loaded sentence conveys the action, resource, selection method, and permission requirement with no wasted words.

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

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

For a simple one-parameter tool with no output schema, the description provides the essential information: what is downloaded, how it is identified, and the permission needed. It is nearly complete, though it could briefly mention the expected return value or explicitly state that no modification occurs.

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 0%, so the description must compensate. It adds meaning by indicating that thumbprint is the certificate identifier used for selection, but it does not specify the thumbprint format or any additional constraints. This is adequate but not rich.

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

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

The description uses a specific verb ('Download') with a concrete resource ('PEM-formatted IdP certificate') and a clear selector ('by its thumbprint'). It clearly differentiates from sibling certificate tools like certificates_list_idp, certificates_set_active_idp, and certificates_verify_idp.

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 use case clear: download a specific IdP certificate when you have its thumbprint. It also states an important precondition ('Requires Read on Infrastructure'). It does not explicitly name alternatives or exclusions, but the context is sufficient for a simple one-parameter 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?

No annotations are provided, so the description carries the full burden. It explicitly discloses the permission requirement and the read-only nature of the operation ('List'). For a simple list tool, this is adequate transparency, though it does not elaborate on output format or any filtering semantics beyond 'available'.

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

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

Two short sentences with no filler. The core purpose is front-loaded, and the permission note is given immediately after. Every word adds value.

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

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

For a zero-parameter read-only list operation with no output schema, the description provides the essential context: what is listed and what permission is required. It is slightly sparse on what 'available' means and what fields the returned certificates contain, but this is 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?

The input schema has zero parameters, so schema coverage is effectively complete and there are no parameter details to clarify. The baseline for zero-parameter tools is 4; the description correctly adds no unnecessary parameter information.

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 ('list') and resource ('all available IdP certificates'), making the tool's function unambiguous. It is clearly distinguished from sibling certificate tools like certificates_download_idp or certificates_verify_idp by the action and scope.

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

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

The description gives clear context: use this to enumerate IdP certificates, and it states the required permission ('Read' on 'Infrastructure'). It does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5, but the context is sufficient for a zero-parameter 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?

With no annotations, the description carries the full burden. It discloses that this is a state-changing operation ('Set the active...') and states an authorization requirement ('Requires Write on Infrastructure'). However, it does not describe side effects, reversibility, failure cases, or what happens to the previously active IdP certificate.

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 brief sentences with no filler. The core action and parameter are front-loaded, and the permission requirement is placed immediately after. Every sentence 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 one-parameter mutation tool with no output schema, the description is minimally viable: it names the operation, the parameter, and a permission requirement. However, it omits usage context relative to siblings, behavior when the thumbprint is invalid, and any result/confirmation information, leaving an agent with only the bare invocation path.

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 0%, so the description must compensate for the parameter's meaning. It only repeats that the operation happens 'by thumbprint', adding little beyond the property name 'thumbprint' and string type. It does not explain what a thumbprint is, how to obtain it, or the expected format.

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 identifies a specific action ('Set') and resource ('the active IdP certificate'), and it specifies the distinguishing input ('by thumbprint'). It is not a tautology, but it does not explicitly contrast itself with sibling certificate operations such as certificates_list_idp or certificates_download_idp.

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 a permission prerequisite ('Requires Write on Infrastructure') but does not explain when to choose this tool over alternatives or mention that listing/verifying certificates would be done via siblings. No when-to-use or when-not-to-use guidance is 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?

With no annotations, the description carries the burden of disclosing behavior. It usefully states the required 'Write' permission on 'Infrastructure', but does not disclose whether the operation has side effects, what the return value looks like, or whether it performs any external validation beyond a simple check.

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 concise sentences with no filler. It front-loads the core purpose and then adds the key permission constraint. Every sentence 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-parameter verification tool, the description covers the purpose and the critical permission requirement. It does not describe the return value, but 'verify whether' strongly implies a boolean outcome, and no output schema exists to require further detail.

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 0%, and the description identifies the parameter as a certificate thumbprint, which adds minimal context beyond the property name itself. It does not specify thumbprint format, length, or how to obtain it, leaving some ambiguity for the agent.

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 action ('Verify whether a certificate... can be used for IdP communication') on a specific resource (certificate by thumbprint). This clearly distinguishes it from sibling tools like certificates_list_idp, certificates_download_idp, and certificates_set_active_idp.

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

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

The description implies when to use the tool (when checking certificate validity for IdP communication) and provides a permission prerequisite, but it does not explicitly contrast with alternatives or state when not to use it. Usage context is present but 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?

With no annotations provided, the description carries the behavioral disclosure burden. It meaningfully discloses that name must be alphanumeric+underscore only and unique, that system consumers cannot be created, and that Write permission on Consumer is required. It stops short of describing return values or failure modes, but the stated constraints add substantial behavioral 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 terse sentences with no filler. The core action is front-loaded, and every sentence adds operational value: creation intent, name constraints, and permission requirement.

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?

Given no annotations, no output schema, and 0% schema coverage, the description is the only source of guidance but only covers the name parameter and permission. It omits semantics for the required maximumSimultaneousInFlightInstructions, all optional parameters, and success/error behavior, so it is not complete enough to invoke confidently.

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 0%, so the description must compensate. It only explains the 'name' parameter's format and uniqueness requirement; the required 'maximumSimultaneousInFlightInstructions' and the six optional parameters are left completely unexplained. This is weak compensation for an eight-parameter schema.

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

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

The description uses a specific verb and resource ('Create a Consumer') and is clearly distinguishable from sibling tools like consumers_list, consumers_get_by_id, consumers_update, and consumers_delete. The naming constraints further clarify the operation's identity.

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

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

The description makes the usage context explicit: call this tool to create a Consumer, and it notes the required 'Write' permission. It does not explicitly mention alternatives like consumers_update for existing records, but for a create operation the context is clear enough.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals important restrictions and permission requirements, which are key behavioral traits for a delete operation. It does not explicitly state that deletion is irreversible or describe side effects, but for a simple ID-based delete these are the most relevant 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?

The description is two focused sentences: the first names the action and target, the second adds constraints and permission. No unnecessary words or redundant schema information.

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

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

For a single-parameter delete tool with no output schema, the description adequately covers the core purpose, restrictions, and required permission. It could mention irreversibility or the expected response, but those are minor omissions given the simplicity of the 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 description coverage is 0%, so the description should compensate by explaining the 'id' parameter, but it only restates 'by ID' without adding format, source, or validation context. The integer id remains minimally documented.

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

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

The description opens with a specific verb and resource, 'Delete a Consumer by ID', which clearly states the action. It is easily distinguishable from the sibling consumers_delete_many by its focus on a single consumer.

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

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

The description provides concrete constraints: system consumers and consumers used by scheduled instructions cannot be deleted, and 'Write' permission on 'Consumer' is required. This effectively tells the agent when the tool will fail, but it does not explicitly contrast with alternative tools like consumers_update or consumers_delete_many.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It does add useful context by specifying the required permission and the batch nature of the request. However, it does not disclose consequences such as irreversibility, partial-failure behavior, or handling of nonexistent IDs, which would be valuable for a destructive delete operation.

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

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

The description is two sentences with no filler: the first states the action and scope, the second states the permission requirement. Every part earns its place and the key information is front-loaded.

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

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

For a low-complexity tool with one required parameter and no output schema, the description is largely complete: it states what is deleted, the batch scope, how targets are identified, and the required permission. Minor details such as behavior for invalid IDs are absent but not critical for a simple batch delete.

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 fully documents the 'ids' parameter as 'Consumer IDs to delete'. The description's 'by their IDs' adds no substantive meaning beyond the schema. Baseline 3 is appropriate when the schema carries the parameter 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?

The description names a specific verb ('Delete'), a resource ('Consumers'), and a clear scope ('multiple... by their IDs in one request'). This distinguishes it from the singular consumers_delete sibling and lets an agent select the correct 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 phrase 'multiple... in one request' clearly establishes this as the batch-deletion variant in contrast to the singular consumers_delete tool. It also states the required 'Write' permission, giving a clear prerequisite. It does not explicitly enumerate when-not cases, but the context is strong enough for a simple one-parameter 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?

With no annotations, the description carries the behavioral disclosure burden. It usefully states the required permission ('Read' on 'Consumer') and implies a read-only operation, but it does not describe not-found behavior, error conditions, or response format.

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, each earning its place: one states the operation and cardinality, the other states the permission requirement. Nothing is redundant or excessive.

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-parameter lookup, the description covers the core operation, the permission needed, and the return scope. It is slightly thin on error behavior, but the low complexity and full schema coverage make it adequate.

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

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

The input schema already documents 'id' as an integer 'Consumer ID' with 100% coverage, so the description adds no new parameter detail. Baseline 3 applies because the schema fully handles parameter semantics.

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

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

The description uses a specific verb ('Return') with a specific resource and scope ('single Consumer by integer ID'), clearly distinguishing it from sibling tools like consumers_list and consumers_get_by_name. The operation is immediately identifiable.

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

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

The description makes clear this is a point lookup by integer ID, which implies the appropriate use case: when the caller knows the Consumer's ID. It does not explicitly mention alternatives or when not to use it, but the context 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?

With no annotations, the description carries the behavioral burden. It adds useful traits: the name is Base64-encoded automatically (so callers should pass plain text) and Read permission on Consumer is required. It does not specify not-found behavior or return shape, but the declared traits exceed the minimum for a simple lookup.

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 conveys the operation, the lookup key, the encoding behavior, and the permission requirement with no redundant wording.

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?

Given the simple one-parameter schema and no output schema, the description is nearly complete: it explains what is returned, how to pass the parameter, and what permission is needed. The only minor gap is not stating the behavior when no Consumer matches, so a perfect score is not warranted.

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

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

Schema coverage is 100%, so the schema already documents the name parameter as plain text. The description adds meaningful value by stating that Base64 encoding happens automatically, preventing the agent from pre-encoding the 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 clear verb ('Return'), a specific resource ('a single Consumer'), and the lookup key ('by name'). This distinguishes it from sibling tools like consumers_get_by_id (by ID), consumers_list (all), and consumers_search (search).

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 use case is implied: use this when you need an exact Consumer by name and have Read permission. However, it does not explicitly state when not to use it or point to alternatives such as consumers_search or consumers_get_by_id, leaving the selection mostly 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?

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly states the required permission ('Read' on 'Consumer') and implies a read-only side-effect-free operation. It does not discuss pagination or response format, but for a simple list-all tool, the permission note is meaningful added 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?

The description is two sentences with no filler. The primary action is front-loaded in the first sentence, and the permission requirement is the only additional sentence. Every word contributes.

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

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

For a zero-parameter list tool, the description covers the essential invocation context: what it returns and the required permission. It could mention response shape or pagination, but the absence of an output schema is less critical when the operation is simply returning all Consumers.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to clarify. The description adds no parameter detail, but the baseline for zero-parameter tools is appropriate since nothing is left undocumented.

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

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

The description uses the specific verb 'Return' with the resource 'all Consumers', clearly indicating a list-all operation. This distinguishes it from sibling tools like consumers_get_by_id, consumers_get_by_name, and consumers_search.

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 word 'all' provides clear context that this tool is for retrieving the full set of consumers rather than a filtered or single record. It does not explicitly name alternatives or exclusions, but for a zero-parameter list, the usage context is reasonably clear.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions 'force' and 'internal cache', but does not explain side effects such as cache invalidation, reloading from source, idempotency, potential disruption, or whether the operation is safe to run repeatedly.

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 sentence of seven words with no filler. The action and target are front-loaded, and the description is appropriately sized for a zero-parameter cache maintenance operation.

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

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

The tool is very simple with no parameters and no output schema, so a one-sentence description is mostly sufficient. However, the absence of usage context and any disclosure of behavioral effects leaves the description slightly incomplete for an agent deciding whether and when to call it.

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

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

The tool has zero parameters and the schema description coverage is 100% (empty schema). There is no parameter burden for the description to carry, so a baseline of 4 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 identifies a specific action ('Force a refresh') and a clear resource ('internal Consumers cache'). It is distinct from sibling tools like consumers_list and consumers_update because it targets cached state rather than exposing or mutating consumer data, though it does not explicitly name alternatives.

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?

No guidance is given about when to invoke this tool versus alternatives, such as after bulk updates, when cache staleness is suspected, or before performing reads. The description does not provide any context, exclusions, or triggers for use.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It usefully discloses the permission requirement and that the tool is read-oriented ('Search', 'Requires Read'). Yet it does not describe the response shape, default pagination behavior, or whether all listed fields are equally valid for both filtering and sorting, which would improve transparency.

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 concise and well-structured: one front-loaded sentence states the core purpose, followed by a compact list of capabilities and the permission requirement. Every sentence earns its place with no redundancy.

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

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

The description is adequate for a search tool: it defines the resource, lists usable fields, and states the required permission. However, because there is no output schema and no explicit comparison to sibling search/list tools, an agent may still be uncertain about the return format and the exact circumstances in which 'consumers_search' is preferable to 'consumers_list'.

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

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

The input schema already covers most parameters with descriptions. The description adds value by explicitly naming the valid filterable/sortable fields: Name, Enabled, MaximumSimultaneousInstructions, OffloadTargetUrl, and SystemConsumer. This supplements the schema's generic OData filter example and helps an agent construct valid queries.

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: 'Search Consumers.' It also lists the exact filterable/sortable fields, which clarifies the tool's scope. However, it does not explicitly differentiate itself from the sibling 'consumers_list' tool, relying on the word 'Search' to imply the distinction.

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

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

The description implies when to use this tool: when searching consumers with filtering, sorting, or pagination. It also notes the required 'Read' permission. However, it does not explicitly state when to prefer 'consumers_list' or other consumer-related search/get tools, leaving usage guidance somewhat implicit.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does disclose a meaningful limitation (system consumers cannot be renamed or disabled) and the required permission level, which is useful context beyond the schema. However, it does not state whether the update is partial (PATCH-style, omitted fields unchanged) or full (PUT-style), nor what happens on invalid ids or failed permission checks — critical behavioral traits 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 short sentences with zero filler: purpose, constraint, and permission each earn their place. The action verb and resource are front-loaded, and no sentence repeats what the name or schema already conveys.

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

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

For a 9-parameter mutation tool with no annotations and no output schema, the description is not complete. The permission and system-consumer constraint are useful, but the description omits the most decision-critical facts: whether unspecified fields are preserved or reset, error behavior for invalid or system-consumer targets, and what the response looks like. An agent cannot invoke this tool correctly with high confidence based on the current information.

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 0%, so the description must compensate, but it does not. 'Renamed' and 'disabled' only weakly map to the name and isEnabled parameters. The remaining seven parameters (applicationUrl, offloadTargetUrl, instructionHandlerUrl, offloadUseWindowsAuth, offloadPostTimeoutSeconds, maximumSimultaneousInFlightInstructions) are left entirely to name-guessing, with no explanation in either the schema or the description.

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

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

The description states a specific verb and resource: 'Update an existing Consumer.' The word 'existing' distinguishes it implicitly from consumers_add (creation) and consumers_delete (removal) among its siblings, and the update verb itself makes the mutation intent unambiguous. However, it does not explicitly name alternatives, so it stops short of full sibling differentiation.

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

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

The description provides a permission prerequisite ('Requires Write on Consumer') and a usage constraint ('System consumers cannot be renamed or disabled'), which implies a when-not: do not attempt to rename or disable system consumers. But it never explicitly routes the agent to an alternative tool (e.g., consumers_add for creation) or states when this tool should be preferred over similar update tools like cached_users_update.

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 discloses important behavioral requirements: Write permission on 'CustomProperty', uniqueness constraints, length limits, and the prohibition on spaces in names. It does not fully describe error behavior or what the response contains, but the core side effects and prerequisites are transparent.

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 concise sentences with no filler. It front-loads the core purpose, then packs constraints and permission requirements efficiently. Every sentence adds necessary information.

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

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

For a 4-parameter create operation with no output schema and no annotations, the description is largely complete: it covers required inputs, optional values, uniqueness/length constraints, and permission requirements. It could add what happens if both typeId and typeName are supplied or what the created object response looks like, but these are minor gaps given the clarity of the rest.

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 0%, so the description must compensate, and it does. It explains the typeId/typeName alternative, name uniqueness and format, and values uniqueness and length. It does not elaborate on the nested value object structure beyond the schema, but the critical selection and validation semantics are present.

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

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

The description opens with a specific verb and resource: 'Create a Custom Property.' It clearly distinguishes this creation tool from the many sibling operations like custom_properties_get_by_id, custom_properties_update, and custom_properties_delete. The mention of optional values and type selection further clarifies the tool's exact scope.

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

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

The description gives clear practical context by stating 'Provide typeId OR typeName' and enumerating constraints for name and values. It does not explicitly name alternative tools or say when not to use this one, but the 'Create' verb and the sibling set make the primary use case unambiguous. The lack of explicit exclusion clauses keeps it just 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the destructive nature via the verb 'Delete', the operational scope ('single... by ID'), and the authorization prerequisite ('Requires Write on CustomProperty'), which is genuinely useful context. It remains silent on failure behavior for non-existent IDs, whether deletion cascades to property values attached to devices or groups, and what a successful response looks like.

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 core action is front-loaded first, and the authorization prerequisite follows as a separate sentence. Every clause earns its place, and the key scoping fact ('single... by ID') leads the first sentence.

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 delete with no nested objects and no output schema, the description covers the essential context: action, scope, and required permission. The only gaps are return/error semantics — what the caller receives on success or when the ID is not found — which are minor given the tool's low complexity but would round out the picture.

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 id as an 'Integer ID' and the baseline is 3. The description's 'by ID' reinforces that the parameter selects the target custom property to delete, adding slight semantic context beyond the bare schema. No additional type, format, or lookup guidance is provided.

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

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

The description uses a specific verb-resource pair ('Delete... Custom Property') and scopes the action precisely to a single record identified by ID. The 'single' qualifier cleanly differentiates it from sibling custom_properties_delete_many, and the delete verb separates it from the add/update/search/get siblings. There is no ambiguity about what this tool does.

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

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

The 'single... by ID' phrasing implies when to use this tool — delete exactly one custom property when its ID is known — and the 'Requires Write on CustomProperty' note states a precondition. However, no alternative is named explicitly; an agent must infer that bulk deletion maps to custom_properties_delete_many or that a lookup tool precedes deletion. This is implied rather than explicit routing guidance.

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

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

No annotations exist, so the description carries the full burden of behavioral disclosure. It does disclose the required permission ('Write' on 'CustomProperty') and the destructive nature of the operation, but it does not mention side effects, partial-failure behavior, or irreversibility. This is adequate but minimal for a destructive multi-ID operation.

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

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

A single, front-loaded sentence states the action and required permission without filler. It could have added a sibling alternative, but as written it is tightly structured.

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

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

For a simple one-parameter destructive tool, the essentials are present: what it does, what it targets, and the required permission. Since there is no output schema, return-value details are not required. However, it lacks usage-routing guidance versus the single-delete sibling and omits behavioral caveats about partial deletions, so completeness is only moderate.

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 0%, so the description must compensate for the undocumented 'ids' parameter. It adds 'by their IDs' to clarify the parameter's purpose, but it does not elaborate on constraints such as non-empty, uniqueness, or count limits. For a simple single-array parameter, this is acceptable but not rich.

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

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

The description uses a specific verb ('Delete') and resource ('Custom Properties'), and clarifies bulk behavior via 'multiple' and 'by their IDs'. It clearly distinguishes from the single-item sibling custom_properties_delete, though it doesn't name it 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?

No guidance is given on when to choose this tool over custom_properties_delete or other custom property operations. The only added context is the permission requirement, with no explicit when/when-not guidance or alternatives.

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 does disclose the core behavior: a read-style retrieval operation that returns one object. But it does not mention what happens for invalid or missing IDs, error behavior, or any other operational 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?

The description is a single, direct sentence with no redundant wording. It front-loads the action and resource, making it easy for an agent to parse quickly.

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 get-by-id operation with one well-documented parameter, the description is largely sufficient. It clearly defines what is retrieved and by what identifier. The main omissions are error/not-found behavior and return format, but these are minor for a tool of this simplicity.

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 only parameter, 'id', is already documented as 'Integer ID'. The description merely reinforces that the tool looks up by ID and adds no additional semantic 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 states a specific action ('Return') and resource ('a single Custom Property') with a clear retrieval scope ('by its ID'). This unambiguously distinguishes it from sibling tools like custom_properties_search or custom_properties_get_by_type_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?

The usage context is implied: use this tool when you have a specific Custom Property ID and need that single record. However, there is no explicit guidance about when not to use it or which alternative to prefer, such as custom_properties_search or custom_properties_get_by_type_id.

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 indicates a read operation ('Return') but does not disclose authentication needs, pagination, response format, or whether any side effects exist. It adds little beyond what the tool name already suggests.

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 short, front-loaded sentence with no wasted words. It conveys the core behavior and key parameter in a compact form appropriate for a simple getter.

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

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

The tool appears simple, but with no annotations, no output schema, and no parameter descriptions, the agent is left without information about return values, error cases, or permissions. The description is adequate for a coarse understanding but not complete enough for confident 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?

The input schema only defines typeId as an integer with no description. The description clarifies that typeId is the ID of a type, which adds some meaning beyond the schema. However, it does not explain what the type ID refers to or how to obtain it, so compensation for the 0% schema coverage is partial.

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

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

The description uses a specific verb ('Return') and resource ('Custom Properties') with the lookup key ('type ID'). It clearly states what the tool does and is distinguishable from siblings like custom_properties_get_by_type_name and custom_properties_get_by_id, though it does not explicitly contrast 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?

There is no guidance on when to use this tool versus the sibling getters (e.g., get_by_type_name, get_by_id). The context is implied by the name and parameter, but no explicit choice criteria or alternatives are mentioned.

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 signals a read operation ('Return') but does not disclose output format, possible empty results, error behavior, authentication needs, or whether 'all' implies pagination. Minimal behavioral context beyond the tool's name.

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

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

The description is a single front-loaded sentence with no filler. Every word contributes to stating the operation and scope, which is ideal for a simple one-parameter getter.

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 read tool with one parameter, the description is minimally viable but leaves gaps: no output schema exists to explain the return shape, no mention of behavior when type name is invalid, and no routing to the analogous get-by-ID tool. It is adequate but not thorough.

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 0%, but the description reinforces that typeName is the type whose custom properties should be returned. It adds no additional meaning such as value format, case sensitivity, or how to discover valid type names, so it only partially compensates for the schema gap.

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

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

The description states a specific verb ('Return'), a resource ('Custom Properties'), and a precise scope ('for a given type name'). It distinguishes this tool from siblings like custom_properties_get_by_type_id and custom_properties_get_by_id by making the lookup key explicit.

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 the caller has a type name rather than a type ID, but it never explicitly contrasts this with custom_properties_get_by_type_id or custom_properties_search. No exclusions or alternative-selection guidance 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Search' implies a read-only collection operation, but the description says nothing about return shape, pagination, default behavior, or side effects, and there is no output schema to fill that 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?

The description is two compact sentences with the action front-loaded and the field list presented efficiently. There is no filler or redundant detail.

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

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

For a simple read-only search with optional pagination/filter/sort parameters, the description plus schema is largely sufficient for correct invocation. It still relies on 'Search' to imply that matching custom properties are returned because 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 high, so skip/take/filter/sortOrder are already documented. The description adds value by naming the valid filter and sort fields (Name, TypeName), which the schema leaves unspecified.

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 identifies the action (Search), the resource (Custom Properties), and the key fields (Name, TypeName). It implicitly distinguishes itself from exact-lookup siblings like custom_properties_get_by_id, but does not explicitly contrast itself with related lookup variants.

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 filter/sort field list gives implied context for when this tool would be useful, but it never states when to prefer search over get_by_id or get_by_tpe_id, nor does it mention exclusions. Usage guidance is present only by 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?

With no annotations provided, the description carries the full behavioral burden. It discloses the auth requirement and the non-obvious semantics of values=null versus values=[], which are not visible in the input schema. It does not mention reversibility, return value, or error behavior, so it is not a perfect 5, but it is far more transparent than a bare 'update' statement.

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, each earning its place: the purpose statement, the critical values behavior, and the permission requirement. There is no filler or restating of schema fields, and the most important update trap is front-loaded right after the purpose.

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

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

The description covers the most important usage gotchas (values null vs []) and the auth requirement, which is essential for calling the tool correctly. However, the behavior of the other updatable fields (name, typeId, typeName), partial-update semantics, and the return payload are all unaddressed. With no output schema and no annotations, those gaps leave an agent partially guessing.

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

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

The input schema has 0% description coverage, so the description must compensate. It adds meaningful, non-obvious semantics for the values parameter: null means unchanged and [] removes all values. However, it provides no guidance for name, typeId, or typeName, leaving those parameters only as raw schema names. This partial compensation warrants a mid-range score.

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

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

The description opens with 'Update a Custom Property,' which names a specific verb and resource. The values=null vs values=[] distinction adds precise scope, and the tool's name clearly differentiates it from sibling add/delete/search tools without needing their schemas.

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

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

The description makes the operation context unambiguous: it is for updating an existing custom property. It also gives a permission precondition, 'Requires Write on CustomProperty.' It does not explicitly enumerate when-not-to-use or name alternatives, but the sibling set (custom_properties_add, custom_properties_delete, etc.) makes the boundary clear.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the creation effect, the uniqueness and length constraints, the prohibition on system types, and the required Write permission on 'CustomProperty'. This goes beyond a bare statement of purpose and provides meaningful behavioral context. It does not cover all edge cases (e.g., duplicate name behavior, return value), but for a creation tool it is reasonably transparent.

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

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

The description is compact and front-loaded with the primary action. Every sentence adds useful information: the action, the name constraints, the system-type exception, and the permission requirement. There is no fluff, repetition, or irrelevant detail, making it efficient and well-structured.

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?

Given the tool is a simple create operation with two parameters, full schema description coverage, and no output schema, the description covers the essential context: the unique name constraint, the max length, the system-type prohibition, and the required permission. It does not describe the response shape or error conditions, but for calling this tool correctly, the provided information is sufficient.

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 repeats the name constraints already present in the schema ('unique, ≤32 chars') and adds the system-type restriction, but this is not parameter-specific. The description parameter is fully documented in the schema, so the description provides no additional semantic value for parameters beyond what the schema already offers.

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 starts with a specific verb and resource: 'Create a new Custom Property Type.' This clearly identifies the operation and the object being acted upon, and distinguishes it from sibling tools like custom_properties_add (which adds a property value) and custom_property_types_list (which lists types). The added constraints (unique name, ≤32 chars, no system types) further pin down the purpose.

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: it is for creating a new custom property type, and it notes that system types cannot be created, which signals a limitation. However, it does not explicitly state when to prefer this tool over related siblings, nor does it mention alternatives such as custom_properties_add for adding property values. The context is clear but the guidance is only implied 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?

With no annotations provided, the description carries the full behavioral burden. 'Return' indicates a read-only operation and 'all available' defines scope, which is helpful. However, it does not describe the response format, ordering, pagination, or any potential access requirements, so transparency 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 a single, direct, front-loaded sentence with no filler or redundant content. Every word contributes to clarifying the operation.

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

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

For a zero-input list operation, the description provides enough context to select and invoke the tool: it returns all custom property types. It does not explain the shape of the returned data, but no output schema exists and the operation is simple enough that the core completion is present.

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

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

The tool has zero parameters and the input schema properties are empty, so there is no parameter ambiguity. The description still adds meaning by clarifying the returned set is 'all available' types, which supports the 0-parameter 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 clearly states the operation: 'Return all available Custom Property Types,' using a specific verb and resource. It is not a tautology because it adds the scope 'all available,' but it does not explicitly differentiate itself from sibling lookup/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 implies an appropriate use case—obtain the complete set of custom property types—but provides no explicit when-to-use guidance or alternatives. For a zero-parameter list operation, the context is reasonably clear, though exclusions are absent.

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 of behavioral disclosure. It indicates a read operation ('Get') but does not explain behavior such as what happens when the FQDN is not found, whether the match is case-sensitive, or whether the FQDN is guaranteed unique. The example clarifies format but does not address runtime outcomes.

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

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

The description is a single, efficient sentence that states the operation, resource, and identifier, followed by a relevant example. No filler or redundant information; every word contributes to understanding.

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

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

For a simple one-parameter getter with no output schema, the description sufficiently communicates what the tool does and what input it expects. The absence of error-handling details is a minor gap for such a straightforward operation, but the core information needed to call it correctly is present.

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

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

The schema already provides 100% parameter coverage with a clear description for 'fqdn'. The tool description adds value by giving a concrete format example ('hostname.domain.com'), which reinforces the expected input shape beyond the schema's 'Device FQDN'. This extra semantic clarity justifies a score above 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 clearly states the action: 'Get a single device' using a specific identifier, 'fully-qualified domain name (FQDN)'. This distinguishes it from sibling tools like devices_get_by_tachyon_guid and devices_search by specifying the exact lookup key. The verb-resource-scope structure 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 when you know a device's FQDN and need a single matching record, but it doesn't explicitly contrast with alternatives such as devices_search or devices_list. No exclusions or conditions are provided, so the guidance relies on inference rather than explicit 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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It clarifies that the Tachyon GUID is assigned by the 1E agent, which is useful context, but it does not disclose what happens when no device is found, whether the response is a full device object, or any error behavior. For a simple read-only getter, this is acceptable though 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?

A single, front-loaded sentence contains the action, resource, and key semantic context with zero filler. Every word 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-parameter read operation with no output schema, the description is largely complete. It states what the tool does and what identifier it uses. Minor gaps, such as not-found behavior and response shape, are low-risk for this simple getter.

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 meaning beyond the schema by explaining that the Tachyon GUID is the unique identifier assigned by the 1E agent, giving an agent useful context about the parameter's source and significance.

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 ('Get'), a specific resource ('a single device'), and the exact lookup key ('Tachyon GUID'), clearly distinguishing this tool from siblings such as devices_get_by_fqdn and devices_search. The parenthetical explanation of what a Tachyon GUID is adds helpful clarity.

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 a Tachyon GUID is available, but it provides no explicit guidance about when to use this tool versus alternatives like devices_get_by_fqdn, devices_list, or devices_search. No exclusions or alternatives are mentioned.

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 burden of basic behavioral disclosure. It makes the read-only nature clear through 'Get' and identifies the input as a device FQDN, but it does not disclose what happens when the device is not found, what fields the returned groups contain, or whether any permissions are required.

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

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

The description is a single focused sentence with no filler. It front-loads the action and resource, then clarifies the identifier. Every word adds value.

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?

Given the low complexity of a single-parameter lookup, the description is nearly complete: it states the input and the conceptual output. It does not describe response structure or error behavior, and there is no output schema to cover that, so it stops just short of fully complete.

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

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

The schema provides only a bare string parameter with 0% description coverage. The description compensates by explaining that the fqdn parameter refers to the device being queried, adding meaning beyond the schema. It still lacks format details or examples, but the key semantic is clear.

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 action ('Get'), a specific resource ('Management Groups'), and the identifying key ('FQDN'). This clearly differentiates it from sibling tools such as devices_get_by_fqdn, which returns device details, and management_groups_get_all_devices, which returns devices for a group.

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

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

The description implies when to use the tool: when you need the management groups belonging to a device identified by FQDN. However, it gives no explicit guidance about alternatives, prerequisites, or cases where another tool such as devices_get_by_fqdn would be more appropriate.

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 verb 'List' and the 'all' scope clearly imply a read-only, unfiltered enumeration, which is the main behavioral trait. However, with no annotations provided, the description carries the full burden; it does not mention pagination, response shape, result limits, or any other operational behavior beyond the basic listing action.

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 that communicates the purpose and scope immediately. There is no filler, repetition, or unnecessary detail.

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

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

For a parameterless list endpoint, the description is largely sufficient: an agent can invoke it with no arguments and understand that it returns all registered devices/agents. The absence of any output schema and any mention of pagination or result size leaves a minor gap, but it does not prevent 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?

The tool has zero parameters, so there are no semantics to clarify and the schema is fully covered by construction. The baseline of 4 applies because no parameter-level explanation is needed.

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

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

The description uses a specific verb ('List') and identifies the resource ('registered devices/agents known to the 1E platform'), making the core purpose clear. However, it does not explicitly contrast itself with sibling tools like devices_search or devices_get_by_fqdn, so sibling differentiation is only implicit.

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

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

There is no guidance on when to use this tool versus alternatives such as devices_search, devices_get_by_fqdn, or devices_summary. The word 'all' hints at an unfiltered inventory, but the description never states when to choose this over a search or lookup 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does explain includeInherited behavior and the pagination/sort inputs, and the read-only nature of a search is reasonably implied. However, it does not describe the response shape, pagination defaults, maximum page sizes, or any access 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?

The description is concise and front-loaded with the main purpose, followed by parameter details and the includeInherited caveat. It is efficient, though the phrase 'Body is a SearchPostModel' is somewhat redundant with the schema and the unsupported 'filter' claim introduces mild ambiguity.

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

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

The description is not complete for a search tool with no annotations and no output schema. It leaves the response format and pagination behavior unspecified, offers no comparison to sibling device tools, and claims filter support that is not reflected in the input schema, making it harder for an agent to know exactly what this endpoint returns and how to use it effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some value by clarifying 'start' as an integer offset and explaining the effect of includeInherited, but it mostly paraphrases the schema's existing parameter descriptions without adding substantial 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?

The description clearly states the verb ('Search'), the resource ('devices'), and the core capabilities (filter/sort/pagination), which distinguishes it from sibling get/list tools like devices_get_by_fqdn and devices_list. It does not explicitly name alternatives, and the mention of 'filter' is slightly misleading because the input schema exposes no filter parameter.

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

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

There is no guidance on when to use this tool versus the many sibling device tools such as devices_list, devices_get_by_fqdn, or devices_summary. The description implies a search use case but does not state when not to use it or which alternative to choose for simple listing or direct lookup.

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?

There are no annotations, so the description must disclose behavior on its own. It only indicates a read operation for summary data; it does not explain pagination behavior, how the optional filter works, what statuses are returned, or any other behavioral 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?

The description is a single, front-loaded sentence with no filler. It is concise, though the vague 'optional filter' phrase slightly reduces precision.

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 annotations, no output schema, and 0% parameter coverage, the description leaves too much unspecified: pagination parameters, filter syntax, what the summary contains, and expected response shape. It is minimally viable but incomplete.

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 0%, and the description fails to explain the start and pageSize parameters. Worse, it mentions an 'optional filter' even though no filter parameter exists in the schema, which could mislead an agent.

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

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

The description uses a clear verb-resource pair ('Get a summary count/status of devices') and the 'summary' qualifier distinguishes it from devices_list and devices_search. However, it references an 'optional filter' that has no corresponding parameter in the schema, creating slight ambiguity.

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

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

No guidance is given about when to choose this tool over devices_list or devices_search. The description implies it is for aggregated counts/status, but it does not state conditions, exclusions, or alternatives.

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 disclosure burden. It adds useful behavioral context by noting the return value includes the full schema and parameters needed. However, it does not explicitly state that this is a read-only operation, whether it can return null/error for missing IDs, or any authentication 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?

The description is a single focused sentence that states the action, the resource, the lookup key, and a key behavioral detail about the return value. There is no filler or redundant phrasing.

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-parameter retrieval tool, the description is adequately complete: it names the resource, the identifier, and the important return detail that the full schema is included. It could mention not-found behavior or how to route to sibling lookup tools, but given the low complexity and full schema coverage, these are minor gaps.

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 only parameter 'id' is already described as 'Integer ID'. The description repeats this information without adding new semantic detail such as where the ID comes from or how it should be formatted, so the schema already does the heavy lifting.

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

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

The description clearly states a specific verb ('Get'), a resource ('Instruction Definition'), and the lookup key ('by its integer ID'). It is immediately distinguishable from sibling operations like instruction_definitions_list, instruction_definitions_search, and instruction_definitions_get_by_name.

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 that this tool is appropriate when an integer ID is already known, and the sibling instruction_definitions_get_by_name exists as an alternative for name-based lookup. However, it does not explicitly state when to use this tool over the alternatives or mention searching/list as a way to obtain an ID.

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 exact-match lookup semantics, but it does not mention what happens when no definition matches, whether matching is case-sensitive, or what the response contains beyond implying definitionId and parameter schema.

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

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

Two sentences, no filler, and the primary action is front-loaded. The second sentence earns its place by connecting the tool to a concrete workflow step.

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

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

For a simple one-parameter getter with no output schema, the description provides enough workflow context: call it before sending an instruction, and use the result to obtain the definitionId and parameter schema. The main gap is not-found/error behavior, which would strengthen completeness.

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

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

The input schema provides only 'name' as a string with no description, so the description must compensate. 'Exact name' adds meaningful semantics by telling the agent the value must be the full exact name rather than a partial or fuzzy match, though it stops short of specifying format or case-sensitivity.

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

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

The description opens with a specific verb and resource: 'Get an Instruction Definition by its exact name.' The 'exact name' qualifier clearly distinguishes this from the sibling tools instruction_definitions_list, instruction_definitions_search, and instruction_definitions_get_by_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?

The description gives a clear use case: 'Use this to find the definitionId and parameter schema before sending an instruction.' It does not explicitly name alternative tools or when not to use them, but 'by its exact name' implies the routing decision versus by-ID or search-based retrieval.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly implies a read-only listing operation and explains the domain concept, but it does not disclose return format, pagination behavior, or how the instructionType filter behaves (e.g., exact match vs partial match).

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

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

The description is a single, well-structured sentence that front-loads the action and resource, then clarifies the domain object in a parenthetical. There is no redundant information or 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 list tool with one optional parameter and no output schema, the description plus schema is largely sufficient. The only notable gap is the lack of guidance on how this tool relates to the search/get-by-name/get-by-id sibling tools.

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

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

The schema already documents the single optional parameter with 100% coverage, stating it is an optional filter by instruction type. The description adds no new details about format, allowed values, or filtering semantics, so it provides minimal value beyond the schema.

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