list_security_lists

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.

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.

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.

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.

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.

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.