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

Beyond readOnlyHint/openWorldHint, the description discloses that the response includes structural context (parent and children) and that the call is audited/recorded with the key rather than a question. Audit logging and result shape are behaviour the annotations cannot convey, though nothing is said about language fallback or as-of resolution.

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 short sentences, front-loaded with the core action and scoping. The phrase 'where it sits and what sits beneath it' is slightly literary but earns its place by describing the hierarchy in the result.

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?

An output schema exists so return values needn't be spelled out, and annotations carry the safety profile; the description usefully adds the audit-recording note and the article-vs-fragment distinction. Only minor gaps remain around language fallback and as-of semantics.

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% and each parameter (key, lang, as_of, whole_subtree) is already documented in the schema. The description gestures at 'whole of an article', which maps to whole_subtree, but adds no format or fallback detail beyond the schema's own text, so the baseline 3 applies.

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 a specific verb and resource ('Read one clause by its key') and hints at the returned shape ('where it sits and what sits beneath it'). It never names the sibling tools (get_document, search_policies), so differentiation is inferred rather than 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?

Gives concrete triggers: when a search result points at another clause, or when you need the whole of an article rather than the matched part. That is clear context but there are no explicit exclusions or named alternatives, so the agent must infer that search_policies is for discovery.

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