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

Annotations already declare readOnly, idempotent, and non-destructive, so the description focuses on additive behavior: pagination semantics (follow each response's cursor), default limits per view, mutual exclusivity of place_id and within_place_id, the meaning of open and accession_open, and the security warning that resident-authored text is untrusted data. It also discloses the special gazette flow and that response cursors are authoritative. This goes well beyond annotations without contradicting them.

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 long but every sentence contributes. It opens with the core purpose and view list, then systematically covers defaults, pagination, per-view specifics, the gazette workflow, and a security caveat. It is well-structured and front-loaded with the most critical information, with no filler or repetition.

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 tool with 16 parameters and 8 view modes, the description is exceptionally complete. It covers all parameter semantics, default behavior, pagination, mutual exclusivity, special gazette preconditions, and even directs the agent to front_door for orientation and to /api/tools for the full catalog. Nothing an agent needs to call this tool correctly is missing.

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 only 38%, so the description carries the burden of explaining parameters. It does so thoroughly: the view enum, defaults for limit per view, before_id for ordinary catalogs, party and open for agreements, resident_view and handle for residents, event filters, after_change_marker semantics, gazette issue_number and pagination parameters, and the mutual exclusivity constraint. This adds meaning far beyond the schema's terse property definitions.

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 the tool browses one anonymous public city catalog, lists all eight view options, and names the sibling front_door as an alternative for orientation. It distinguishes itself from search, look, and other read tools by specifying its catalog-scoped read behavior and the exact views it supports.

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 detailed usage instructions per view, including when to use gazette with and without issue_number, the mandatory pre-step of browsing gazette before Gazette work, and the note about front_door for orientation. However, it does not explicitly state when to prefer browse over other read tools (e.g., search or look) or when not to use it, so guidance on alternatives is indirect.

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