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

With no annotations provided, the description carries full burden. It clearly states the tool is read-only ('gathers data only') and details the data collected (consumer group state, lag, topic health, cluster health). Lacks mention of permissions or potential side effects, but for a diagnostic tool this is adequate.

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?

Description is concise with 4 sentences plus a bullet list of return components. First sentence states purpose, then explains tool's role, then parameter, then return value. 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?

Given the tool's complexity and the presence of an output schema (not provided), the description covers purpose, parameter, and return structure. However, it lacks information on error cases or prerequisites (e.g., consumer group existence). Still sufficient for an agent to use correctly.

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

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

The schema has 0% description coverage, so the description must compensate. It adds a brief explanation for group_id: 'The consumer group ID to analyze.' While minimal, it provides necessary context for the single required 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?

States specific verb+resource 'Analyze consumer lag and identify potential root causes', clearly distinguishing it from siblings like get_consumer_lag which only retrieves raw lag data. The description makes its diagnostic nature 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?

Provides context that the tool gathers data only and the LLM agent interprets results, implying it should be used for root cause analysis rather than direct lag retrieval. However, it does not explicitly compare to alternatives like describe_consumer_group or get_consumer_lag.

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, description carries full burden; it discloses write nature and cancellation constraints, though lacks details on outcome (e.g., status change) or idempotency.

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?

Very concise: three sentences plus args, front-loaded with action and constraints, 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?

Complete for a single-param cancellation tool with output schema; covers purpose, usage constraints, and parameter. Could optionally mention error handling or idempotency.

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%, but description explains param 'work_request_id' is an OCID for the work request to cancel, adding value beyond the schema's title.

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?

Clearly states verb 'Cancel' and resource 'in-progress OCI work request', distinguishing from sibling tools like get_work_request or list_work_requests.

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

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

Explicitly specifies when to use (only in-progress requests) and when not to (completed/failed), and mentions prerequisite --allow-writes.

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 were provided, so the description carries the burden. It discloses that the operation requires confirmation, is high risk, and affects IAM policies. However, it does not mention whether the operation is synchronous or asynchronous, its reversibility, or any downtime implications. The existence of an output schema is not leveraged.

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, with a clear opening statement followed by risk warnings and arguments. It is well-structured and front-loaded. However, the arguments list could be formatted more clearly (e.g., bullet points) to improve readability.

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 tool with two required parameters and an existing output schema, the description covers the main purpose, risk, and arguments. It lacks prerequisites (e.g., required permissions) and does not explain the return value, though the output schema may cover that. Additional context like typical use cases 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?

Schema description coverage is 0%, so the description must compensate. It provides basic explanations: 'cluster_id: OCI Kafka cluster OCID to move' and 'target_compartment_id: Target OCI compartment OCID.' This adds meaning beyond the parameter names but lacks details like OCID format or validation rules.

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 tool's purpose: 'Move an OCI Kafka cluster to a different OCI compartment.' This is specific, uses a strong verb ('move'), and identifies the exact resource (OCI Kafka cluster) and target (different compartment). It distinguishes itself from sibling tools like 'oci_kafka_change_cluster_config_compartment' which deals with config compartment.

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 mentions it requires --allow-writes, is high risk, requires confirmation, and changes IAM policies. This guides usage by warning about prerequisites and consequences. However, it does not explicitly contrast with alternatives or state when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It discloses that writes are needed and that moving a compartment affects IAM policies and user access. However, it does not mention whether the operation is reversible, any side effects beyond IAM, or if it creates a work request (given sibling tools for work requests).

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 short and well-structured. It begins with a one-sentence summary, then provides behavioral context and explicit parameter definitions. Every sentence adds value, and the information is front-loaded for quick 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?

Given the presence of an output schema, the description need not elaborate on return values. It covers purpose, parameters, and key behavioral impacts. However, it could be improved by mentioning whether the operation is synchronous or if it triggers a work request, especially given siblings for work request management.

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. The 'Args' section adds meaningful context to both parameters: 'cluster_config_id' is described as an 'OCI cluster config OCID' and 'target_compartment_id' as a 'Target OCI compartment OCID,' clarifying what each value represents beyond the schema titles.

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 'Move an OCI Kafka cluster configuration to a different compartment,' using a specific verb and resource. This action is distinct from siblings like 'change_cluster_compartment' (which moves the cluster itself) and other config-related 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 explains that the tool requires '--allow-writes' and notes that moving a config changes IAM policies and user access. While it provides useful prerequisites and implications, it does not explicitly compare to alternatives like 'change_cluster_compartment' or indicate specific scenarios where this tool is 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?

No annotations provided, so description carries full burden. It reveals that the new connection takes effect immediately, no restart required, and all existing clients are reset and will reconnect. Also mentions persistence behavior. This is thorough and 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?

Well-structured: purpose sentence, bullet-pointed usage scenarios, behavioral note, then clear parameter list. Every sentence provides necessary information 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?

Covers runtime behavior, immediate effect, client reset, and persistence. While output schema exists (not shown), the description doesn't mention return values or error handling. For a tool with 7 parameters and runtime effects, it is largely complete but could mention success/error responses.

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 has 0% description coverage, but description provides detailed explanations for all 7 parameters, including examples, defaults, and conditions (e.g., ssl_ca_location fallback). This adds high value 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?

Description starts with a specific verb 'Configure or update' and resource 'Kafka cluster connection details at runtime'. It clearly distinguishes from sibling tools that manage clusters, topics, etc., by focusing solely on connection configuration.

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

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

Explicitly lists three 'Use this tool when' scenarios (no cluster configured, switch cluster, new credentials). Could be improved by also stating when not to use, but the guidance is clear and helpful.

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 discloses important behaviors: it requires --allow-writes, is high risk, and is asynchronous. It also directs the user to a progress-tracking tool. This adds value beyond the schema, but could further explain recovery steps or cost implications.

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 well-structured: a clear first sentence, followed by key warnings, then a bullet list of parameters. Every sentence adds value, though the parameter list could be slightly more concise by grouping defaults.

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, the description covers the core purpose, risk, async nature, and all parameters. It does not describe the output schema, but per rules, that is acceptable since an output schema exists. It is sufficiently complete for an AI agent to use the tool correctly.

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

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

The input schema has 0% description coverage (only titles and defaults). The description compensates by listing all 9 parameters with clear, human-readable explanations of their purpose, adding significant 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 tool creates a new OCI Streaming with Apache Kafka cluster. The verb 'Create' and the resource 'cluster' are specific, and the tool is distinct from siblings like update, delete, scale, etc.

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 notes that it requires --allow-writes, is a high-risk operation requiring confirmation, and is asynchronous with a recommendation to use oci_kafka_get_work_request for progress tracking. This provides context for safe usage, though it does not explicitly contrast with when to use alternative 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?

No annotations are provided, so the description carries the full burden. It mentions the --allow-writes requirement and the lifecycle step (apply via update_cluster), but does not elaborate on other behavioral aspects such as idempotency, rate limits, or error conditions. This is adequate but not detailed.

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: it opens with the core purpose, mentions a key requirement, explains the lifecycle, and then lists parameters. Every sentence adds value without redundancy.

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

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

Given the tool has 3 parameters, 0% schema coverage, no annotations, and an output schema (not shown), the description sufficiently covers the tool's purpose, prerequisite, and usage. It lacks detailed return value info but that is expected with an output schema. Overall, it's complete for this create action.

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. It lists all three parameters (display_name, compartment_id, freeform_tags) with brief, clear explanations that go beyond the schema's basic titles and types. This is helpful, though the description could be more detailed for tags or compartment_id.

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

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

The description clearly states the tool creates a new OCI Kafka cluster configuration, defined as a named, versioned container for Kafka broker settings. It distinguishes itself from sibling tools like oci_kafka_update_cluster_config and oci_kafka_create_cluster.

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 specifies the prerequisite 'Requires --allow-writes' and advises using oci_kafka_update_cluster after creation to apply the config. It gives clear usage context but does not explicitly state when not to use this tool. Overall, it provides good 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 provided, the description carries the full burden. It mentions the requirement for --allow-writes and indicates the return value, but does not disclose other behavioral traits like idempotency, cost implications, or side effects beyond creation.

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 extremely concise, with the purpose in the first sentence, followed by a prerequisite line, a structured Args section, and a return statement. No unnecessary 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?

Given the tool's simplicity (3 parameters, no nested objects) and the presence of an output schema, the description covers the essential behavior. It could be considered complete, but some minor details (e.g., whether the topic is created immediately, any naming constraints) are omitted.

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 description adds significant meaning beyond the input schema, which has 0% schema description coverage. It names all three parameters (topic_name, num_partitions, replication_factor), explains their purpose, and provides default values, fully compensating for the schema gaps.

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 'Create a new Kafka topic' with a specific verb and resource. It distinguishes from sibling tools like delete_topic, update_topic_config, list_topics, and describe_topic by focusing on creation.

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 includes a prerequisite ('Requires --allow-writes to be enabled'), which provides clear context for when the tool can be used. However, it does not explicitly contrast with alternatives or state when not to use it.

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

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

No annotations are provided, so the description carries full burden. It clearly states permanent data loss, high risk, asynchronous behavior, and the need for confirmation. Fully 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?

Very concise: two sentences plus a bullet list. The main purpose is front-loaded, and every sentence provides essential information.

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

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

Given the simple delete operation with one parameter and an output schema (so return values are covered by schema), the description provides complete guidance on usage and consequences.

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 single parameter cluster_id is described with its format (OCI Kafka cluster OCID) and example pattern, adding value beyond the schema's title alone.

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

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

The description clearly states it deletes an OCI Kafka cluster permanently. It distinguishes itself from sibling tools that perform other operations like create, update, or delete configs/topics.

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

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

Explicitly mentions the --allow-writes requirement, high-risk nature, and confirmation needed. Also guides to use oci_kafka_get_work_request for async tracking. Does not explicitly state when not to use, but alternatives are clear from siblings.

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 fully covers behavioral traits: it is a destructive, permanent operation that deletes all versions and affects referencing clusters. It discloses the need for confirmation and the '--allow-writes' flag.

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 well-structured with a main sentence followed by bullet-like lines. It is concise but includes all necessary warnings. Could be slightly tighter but earns its length.

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 (one parameter, destructive action) and the presence of an output schema, the description covers essential aspects: permanent deletion, version scope, and dependent resources. No return value explanation needed due to output schema.

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 only one parameter with no description (0% coverage). The description's Args section adds the OCID pattern 'ocid1.kafkaclusterconfig.*', which provides valuable context for the parameter 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 states the verb 'Delete' and the resource 'OCI Kafka cluster configuration', with the qualifier 'permanently'. It distinguishes from siblings like delete_cluster and delete_cluster_config_version by specifying it deletes the entire config and all versions.

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

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

The description explicitly requires '--allow-writes', labels the operation 'HIGH RISK' needing confirmation, and advises updating referencing clusters before deletion. It implies when not to use (only when certain), and alternatives like delete_cluster_config_version are available among siblings.

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?

Discloses irreversibility and required writes permission. No annotations provided, so description adds value. Could mention impact on active version if any, but adequate.

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?

Concise, front-loaded with purpose, then prerequisites and args. No unnecessary words. Excellent structure.

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

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

Covers purpose, usage, parameters, and behavior. Output schema exists to handle return values. Slightly incomplete on success response, but acceptable.

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 description coverage, description adds format guidance for cluster_config_id (OCID pattern) and clarifies version_number is integer. Both parameters are well-explained.

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 it deletes a specific version of an OCI Kafka cluster configuration, distinguishing it from siblings like delete_cluster_config (which deletes entire config) and delete_cluster.

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 explicit prerequisite (--allow-writes) and warns against deleting an applied version. Lacks explicit comparison to alternatives like delete_cluster_config, but context is clear.

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

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

With no annotations, the description carries the full burden. It clearly warns that the operation is destructive, high risk, requires confirmation, and that the group must be empty. This provides sufficient transparency for an agent to understand the implications.

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 with a clear structure: purpose, warnings, prerequisites, argument, and return. It front-loads the risk information, making it efficient for quick reading.

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 (single-param delete operation) and the presence of an output schema, the description covers the essentials: what it does, when to use it, and what it returns. It doesn't explain error handling, but that's acceptable for this level of complexity.

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 description for the only parameter (group_id) is 'The consumer group ID to delete,' which adds little beyond the schema's title 'Group Id.' Since schema coverage is 0%, the description is the sole source, but it lacks further detail like format or example.

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 'Delete a consumer group,' specifying the verb and resource. It distinguishes from sibling tools like list_consumer_groups and describe_consumer_group by focusing on deletion and adding context about the destructive nature.

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

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

Explicitly states prerequisites: group must have no active members (EMPTY state), requires --allow-writes, and requires confirmation. It doesn't explicitly say when not to use or mention alternatives, but the conditions are clear enough for correct usage.

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 provided, so description carries full burden. Clearly labels as destructive and high risk, mentions prerequisites, and indicates return value. Does not cover all side effects but is sufficient for a simple delete.

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

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

Extremely concise with a clear warning upfront, structured args section, and 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?

Given the simple operation and presence of an output schema, the description covers destructiveness, prerequisites, and parameter. Does not mention error handling or topic existence checks, but acceptable for a delete 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 0%, so description must add meaning. The parameter 'topic_name' is described as 'Name of the topic to delete,' which is minimal. No additional constraints or format details are given.

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 'Delete a Kafka topic' with a strong warning. It distinguishes from siblings like create, describe, and update topic 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?

Provides usage context (requires --allow-writes, high risk, confirmation needed) but does not explicitly state when to use vs. other deletion tools (e.g., delete_cluster, delete_consumer_group).

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 provided, so the description must carry the burden. It discloses the return type (state, coordinator, assignor, members) but does not mention permissions, rate limits, or whether it is read-only. The description is moderately transparent but lacks operational 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 concise, with only three sentences. The main purpose is front-loaded, and there is no redundant information. 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?

Given the tool has an output schema, the description doesn't need to detail return structure, but it still lacks usage context (e.g., when to use, error conditions). The description is adequate but not fully comprehensive for a single-parameter 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?

The only parameter, group_id, is described as 'The consumer group ID to describe', which adds meaningful context beyond the schema's title 'Group Id'. Schema coverage is 0%, but the description compensates well.

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 'Get detailed information' and the resource 'a consumer group'. It effectively distinguishes from sibling tools like list_consumer_groups and get_consumer_lag by focusing on detailed group info.

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?

While the description implies use when detailed info is needed, it lacks explicit guidance on when to use this tool vs alternatives like list_consumer_groups or get_consumer_lag. No exclusions or prerequisites 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 provided. Description implies read-only behavior by stating it returns information, but does not explicitly confirm no side effects or required permissions. Adds moderate 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 concise sentences plus a parameter line. Front-loaded with purpose, then details, then usage. No filler.

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

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

With output schema present, description covers return values adequately. Could mention error cases or prerequisites, but overall complete for a read 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?

Only parameter is topic_name. Description adds 'Name of the topic to describe,' which is minimally helpful beyond the schema. Schema has 0% description coverage, so description compensates slightly.

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 'Get detailed information about a specific Kafka topic' and lists specific return values (partition details, config). It distinguishes from sibling tools like list_topics.

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

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

Explicitly says 'Use this to inspect a topic's health and config.' Provides clear context but does not explicitly mention when not to use 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?

The description fully discloses the return values (total partition count, under-replicated count, details of affected partitions with missing replicas), which is transparent given no annotations. It does not explicitly state that the tool is read-only, but the detection nature implies no side effects.

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

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

The description is three sentences, each earning its place: first defines the action, second explains significance, third lists return values. No redundant words, and the most critical information appears first.

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 provides sufficient context for a detection tool with no parameters and an output schema mentioned. It covers what the tool does, why it matters, and what it returns. A minor gap is the lack of explicit cluster scoping, but the tool name implies 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?

There are no parameters, so the schema is trivially covered at 100%. The description adds value by explaining the detection context and output, which is more than the empty schema provides.

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

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

The description clearly states the tool detects under-replicated partitions, explains the condition (ISR count < replica count), and distinguishes it from sibling tools like get_cluster_health or get_partition_skew by focusing specifically on replica synchronization.

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 explains that under-replicated partitions indicate data durability risks and lists common causes (broker failures, network issues, disk problems), giving users context for when to use the tool. However, it does not explicitly state when to avoid using it or compare it with 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 burden. It states the tool is a disable operation (mutating) and mentions the required --allow-writes flag. It does not detail reversibility or impacts, but the purpose is straightforward.

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: a clear purpose sentence, followed by prerequisite/usage guidance, and then a parameter definition. No redundant 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?

Given the low complexity (1 parameter, no annotations, but has output schema), the description covers the tool's purpose, when to use it, and the parameter meaning. It does not describe the return value, but the output schema likely does. Slightly more detail on consequences 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 input schema has one parameter with no description, but the tool description adds 'cluster_id: OCI Kafka cluster OCID' in the Args section, which clarifies the parameter's meaning. However, schema coverage is 0% and the description could provide more detail like constraints or 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 states 'Disable the superuser for an OCI Kafka cluster' which is a specific verb-resource pair. It distinguishes from sibling tools like oci_kafka_enable_superuser and oci_kafka_delete_cluster.

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

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

The description provides clear usage context: 'Use this after completing administrative tasks to restore least-privilege access' and a prerequisite ('Requires --allow-writes'). It does not explicitly state when not to use or list alternatives, but the sibling enable_superuser is the natural counterpart.

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, description discloses superuser access, the optional duration parameter, and that without a duration it stays enabled until explicitly disabled, plus a warning for careful use.

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

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

Four concise sentences: action, prerequisite, warning, and parameter descriptions. No redundancy, front-loaded with 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?

Covers purpose, parameters, and key behavioral aspects (duration behavior, need for --allow-writes). With no output schema needed (the description doesn't require return info), it's nearly complete.

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

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

Both parameters are described with their purpose and behavior beyond schema titles; the duration parameter's default and effect are explained, adding value 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?

Clearly states it enables superuser for an OCI Kafka cluster, distinguishes from the sibling 'oci_kafka_disable_superuser' by specifying enablement and notes the superuser's full administrative access.

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?

Specifies a prerequisite ('Requires --allow-writes') and advises sparing use with a time limit, but does not explicitly list when not to use or mention alternative tools beyond the implied complement disable.

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, and the description does not disclose any behavioral traits beyond the fact that it returns configuration. It omits information about side effects, permissions, or rate limits. The read-only nature is implied but not confirmed.

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, directly stating the purpose and content. It is concise without 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?

Given no parameters, a simple get operation, and the presence of an output schema, the description adequately covers what the tool does. It could mention prerequisites or error conditions, but the current information is sufficient for safe 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 0 parameters, so no parameter documentation is needed. Baseline is 4, and the description adds no parameter information, which is acceptable given zero 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 clearly states 'Get Kafka cluster configuration settings' and specifies the content: 'broker-level configuration including log settings, replication defaults, and other cluster parameters.' This distinguishes it from sibling tools like get_cluster_config_version or get_cluster_health.

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 includes 'Use this to inspect current cluster settings,' providing clear context for when to use the tool. However, it does not explicitly exclude alternatives or mention when not to use it.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only states it retrieves a version but does not mention safety (read-only), idempotency, permission requirements, or behavior on missing versions. This is insufficient for a tool with no annotations.

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

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

The description is extremely concise: two sentences plus an argument list. It is front-loaded with the main action and includes only necessary details. Every part 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?

The tool has an output schema (not shown) which reduces the need to explain return values. However, the description lacks prerequisites or error context. For a simple read operation, it is fairly complete but could mention that the config version must exist.

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 adds meaningful context: for 'cluster_config_id' it specifies the OCID format (ocid1.kafkaclusterconfig.*), and for 'version_number' it clarifies it is an integer version. This adds substantial value beyond the schema titles.

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' and the specific resource 'a specific version of an OCI Kafka cluster configuration'. It distinguishes from sibling tools like 'get_cluster_config' and 'list_cluster_config_versions' by specifying retrieval by version number.

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 for retrieving a specific version but lacks explicit guidance on when to use this tool over alternatives such as 'list_cluster_config_versions' or 'get_cluster_config'. No when-not or exclusion 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 bears the full burden. It transparently lists return data (cluster ID, controller ID, broker details, topic count) and implies a read-only operation. No side effects are stated, which is appropriate for a health 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 sentences, front-loaded with the main purpose, followed by return details and usage advice. Every sentence is informative and concise.

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

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

The tool has no parameters and an output schema. The description covers the return values and usage context, making it fully actionable. No gaps are apparent.

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

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

There are no parameters, so the baseline is 4. The description adds value by detailing the return fields, which helps the agent understand what the tool provides.

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

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

The description clearly states 'Get Kafka cluster health status' with specific outputs like broker list, controller info, and topic count. This distinguishes it from sibling tools focused on deletion, configuration, or topic management.

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

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

It explicitly says 'Use this to verify cluster connectivity and check overall cluster health,' providing clear context. However, it lacks guidance on when not to use it or alternatives for more detailed queries.

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 password is masked and mentions the 'configured' field in the output. While it does not cover all possible behavioral aspects (e.g., authorization requirements), it provides key behavioral details beyond the tool's basic function.

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 at six sentences, well-structured with a clear first sentence stating the main purpose, followed by bullet-pointed use cases, and ending with a conditional action. Every sentence adds value 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?

Given that there are no parameters and an output schema exists (implied but not shown), the description provides sufficient context: it explains the tool's purpose, key output elements (configured, masked password), and when to use an alternative tool. This is complete for the tool's complexity.

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 no parameters, so the input schema is empty with 100% coverage. The description does not need to add parameter semantics, and it correctly omits any param details. The baseline for zero parameters is 4.

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 'Show' and the resource 'current Kafka connection configuration'. It lists specific use cases such as checking if a cluster is configured, verifying the connected cluster, and confirming security settings, effectively distinguishing it from sibling tools like oci_kafka_configure_connection.

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

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

The description explicitly tells when to use the tool: 'Check whether a cluster is already configured before calling other tools.' It also provides an alternative action: if 'configured' is false, call oci_kafka_configure_connection first. This offers clear guidance on usage context.

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 states the tool is a read operation ('Get') and describes returned data, but does not disclose potential errors, authentication requirements, or behavior when the group_id is invalid. This is adequate for a straightforward retrieval tool but lacks depth.

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, with four sentences each serving a purpose: purpose, parameter, return value, and usage. 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?

Given the simplicity of the tool (one parameter, output schema exists), the description covers the essentials: what it does, what parameter is needed, and what is returned. It could mention that it works across all assigned partitions, which it does, and provides a practical use case. Minor gap: no mention of pagination or limit, but not needed 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%, so the description must compensate. It fully explains the only parameter group_id: 'The consumer group ID to check lag for.' This adds necessary meaning that the schema alone does not provide.

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

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

The description clearly states the action ('Get consumer lag') and the resource ('for a consumer group across all assigned partitions'). It effectively distinguishes from sibling tools like oci_kafka_describe_consumer_group (group metadata) and oci_kafka_reset_consumer_offset (mutating offset).

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 clear use case: 'Use this to diagnose slow consumers or processing bottlenecks.' However, it does not explicitly mention when not to use it or provide alternatives among sibling tools, which would improve clarity.

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 has full responsibility for behavioral disclosure. It only states it returns metadata and latest version, but does not mention authentication, error conditions, or side effects. Given it's a read operation, more detail on expected behavior would be beneficial.

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 at three sentences plus the Args line, front-loaded with the main purpose. It efficiently covers the key aspects without unnecessary verbosity.

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 has one required parameter with no enums and an output schema exists, the description adequately covers what is needed. It mentions the return value and links to related tools, making it fairly complete for a simple get operation.

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

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

The schema has 0% coverage, but the description adds an Args section that explains cluster_config_id as an OCID with the pattern ocid1.kafkaclusterconfig.*. This provides meaningful context beyond the schema's type definition, compensating for the lack of 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 clearly states it retrieves detailed information about an OCI Kafka cluster configuration, specifying it returns config metadata and latest version. However, there is a sibling tool 'oci_kafka_get_cluster_config' with a similar purpose, and the description does not differentiate between 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?

The description explicitly suggests using oci_kafka_list_cluster_config_versions to see all versions, providing a clear alternative context. It does not include when-not-to-use or prerequisites, but the guidance is clear enough for this specific 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 behavioral disclosure burden. It describes the tool as a read operation ('returns' data) and lists output fields, which is sufficient for a simple getter. However, it does not explicitly state idempotency, required permissions, or error scenarios, leaving minor gaps. The name and return description imply read-only safety.

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: a one-line purpose, a bullet-like list of return fields, parameter explanation, usage examples, and fallback guidance. Every sentence earns its place with no redundancy 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?

For a simple read tool with one optional parameter and an output schema (implied), the description is fully complete. It covers purpose, returned data, parameter semantics, and usage flow including fallback to a sibling tool. The output schema handles the return structure, so no further description is needed.

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 adds critical semantics: it explains the format of cluster_id ('ocid1.kafkacluster.*'), notes it defaults to the OCI_CLUSTER_ID environment variable if omitted, and provides usage context. This adds substantial value beyond the bare schema definition.

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 tool's purpose with a specific verb ('Get') and resource ('OCI control plane metadata for a Kafka cluster'). It enumerates the exact fields returned (OCID, name, state, etc.), distinguishing it from sibling tools like oci_kafka_get_oci_cluster_config and oci_kafka_get_cluster_health.

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 explicit when-to-use guidance with example questions ('What is the cluster OCID?') and alternative instructions: if cluster_id is missing, call oci_kafka_list_oci_clusters or ask the user. This effectively distinguishes usage from write operations and other read 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?

Describes that it checks partition leadership distribution, defines skew ratio threshold, and states return values. Since no annotations, description provides adequate behavioral context. Does not mention permissions but read-only nature inferred.

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?

Concise and well-structured. Front-loaded purpose, includes threshold interpretation, then parameter, then returns. No superfluous 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?

Given simple tool with one optional parameter and output schema, description covers all necessary details: what it does, how it interprets results, what it returns. Sufficient for agent decision-making.

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?

Only one parameter fully explained: topic_name is optional, default checks all topics. This adds complete meaning beyond schema which has no 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?

Clearly states tool detects partition imbalance across brokers. Specific verb+resource, and distinguishes from sibling tools like detect_under_replicated_partitions. Provides threshold for interpretation.

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 explicit when-to-use or alternatives mentioned. Implied from purpose but lacks comparison to similar detection tools. Could be improved by noting when to use this versus other health checks.

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 full burden. It states that the tool gets status and details, and that it should be polled, but does not disclose any behavioral traits such as rate limits, authentication requirements, or side effects. The presence of an output schema is not mentioned, but it exists separately. The description is minimally adequate.

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, with three sentences: purpose, usage guidance, and argument description. It is front-loaded with the main action, and every sentence adds value without redundancy.

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

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

The description covers the essential context: purpose, when to use, and the parameter's source. Since an output schema exists (not shown to us), the description does not need to explain return values. However, it could hint at distinguishing from error/log work request tools, but overall it is complete enough for a simple polling 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?

The only parameter, work_request_id, is described as 'Work request OCID returned by the triggering operation', which adds significant context beyond the schema (which has no description). It tells the agent where to obtain the value, making the parameter's purpose and source 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 clearly states the tool's action 'Get the status and details of an asynchronous OCI work request', specifying both the verb and resource. It distinguishes from siblings like list_work_requests, cancel_work_request, get_work_request_errors, and get_work_request_logs by focusing on the overall status and details.

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 explicit guidance on when to use the tool: 'Use this after any async operation (create/update/delete cluster, enable superuser, etc.) to track progress. Poll until status is SUCCEEDED or FAILED.' It does not include when-not-to-use or alternatives, but the context is clear and helpful.

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 states the tool returns error details but does not disclose side effects (e.g., read-only, idempotent) or required permissions. The description is adequate but not comprehensive for behavioral traits.

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 extremely concise: two sentences for purpose and usage, plus one line for the parameter. No unnecessary words or repetition. Front-loaded with the main action.

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 has an output schema, so the description covers the key points: when to use it and what it returns. It could mention that errors are returned as a list, but the output schema likely handles that. Slightly incomplete but 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?

The single parameter work_request_id is described as 'Work request OCID that failed', adding context beyond the schema's generic title. The word 'failed' clarifies it is only for failed work requests, which is valuable.

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 'Get error details' and the resource 'failed OCI work request'. It distinguishes itself from siblings like oci_kafka_get_work_request and oci_kafka_get_work_request_logs by specifying it returns errors, not general status or logs.

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

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

The description explicitly says 'Call this when oci_kafka_get_work_request shows status FAILED', providing a clear condition. It does not explicitly mention when not to use it, but the condition is sufficient and contextually implied.

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 full burden. It describes the output as timestamped log messages but does not disclose behavioral traits such as read-only nature, required permissions, or any side effects. The 'get' verb implies read-only, but this is not explicit.

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 very concise: two short sentences plus an args line. It is front-loaded with the purpose and adds no unnecessary fluff.

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

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

Given the tool's simplicity (one parameter, read operation) and the existence of an output schema, the description adequately covers the purpose and return type. However, it does not mention pagination or ordering, which could be relevant.

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 includes an 'Args' section explaining that work_request_id is the 'Work request OCID to retrieve logs for', adding meaningful context beyond the schema's type and title.

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 'Get' and the resource 'log entries from an OCI work request', differentiating it from sibling tools like get_work_request (returns work request details) and get_work_request_errors (returns errors).

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 mentions it is 'useful for understanding the sequence of steps in a long-running operation', which implies a use case, but does not explicitly state when to use this tool versus alternatives or provide exclusions.

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

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

With no annotations, the description discloses key behavior: fallback to environment variable or config file if compartment_id is omitted, and default scope as tenancy OCID. This adds valuable 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?

Extremely concise: two short paragraphs. First sentence states purpose; second explains the parameter. No superfluous 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?

Adequate for a simple list operation with one optional parameter and an output schema. Lacks mention of pagination, filtering, or return format, but output schema exists to fill that gap.

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

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

Schema coverage is 0%, so the description must compensate. It explains the compartment_id parameter's purpose, default behavior, and fallback, providing meaning beyond the schema's minimal type info.

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 tool lists OCI Kafka cluster configurations in a compartment, using a specific verb and resource, and distinguishes from sibling tools like 'get' and 'create'.

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 explicit guidance on when to use this tool versus alternatives such as get_cluster_config or list_cluster_config_versions. The description focuses on parameter fallback but omits usage context.

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 provided, so description carries full burden. Mentions that configurations are versioned and each update creates a new version. Does not mention pagination, ordering, or limits. Adequate but could elaborate on 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?

Extremely concise: five sentences, no redundant information. Front-loaded with purpose, followed by versioning context, usage guidance, and parameter details. 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?

Covers purpose, usage, and parameter. With an output schema present, return values are defined. Does not mention if results are paginated or sorted, but overall adequate for a list 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?

Single parameter cluster_config_id is described with its OCID format (ocid1.kafkaclusterconfig.*), adding significant value beyond the schema's title. Since schema description coverage is 0%, description fully compensates.

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?

Clearly states the tool lists all versions of a Kafka cluster configuration. Explains that configurations are versioned, distinguishing this from retrieving a single version or listing configurations. Verb 'list' is appropriate, and resource is specific.

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

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

Explicitly describes the use case: to view version history and choose a version to apply or roll back to. Implicitly differentiates from siblings like get_cluster_config_version (for a single version). Lacks explicit exclusions but provides strong context.

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 tool returns a list with count, state, and type, but does not mention read-only nature, potential performance impact, or any rate limits. For a simple list tool, this is adequate but 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 concise: two sentences that directly state the purpose and return contents. No unnecessary words or repetition. 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?

Given the tool's simplicity (zero parameters) and the presence of an output schema, the description adequately covers what the tool does and what it returns. It provides enough context for an AI agent to understand its function and differentiate it from 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?

With zero parameters, schema coverage is 100%, and the description does not need to add parameter information. According to guidelines, 0 parameters yields a baseline of 4. The description mentions the return values, which adds value beyond the input 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 'List' and resource 'all consumer groups in the Kafka cluster', and specifies the returned information (total group count, list with state and type). This distinguishes it from sibling tools like oci_kafka_describe_consumer_group (single group) and oci_kafka_delete_consumer_group (delete operation).

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 does not provide explicit guidance on when to use this tool versus alternatives. Usage is implied by the nature of listing all consumer groups, but no exclusions or references to sibling tools are given. For a tool with many siblings, more explicit context would improve usability.

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 provided, so description bears full burden. It describes return content but does not explicitly state it is read-only or non-destructive, nor address side effects or permissions. Adequate but leaves some behavioral ambiguity.

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?

Concise, well-structured, and front-loaded. Every sentence adds value: purpose, output, usage, and parameter description. 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?

Covers purpose, output summary, usage context, and parameter semantics. Lacks mention of pagination or errors, but for a simple listing tool with output schema, it is nearly complete.

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

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

Schema has 0% description coverage, but the description explains the sole parameter: 'Optional OCI compartment OCID to scope the shape list,' adding meaningful context beyond the schema's title.

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 'List available broker node shapes for OCI Kafka cluster provisioning' and mentions OCPU and memory specs, making it distinct from sibling tools focused on clusters, topics, or consumer groups.

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

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

Explicitly suggests 'Use this before oci_kafka_create_cluster to choose an appropriate broker shape,' providing clear context for when to invoke. Does not discuss alternatives or exclusions, but sufficient for this 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 must fully disclose behavior. It does so by explaining the default compartment logic (env var then config file) and the return structure. While it doesn't explicitly state read-only or mention pagination, the list operation's implications are clear. A score of 4 acknowledges thoroughness with minor room for additional safety notes.

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 at a few lines, uses a bullet list for return fields, and front-loads the core purpose. Every sentence adds information without redundancy.

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

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

For a straightforward list tool with one optional parameter and an output schema, the description is complete. It explains the action, the parameter semantics, the output fields, and typical usage context.

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

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

The single parameter (compartment_id) has 0% schema description coverage, but the description thoroughly explains its meaning, default resolution from environment variables and config file, and optional nature. This adds significant value beyond the schema type definition.

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 tool lists all Kafka clusters in an OCI compartment and enumerates the returned fields. It distinguishes itself from sibling tools like get, delete, or create by positioning itself as a discovery tool, e.g., 'before calling oci_kafka_get_oci_cluster_info.'

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 explains when to use the tool: to discover clusters, check lifecycle states, or find OCIDs. It also provides an alternative call (oci_kafka_get_oci_cluster_info) and explains the default compartment resolution order, fulfilling both when-to-use and how-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?

No annotations are provided, so the description carries the full burden. It states the output but does not explicitly mention that the operation is read-only, has no side effects, or require specific permissions. It is adequate but lacks explicit safety traits.

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 only two sentences with no wasted words. It front-loads the purpose and clearly states the return value structure.

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

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

Given no parameters and the presence of an output schema, the description adequately explains the tool's functionality. It could mention prerequisites like needing a cluster context, but for a simple list operation it is sufficiently 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 input schema has zero parameters, so there is no parameter information needed. Baseline for 0 parameters is 4, and the description adds no param info, which is acceptable.

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 tool lists all topics in the Kafka cluster and specifies the return values (total topic count, list with partition counts). It distinguishes from sibling tool 'oci_kafka_describe_topic' which targets a single topic.

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 says 'Use this to get an overview of all topics in the cluster,' which implies the intended usage. However, it does not mention when not to use it or compare with alternatives like 'oci_kafka_describe_topic' for specific topics.

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?

Discloses the default tenancy OCID behavior but lacks details on pagination, rate limits, or read-only nature; no annotations to compensate.

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?

Concise, well-structured with clear sections; 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?

Adequate for a list tool with output schema; could mention pagination but not essential given schema.

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?

Adds meaningful descriptions beyond schema for both parameters (e.g., example for resource_id), though schema coverage is 0%.

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 tool lists OCI work requests with optional filters, and distinguishes from siblings like get_work_request by focusing on listing.

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 explicit guidance on using resource_id for cluster operations and explains default behavior when no filters are given, but does not contrast with sibling listing 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?

No annotations provided, so description carries full burden. It clearly describes the tool as non-destructive data collection and specifies output structure (diagnostic report sections). No contradictions.

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?

Description is concise and well-structured: a single sentence summary, bulleted data collection points, and a detailed list of report contents. Every sentence adds value; 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?

Given zero parameters and existence of output schema, the description fully explains the tool's purpose, inputs (implicit cluster context), outputs, and how the agent should use the results. Covers all necessary context.

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

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

Input schema has zero parameters, so no parameter descriptions are needed. Schema coverage is 100% vacuously. Description explains tool behavior without parameter details, meeting the baseline of 4 for zero-parameter tools.

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 'Analyze the cluster and recommend scaling actions' and lists specific data collected. It clearly distinguishes from sibling tools like oci_kafka_scale_cluster (which performs scaling) by emphasizing it gathers data only.

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

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

Explicitly states 'This tool gathers data only — the LLM agent should interpret the findings and present human-readable recommendations to the user.' This provides clear guidance on when to use the tool (analysis) and when not to present raw output, and implies alternative tools (scale cluster).

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?

Without annotations, the description carries full burden. It labels the operation as 'DESTRUCTIVE' and 'HIGH RISK', explains the empty consumer group requirement, and notes the need for confirmation. This provides strong transparency, though it could elaborate on the exact impact on consumer offsets.

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 reasonably concise, front-loading the purpose and warning, then prerequisites, then parameter descriptions. It is efficient without being overly terse.

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 complexity (destructive, prerequisites, multiple parameters), the description covers prerequisites, parameter meanings, and return summary. The presence of an output schema means return values need not be detailed further. It is sufficiently 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 fully compensates by explaining each parameter: group_id, topic_name, strategy (with examples of options), and partition (optional, default behavior). This adds significant value 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?

Description clearly states 'Reset consumer group offsets for a topic', specifying a precise verb and resource. It is distinct from all sibling tools, none of which perform a reset operation.

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?

Description provides explicit prerequisites (empty consumer group, allow-writes enabled) and risk level. It does not explicitly mention when not to use the tool, but given no alternative reset tool exists, the guidelines are 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 provided, so description carries full burden. It discloses the operation is high risk, requires confirmation, and is asynchronous. It also references --allow-writes, implying authorization needs. Good coverage of behavioral traits.

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 with a succinct main sentence followed by bulleted details. Every sentence adds value without redundancy.

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

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

Given the presence of an output schema and the description's coverage of asynchronous tracking, it is fairly complete. Minor gap: no constraints on broker_count (e.g., min/max) are mentioned, but overall 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?

Schema coverage is 0%, but description adds clear semantics: cluster_id is an OCID, broker_count is target number of broker nodes. This adds meaning beyond the schema's titles.

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 tool scales an OCI Kafka cluster to a different broker count, with a specific verb ('scale') and resource ('OCI Kafka cluster'). It distinguishes from siblings like 'oci_kafka_recommend_scaling' by focusing on execution rather than recommendation.

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 mentions the requirement for --allow-writes and the high risk nature, indicating when to use cautiously. It also guides the user to track progress via oci_kafka_get_work_request. However, it does not explicitly list alternatives or when not to 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?

No annotations are provided, so the description carries full burden. It discloses the async nature and write permission requirement, but lacks details on how updates affect existing fields (e.g., whether freeform_tags merge or replace), and does not mention prerequisites or states.

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 with a brief overview followed by a parameter list. It avoids unnecessary detail while covering essential aspects, though the structure could be more formalized (e.g., bullet-pointing the list).

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 purpose, parameters, and async behavior. However, it omits potential error conditions, prerequisites (e.g., cluster must exist), and does not elaborate on how updates interact with existing configurations. Since an output schema exists, return value details are not needed.

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 has 0% description coverage, but the description adds explanations for each parameter, including the OCID pattern for cluster_id and the roles of cluster_config_id/version. However, it does not clarify the update behavior for freeform_tags (merge vs replace).

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 tool updates an OCI Kafka cluster's display name, tags, or applied configuration. It uses a specific verb and resource, differentiating from create, delete, and scale operations among siblings.

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

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

The description mentions that writes require '--allow-writes' and that the operation is asynchronous, directing to use 'oci_kafka_get_work_request' to track progress. However, it does not explicitly state when not to use this tool compared to alternatives like 'oci_kafka_update_cluster_config'.

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?

Discloses asynchronous operation and recommends tracking via oci_kafka_get_work_request. States no new version is created. Without annotations, this provides key behavioral details, though permissions and error handling are not 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?

Compact and front-loaded: each sentence adds unique value. No redundant or vague 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?

Covers all essential aspects for an update tool: what it updates, async behavior, version impact, and parameter meanings. Output schema exists, so return values are not needed.

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?

All three parameters are explained in the Args block, providing meaningful descriptions beyond the bare schema types. Schema coverage is 0%, so the description fully compensates.

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 it updates an OCI Kafka cluster configuration's name or tags, using a specific verb and resource. It distinguishes from sibling tools like create, delete, list, etc.

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?

Mentions requirement for --allow-writes and notes that updating metadata does not create a new version. However, it does not explicitly contrast with alternatives like create or update cluster, leaving some implicit context.

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 writes are required and states the return value, but does not cover edge cases, validation errors, or idempotency. Basic behavior is transparent but incomplete.

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, using a clear sentence plus an Args block. It avoids redundancy and is well-structured for an AI agent to parse. Minor improvement possible by removing the word 'configuration' in the first sentence, but overall 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?

Given the tool's complexity (2 parameters, output schema exists), the description covers what it does, the required flag, parameter details with examples, and return values. No critical information is missing, and it remains 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 explain parameters. It defines topic_name and configs with an example dictionary, adding semantic meaning beyond the schema's type-only definition. This adequately compensates for the lack of 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 clearly states 'Update configuration settings for a Kafka topic,' specifying verb and resource. It is distinct from sibling tools like oci_kafka_create_topic or oci_kafka_update_cluster_config, which handle different operations.

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 mentions a prerequisite ('Requires --allow-writes to be enabled') but does not provide explicit guidance on when to use this tool versus other topic tools (e.g., create or describe). The guidance is implied but not thorough.

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