reading_closure

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

With no annotations, the description carries the full burden of behavioral disclosure. It does explain the traversal behavior ('walks outward, nearest first') and the meaning of depth ('How many hops to follow') and warns about the transitive closure ('The transitive closure of the Code is the Code'), which hints at potential depth explosion. However, it does not mention the return format (citations vs. full text), pagination, or any edge cases like cycles. It is transparent about the core algorithm but lacks details on output and side effects.

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 efficient: it states the purpose first, then the graph context, then the traversal behavior, and then the arguments. Every sentence adds value. It is front-loaded with the primary action and uses minimal words to convey the key concepts. No filler or redundancy.

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 is moderately complex (graph traversal), but the description covers the purpose, parameters, and traversal order. An output schema exists (as signaled), so the return format may be documented there. The description does not mention edge cases like cycles or what happens if the citation is invalid, but for a tool with a clear use case and an output schema, the coverage is adequate. It is missing a note on what the output looks like, but the output schema likely covers that.

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 has zero parameter descriptions (coverage 0%), so the description must fully explain each parameter. It does so clearly: citation (starting provision, with an example), depth (hops), and limit (max provisions). It also explains the relationship between depth and the graph. This fully compensates for the schema gap.

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 opens with a clear, specific verb and resource: 'List everything you must read to understand a provision.' It explains the graph metaphor and the outward traversal, and the example (§ 163(j)) makes the purpose concrete. This is distinct from siblings like get_cross_references, which likely returns direct references, while this tool computes the transitive closure. The purpose is unambiguous.

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 provides a clear context for use: 'Before asserting what § 163(j)(1) means, read what it points at.' This implies the tool is for gathering reading material before making assertions. However, it does not explicitly contrast with alternatives like get_cross_references or get_irc_provision, nor does it state when NOT to use it. The usage guidance is implied rather than explicit.

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