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

With no annotations provided, the description must carry the burden, and it largely does: it frames the tool as a read-only grammar lookup, discloses that data is live from the deployed backend, and describes the returned content. It does not explicitly state 'no side effects' or error behavior for unknown rule types, but the query-style semantics make this a minor gap.

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

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

Two dense sentences front-load the core value and then give precise call patterns. The workflow prose mentioning fetch_doc is a little verbose but earns its place by connecting to the broader authoring workflow.

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

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

For a single optional-parameter reference tool with no output schema, the description is complete: it states what the tool is, what it returns, the exact call patterns, and the surrounding workflow. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

The schema already describes rule_type well with 100% coverage, so the baseline is 3. The description adds value by explaining the two invocation modes—no argument vs. passing rule_type—and giving concrete examples like content_match, going beyond the schema's bare description.

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

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

The description clearly identifies the tool as the authoritative grammar of Alter's policy language, listing the exact content it exposes (rule types, JSON body schema, caps, authorable levels, examples, fail-closed semantics). It distinguishes itself from documentation-style siblings by emphasizing that it is live from the deployed backend, so an agent can tell it apart from fetch_doc.

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

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

It gives explicit invocation guidance: call with no arguments for the overview, pass rule_type for a specific grammar. It also states when to use it—before authoring rules with alter policy rules create—and even references the relevant fetch_doc workflow.

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