Server Quality Checklist

Tool Scores

• list_objectsA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full behavioral disclosure burden. It states the core action but omits details about pagination, return format (whether it returns object names, metadata, or contents), or any API-specific behavior. This is a significant gap for a tool with no output schema.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that conveys the essential function without redundancy.

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

  Completeness3/5

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

  Given the simple list operation, the description is adequate but incomplete: it doesn't describe what data is returned (e.g., object names, sizes, ETags) or whether pagination is handled. The lack of an output schema and annotations makes the description the sole source of return-value information, which is insufficient.

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

  Parameters3/5

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

  All 5 parameters have descriptions in the schema, giving high coverage. The description's mention of 'prefix filter' reinforces the prefix parameter but adds no extra semantics beyond the schema's existing documentation.

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

  Purpose5/5

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

  The description 'Lists objects in a bucket, optionally filtered by prefix' uses a specific verb ('lists') and clear resource ('objects in a bucket'), distinguishing it from sibling tools like list_buckets which lists buckets. It clearly describes the core function.

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

  Usage Guidelines3/5

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

  The description implies usage for listing objects but provides no explicit guidance on when to choose this over alternatives such as list_buckets or get_bucket. No exclusions or alternative recommendations are given.

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

• create_bucketA
  3.6/5.0
  Behavior3/5

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

  Without annotations, the description carries the burden. It adds the important behavioral constraint 'Blocked when OCI_READ_ONLY=true', which indicates it is a write operation and cannot run in read-only mode. However, it omits other traits like idempotency, permission requirements, or return behavior.

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

  Conciseness5/5

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

  The description is two sentences with no wasted words. The first sentence states the purpose, the second provides a key constraint, and both are front-loaded and relevant.

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

  Completeness2/5

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

  With no output schema and only a terse description, the agent is left without information on return values, error behavior (e.g., bucket already exists), or idempotency. The read-only block is useful, but the description is incomplete for a mutation tool of this complexity.

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

  Parameters3/5

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

  Schema description coverage is 100% with all parameters described. The description adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description states 'Creates an Object Storage bucket' with a specific verb and resource, clearly distinguishing it from sibling tools that list, get, delete, or perform actions. It precisely identifies what the tool does.

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

  Usage Guidelines3/5

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

  The description implies use for creating a bucket but does not explicitly mention when to use it vs alternatives like list_buckets or get_bucket. The read-only block condition is helpful but not a usage guideline.

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

• get_bucketA
  3.7/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses the default trimmed summary and the raw=true option, and the verb 'Returns' implies a read-only operation. However, it does not mention potential error behavior, required permissions, or what fields the summary contains.

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

  Conciseness5/5

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

  The description is two short sentences, front-loads the main behavior, and has no filler or redundant information. Every word earns its place.

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

  Completeness3/5

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

  Given the absence of an output schema, the description lacks details about the return structure or what the trimmed summary includes. The raw=true escape hatch mitigates this somewhat, but for an AI agent to invoke the tool correctly, knowing what to expect in the summary would be beneficial. It is adequate but not rich.

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

  Parameters3/5

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

  The input schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds minimal extra meaning beyond the raw toggle, which is already described in the schema (raw parameter description). It does not add details on region/namespace formatting or usage.

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

  Purpose5/5

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

  The description clearly states the tool returns details of a specific Object Storage bucket, using a specific verb ('Returns') and resource ('specific Object Storage bucket'). It distinguishes itself from sibling list operations like list_buckets by emphasizing 'specific', and mentions the raw/summary toggle, adding precision.

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

  Usage Guidelines3/5

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

  There is no explicit guidance on when to use this tool versus alternatives like list_buckets or get_namespace. The phrase 'specific bucket' implies single-resource lookup, but no exclusions or alternative references are provided. The usage context is only implied.

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

• list_bucketsA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the key behavior of returning a trimmed summary unless raw=true, which is useful. However, it omits other behavioral details such as whether this is a read-only operation (implicit but not stated), whether pagination is involved, what the trimmed summary contains, or any access/authorization requirements. This is a minimum-viable disclosure with clear gaps.

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

  Conciseness5/5

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

  The description is exceptionally concise and front-loaded. The first sentence immediately states the core purpose, and the second sentence adds a critical nuance about output formatting. There is no redundancy or boilerplate, making it efficient for an agent to parse.

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

  Completeness3/5

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

  The tool has 4 optional parameters and no output schema, so the description should provide more context about parameter interactions and the expected return structure. It mentions a 'trimmed summary' but does not specify what it contains, nor does it clarify that listing is limited to a single compartment (with tenancy root as default, per the schema). The description is adequate but leaves the agent without important contextual details for invoking the tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 100% since every parameter has a detailed description. The tool description adds marginal value by mentioning the raw=true behavior, but that is already captured in the schema. The baseline of 3 applies because the schema does the heavy lifting and the description does not significantly enrich parameter understanding beyond what is already in the input schema.

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

  Purpose5/5

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

  The description clearly states the verb (Lists), the resource (Object Storage buckets), and the scope (in a compartment). It is specific enough to distinguish from sibling tools like list_compartments or list_instances, and the additional note about returning a trimmed summary adds useful detail.

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

  Usage Guidelines3/5

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

  The description implies this tool is used for listing buckets, but it does not explicitly mention when to use it versus alternatives such as get_bucket (for a single bucket) or list_objects (for objects within a bucket). No when-not-to-use or alternative tool references are provided, leaving the agent to infer usage from the verb and resource.

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

• delete_objectA
  3.8/5.0
  Behavior3/5

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

  The description discloses a key behavioral trait: the tool is blocked when OCI_READ_ONLY=true, which goes beyond the obvious 'deletes'. However, it does not mention other important aspects like irreversibility, permissions, or failure behavior, and no annotations are present to fill this gap.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core action, and the second sentence adds a useful caveat. There is no redundancy or unnecessary detail.

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

  Completeness4/5

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

  For a simple delete tool with no output schema and straightforward parameters, the description provides the essential action and a key constraint. It is reasonably complete, though it could mention that deletion is permanent.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema already documents all parameters. The description does not add any new parameter-related semantics, only restating the existence of bucket and object, so the baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the action ('Deletes') and the target ('an object from a bucket'), making it unambiguous. It also differs from all sibling tools, none of which perform deletion.

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

  Usage Guidelines3/5

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

  The description implies usage through its clear action, but it provides no explicit guidance on when to choose this tool over alternatives. The only additional context is the read-only block, which is a constraint rather than usage guidance.

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

• get_namespaceA
  3.8/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of disclosing behavior. It clearly states the tool returns the namespace, implying a read-only operation. However, it does not disclose authentication requirements, error behavior for invalid regions, or the exact return format.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no wasted words. It directly states the action and the object without superfluous detail.

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

  Completeness4/5

  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 optional parameter, no output schema, no nested objects), the description is sufficient. It explains what is returned and for whom. The absence of an output schema is not a major gap because the return value is a simple namespace string, and the schema already explains the region parameter.

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

  Parameters3/5

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

  Schema description coverage is 100% for the single 'region' parameter, which is already fully described in the input schema. The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb 'Returns' and identifies the exact resource ('Object Storage namespace') and scope ('for the tenancy'). It clearly distinguishes from sibling tools like list_buckets or get_instance, which serve different purposes.

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

  Usage Guidelines3/5

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

  The description implies usage when the Object Storage namespace is needed, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. There is no mention of alternatives in the description itself.

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

• list_network_security_groupsA
  3.8/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of explaining behavior. It discloses the output format ('trimmed summary per NSG unless raw=true') and mentions optional filtering, but does not address permissions, pagination, or error behavior. The read-only nature is implied but not stated.

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

  Conciseness5/5

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

  Two clear sentences, front-loaded with the main action and followed by a reference to the raw option. No wasted words, perfectly sized.

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

  Completeness4/5

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

  For a list tool, the description and rich parameter schema provide enough context to invoke it: scope, optional filter, region, and output mode. There is no output schema, so the raw/trimmed distinction is valuable. Minor gaps include pagination details, but they are less critical for this resource.

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

  Parameters3/5

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

  Schema descriptions cover all 4 parameters (compartmentId, vcnId, region, raw) with defaults and meaning. The tool description adds a little context about the trimmed vs raw output, but mostly relies on the schema. Baseline of 3 is appropriate given 100% schema coverage.

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

  Purpose5/5

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

  The description clearly states the tool lists network security groups (NSGs) in a compartment, optionally filtered by VCN. It specifies the resource (NSGs) and the scoping dimensions, distinguishing it from sibling tools like list_security_lists.

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

  Usage Guidelines3/5

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

  The description gives clear context (compartment, optional VCN filter) but does not explicitly mention when to use this versus sibling tools like list_security_lists. The usage is implied by the resource name, but no exclusions or alternatives are provided.

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

• instance_actionA
  3.9/5.0
  Behavior3/5

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

  With no annotations provided, the description must carry the burden of disclosing behavioral traits. It does state that the tool is blocked when OCI_READ_ONLY=true, signaling that it is a write operation and that read-only mode prevents execution. However, it does not mention other important behaviors such as whether actions are asynchronous, what response to expect (no output schema), potential state preconditions (e.g., instance must be stopped before starting), or reversibility of actions.

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

  Conciseness5/5

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

  The description is extremely concise: two sentences, front-loaded with the primary purpose and then a critical constraint. Every word earns its place, with no filler or repetition of schema details. Excellent structure.

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

  Completeness3/5

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

  For a mutating tool with no annotations and no output schema, the description provides essential purpose and one key constraint, but omits other contextual information that would help an agent, such as whether operations take effect immediately, how to verify success (e.g., using get_instance), or error conditions. It is adequate but not rich enough for a lifecycle-management tool.

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

  Parameters3/5

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

  The input schema already provides 100% coverage for all three parameters (action, region, instanceId), including an enum-like list for action and a default for region. The description's mention of 'lifecycle action' adds minimal extra meaning beyond the schema, but it does reinforce the purpose of the action parameter. Since the schema carries the heavy lifting, a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb ('Performs'), a precise resource ('Compute instance'), and an enumerated list of lifecycle actions (START, STOP, etc.). This unambiguously distinguishes it from sibling tools that are primarily read-only list/get operations.

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

  Usage Guidelines4/5

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

  The description makes the intended use case obvious: performing lifecycle actions on Compute instances. It does not explicitly compare against alternatives, but the sibling context shows a clear separation from read-only/list tools, so an agent can infer when to select this tool. The OCI_READ_ONLY constraint adds a clear condition under which the tool should not be used.

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

• list_subnetsA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It does add valuable context that the default return is a trimmed summary and that raw=true returns full OCI SDK objects. However, it does not mention other behavioral aspects such as pagination, permissions, or error handling, leaving some ambiguity.

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

  Conciseness5/5

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

  The description is brief and to the point. Two sentences convey the action, optional filter, and output behavior without unnecessary filler.

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

  Completeness3/5

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

  Given the absence of an output schema, the description should clarify what a 'trimmed summary' contains. It also does not mention pagination or limits, leaving some uncertainty about the return format. While the tool is relatively simple, the vague 'trimmed summary' term is a notable gap.

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

  Parameters3/5

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

  The input schema already provides 100% parameter descriptions, so the baseline is met. The tool description adds no extra meaning beyond the schema; it only references raw and VCN filtering, which are already in the schema.

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

  Purpose5/5

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

  The description clearly states the verb ('Lists'), resource ('subnets'), and scope ('in a compartment, optionally filtered by VCN'). It also distinguishes itself from sibling tools like list_vcns or list_instances by specifying exactly what is listed and that the output is a trimmed summary by default.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use the tool (to list subnets) and how to narrow the scope (by compartment or VCN). It does not explicitly mention when not to use it or alternative tools, but the purpose is specific enough that this is not a major gap.

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

• get_instanceA
  4/5.0
  Behavior4/5

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

  Despite no annotations, the description discloses a key behavioral trait: returns a trimmed summary by default unless raw=true, which changes the output to the full OCI SDK object. This adds value beyond the schema and conveys output behavior.

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

  Conciseness5/5

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

  Two short sentences with no filler. The core purpose and the raw flag behavior are front-loaded and immediately actionable.

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

  Completeness4/5

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

  For a simple get-instance tool, the description plus schema covers the essential information: what the tool does, how to adjust output (raw), and all parameters. It does not detail the exact fields in the trimmed summary, but this is not critical for a read operation.

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

  Parameters3/5

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

  Schema description coverage is 100%, with each parameter already explained. The description only mentions raw=true's effect but does not add significant meaning beyond the schema, so baseline 3 applies.

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

  Purpose5/5

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

  Clearly states 'Returns details of a specific Compute instance', identifying the resource and scope. It distinguishes itself from sibling list_instances by emphasizing a single instance rather than a list.

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

  Usage Guidelines3/5

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

  Usage is implied: use when you need details of one specific instance. It does not explicitly mention alternatives (e.g., list_instances) or state when not to use, leaving the agent to infer from the 'specific' wording.

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

• list_compartmentsA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses the default behavior (searching the entire tenancy tree from the root) and the filtering options, which is useful. However, it does not describe the return format (e.g., list of compartments with OCIDs), pagination, or error behavior, leaving some gaps.

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

  Conciseness5/5

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

  The description is two sentences long, immediately states the primary action, and provides a concrete example. Every sentence serves a purpose with no redundant filler, making it highly efficient and well-structured.

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

  Completeness4/5

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

  For a simple list tool with no output schema and no annotations, the description covers the essential behavior: filtering rationale, default scope, and intended use case. It falls slightly short by not stating the return structure explicitly, but the inference that OCIDs are returned is strong given the stated purpose.

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

  Parameters3/5

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

  Schema description coverage is 100%, with each parameter already clearly described (exact name match, parent compartment, includeSubtree default true). The description adds context about the tenancy-wide default but does not significantly enhance parameter understanding beyond the schema, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool lists compartments by name and/or parent compartment, with a specific verb ('Lists') and resource ('compartments'). It also distinguishes its purpose by noting it resolves compartment names to OCIDs before calling other tools, setting it apart from sibling tools like list_instances or list_vcns.

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

  Usage Guidelines4/5

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

  The description explicitly says to use this tool to resolve a compartment name to its OCID before calling other tools, providing clear context. It does not explicitly name alternatives or when not to use it, but the guidance is strong enough for an agent to select it appropriately.

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

• list_instancesA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden and discloses key behavior: default returns a trimmed summary, and raw=true returns full OCI SDK objects. This adds meaningful context beyond the schema, though it omits other details like pagination or permissions.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary purpose, and every word earns its place. No fluff or redundant information.

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

  Completeness4/5

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

  For a list tool with four optional parameters and no output schema, the description sufficiently explains the operation and return format (trimmed vs raw). It is slightly vague about exactly what the trimmed summary contains, but overall complete enough for typical use.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description only references the 'raw' parameter and does not add new meaning to other parameters beyond what the schema already provides.

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

  Purpose5/5

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

  The description clearly states the tool lists Compute instances in a compartment, specifying both the resource type and scope. It distinguishes itself from sibling tools like get_instance (single instance) and instance_action (actions) by the verb 'Lists' and resource focus.

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

  Usage Guidelines3/5

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

  The description implies usage as a list operation but does not explicitly state when to use it over alternatives like get_instance or list_vcns. No exclusions or alternative tool references are provided, leaving the context partially implied.

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

• list_route_tablesA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the default returns a trimmed summary with route rule count, and that raw=true returns the full SDK object. This is valuable behavioral information beyond the schema, though it does not cover potential errors or permissions.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary action and resource, and efficiently conveys the default vs. raw behavior. Every sentence adds value without redundancy.

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

  Completeness4/5

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

  For a tool with four optional parameters and no output schema, the description sufficiently explains the return behavior (trimmed summary vs. raw object). The schema covers parameter defaults and filters, and the description adds the key behavioral nuance. It is complete enough for an agent to select and invoke correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds a minor semantic hint by explaining the purpose of raw=true ('inspect the actual routes'), but does not add new parameter meaning beyond what the schema already states.

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

  Purpose5/5

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

  The description starts with 'Lists route tables in a compartment, optionally filtered by VCN' – a specific verb and resource with clear scope. The resource 'route tables' is unique among siblings, so there is no ambiguity about what is being listed.

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

  Usage Guidelines3/5

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

  The description implies usage for listing route tables in a compartment, and notes the optional VCN filter. However, it does not explicitly mention when-not-to-use or name alternative tools, though the resource clearly distinguishes it from siblings.

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

• list_security_listsA
  4/5.0
  Behavior4/5

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

  With no annotations present, the description carries full responsibility for behavioral disclosure. It transparently explains the default trimmed summary return format, including ingress/egress rule counts, and that raw=true returns the full OCI SDK object with actual rules. This goes beyond a simple listing statement and meaningfully informs the agent of output behavior.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that leads with the primary action, then efficiently explains the key behavioral nuance (trimmed summary vs raw). There is no wasted wording or redundancy with the schema, achieving maximum conciseness.

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

  Completeness4/5

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

  The tool has no required parameters and no output schema, so the description appropriately covers the essential return behavior (trimmed summary vs raw) and the optional filters. It could further detail the exact structure of the trimmed summary beyond rule counts, but the schema covers parameter semantics and the description sufficiently explains expected outcomes for a list operation.

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

  Parameters3/5

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

  The input schema provides full coverage (100%) for all four parameters with clear descriptions, so the parameter semantics are already well-documented. The description adds marginal value by highlighting raw=true and VCN usage, but those are restatements of the schema. It does not introduce new meaning for any parameter, keeping this at the baseline.

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

  Purpose5/5

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

  The description clearly specifies the verb (lists), the resource (security lists), and the scope (in a compartment, optionally filtered by VCN). It also distinguishes this tool from siblings like list_network_security_groups and list_subnets by naming the exact resource type, leaving no ambiguity about its purpose.

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

  Usage Guidelines3/5

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

  The description gives clear context for when to use the tool (listing security lists in a compartment) and mentions an optional VCN filter. However, it does not explicitly advise against using this tool for other network resource types or point to alternatives such as list_network_security_groups, so the usage guidance is implied rather than fully explicit.

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

• list_vcnsA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full behavioral burden. It discloses the trimmed summary vs. raw output toggle and compartment scoping, but does not address pagination, exact fields in the summary, error behavior, or permission requirements. These gaps make it adequate but not rich.

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

  Conciseness5/5

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

  A single, well-structured sentence that front-loads the main action and immediately explains the key behavior (trimmed summary vs. raw). No redundant words or filler.

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

  Completeness4/5

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

  The tool is a straightforward list operation with three optional parameters and no output schema. The description sufficiently explains the purpose and raw behavior, and the schema documents all parameters. It could mention default region behavior, but the schema covers that, so no major gaps.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description mentions compartment and raw=true, but these are already fully described in the schema. It adds no new parameter syntax or format details beyond what the schema provides.

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

  Purpose5/5

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

  The description uses a specific verb (Lists), specifies the resource (Virtual Cloud Networks), and scopes it to a compartment, clearly distinguishing it from sibling tools like get_vcn. It also highlights the raw=true output behavior, adding clarity about what the tool returns.

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

  Usage Guidelines4/5

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

  The description provides clear context: this is for listing VCNs in a compartment. It implicitly differentiates from get_vcn (which fetches a single VCN) but does not explicitly name alternatives or state when not to use this tool. Thus it has clear context but lacks explicit exclusions.

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

• list_vnic_attachmentsA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains the default return behavior ('trimmed summary') and how to opt into the full object ('unless raw=true'). This is a meaningful behavioral trait, though it does not cover other aspects like pagination or permissions.

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

  Conciseness5/5

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

  Two concise sentences that front-load the purpose and then add the key behavioral note about raw mode. Every word earns its place; no redundant information or padding.

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

  Completeness4/5

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

  The tool has no output schema, so the description's mention of the return format ('trimmed summary' vs 'raw') is valuable. It covers the essential context for a list operation, though it does not address when to use it relative to sibling tools, which is a slight gap given the abundance of list tools.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description's mention of 'compartment' and 'instance' filter echoes the schema but does not add new semantic detail beyond what the parameter descriptions already provide.

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

  Purpose5/5

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

  The description clearly states the action ('Lists') and the resource ('VNIC attachments'), scoped to a compartment with an optional instance filter. This is specific enough to distinguish it from sibling tools like list_instances or list_vcns, as VNIC attachments are a distinct resource type.

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

  Usage Guidelines3/5

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

  The description provides context (compartment scope, optional instance filter) but does not explicitly state when to use this tool over alternatives or mention exclusions. While it's clear what the tool does, it lacks explicit guidance on when it should be preferred over related list tools.

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

• get_vcnA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description must disclose behavioral traits itself. It does so by explaining the trimmed summary default and the raw=true override, which is meaningful behavioral context. However, it does not mention potential errors or permission requirements, though these are less critical for a read-only getter.

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

  Conciseness5/5

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

  Two short sentences, front-loaded with the primary purpose and followed by the key behavioral detail. Every word earns its place with no waste.

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

  Completeness4/5

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

  The tool is simple, parameters are fully documented in the schema, and the description explains the output format. Without an output schema, it could specify in more detail what the trimmed summary contains, but for a getter this is sufficient.

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

  Parameters3/5

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

  Schema description coverage is 100% for all 3 parameters, so the schema already fully documents them. The description's mention of raw=true is redundant with the schema's parameter description, providing no additional semantic value.

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

  Purpose5/5

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

  The description clearly states the tool returns details of a specific VCN, using a specific verb and resource. It distinguishes itself from sibling list_vcns by emphasizing 'specific' VCN, and from other getters like get_instance by naming the VCN resource.

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

  Usage Guidelines4/5

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

  The description implies usage when you need a single VCN's details rather than a list, which contrasts with list_vcns. It provides clear context but does not explicitly exclude alternative tools 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.

• list_regionsA
  4.7/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses what fields are returned and provides a concrete example of the name-to-ID mapping. It implies a read-only listing operation. While it doesn't mention pagination or error behavior, for a simple list tool this is sufficient context. It adds useful behavioral detail beyond a bare 'Lists regions.'

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

  Conciseness5/5

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

  The description is two sentences, with the primary purpose front-loaded and the usage guidance in the second sentence. There is no redundant or unclear language; every clause adds value.

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

  Completeness5/5

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

  The tool is simple with one optional parameter and no output schema. The description covers purpose, output fields, example conversion, and usage context, making it fully self-contained for an agent to select and invoke the tool correctly.

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

  Parameters4/5

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

  The schema has 100% coverage for the single optional parameter 'tenancyId', describing it as 'Tenancy OCID'. The description adds extra meaning by explaining the default resolution ('default: resolved from the auth provider, same rule as compartmentId'), which is not evident from the schema alone. This enhances the parameter's semantics.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Lists the OCI regions this tenancy is subscribed to (region ID, region key, home region flag).' It uses a specific verb ('Lists') and resource ('OCI regions'), and distinguishes itself from sibling tools that deal with instances, compartments, and networks.

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

  Usage Guidelines5/5

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

  The description explicitly explains when to use this tool: 'Use this to resolve a region name... before passing it as the region argument to other tools.' This gives clear context for selection and indicates the tool is a prerequisite for other region-aware operations.

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