papajohns_directory

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

With no annotations provided, the description takes on the full burden and does so well: it discloses that only one level is returned, lists what each child contains (name, path, URL, store count, store leaf flag), and explains how descent works. It does not discuss error handling or rate limits, but for a read-only directory browse these are not critical gaps.

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 logically ordered: purpose, return shape, navigation, and sibling differentiation. It repeats 'Papa John's store directory' twice in quick succession, but each sentence otherwise contributes valuable information without excessive padding.

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 no output schema, the description compensates by enumerating the child fields and the hierarchy levels, and it covers the single optional input. It also names the associated store and nearby tools, giving an agent everything needed to decide whether this is the right tool and how to invoke it.

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 fully documents 'path' ('Directory path from a previous response's children[].path; omit for the root country index'), and the description reinforces this by explaining root omission and the descent through state, city, and store levels. This adds useful navigational context beyond the schema's straightforward wording.

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 explicitly states 'Browse the Papa John's store directory' and clarifies that it returns one level of the directory hierarchy. It also differentiates itself from coordinate search by directing to GET /papajohns/nearby, and notes that store leaf paths should be passed to GET /papajohns/store.

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 provides explicit when-to-use guidance: omit path for the root country index, pass a child's path to descend through state, city, and store levels, and use nearby for coordinate search. It also routes store-looking children to GET /papajohns/store, making the choice among sibling tools clear.

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