get_policies

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

Annotations already mark the tool as read-only (readOnlyHint true). The description adds valuable behavioral context: it lists the specific fields returned (tag, policy ID, rule count) and provides a detailed reference of 10 masking levels with their meanings. This explains the output beyond what the schema may indicate. No contradictions with 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 well-structured: it starts with the main purpose, then lists return fields, provides usage guidance, and includes a helpful reference. It is moderately long but every sentence adds value. However, the masking levels list could potentially be shortened or linked to documentation, but it is comprehensive and justifies 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 (list with one optional parameter, output schema exists), the description covers the essential aspects: purpose, return fields, parameter use, and downstream usage. It does not address error handling or performance characteristics, but for a read-only list tool this is acceptable. The description is complete enough for effective use.

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

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

Schema coverage is 100% (the single optional parameter 'policy_type' is fully described in the schema). The description does not add additional semantic value for the parameter beyond what is in the schema. The masking levels reference is about return values, not parameter semantics. According to the rubric, with high coverage baseline is 3, and the description does not exceed that.

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 masking policies configured in your ALTR organization', specifying the verb (List), resource (masking policies), and scope (in your ALTR organization). It also identifies the returned fields (tag, policy ID, rule count) and explains how to use the output with related tools (add_rules, get_rules, delete_policy), providing clear differentiation from siblings like get_rules and create_policy.

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

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

The description gives a clear usage context: use when you need to list masking policies. It also provides guidance on using the results with other tools. However, it does not explicitly mention when not to use this tool or suggest alternatives (e.g., get_tags or get_databases) for other listing needs. The sibling list is large, so a brief exclusion would improve clarity.

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