Citizen

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

With no annotations provided, the description carries the full burden of disclosing behavior. It thoroughly covers what the tool returns (social graph, deities, personality extremes, etc.), defines friends/grudges, notes placeholder caveats in thoughts, states empty categories degrade to [], and explicitly covers error responses for missing unit_id or no fort. It even clarifies 'Facts only — it senses, it does not advise.'

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 each sentence provides valuable detail, from data categories to error handling to placeholder behavior. It is front-loaded with the main purpose and uses a clear contrast with find_unit. While slightly verbose, it does not waste words and is well-organized.

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 the absence of an output schema and annotations, the description does an excellent job of covering all necessary context. It enumerates the full set of returned categories, defines the semantics of friends/grudges, explains the placeholder issue, and states both error conditions. It fully equips an agent to decide when to call the tool and what to expect.

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 documents unit_id with pattern and description, so the baseline is 3. The description adds extra meaning by explaining where unit_id comes from ('find_unit or chronicle') and that it enables graph walking ('each with a unit_id you can pass back into citizen()'). This adds chaining semantics beyond the schema.

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 it provides 'a deep dossier on ONE citizen' and differentiates from the sibling tool by explicitly noting 'Where find_unit stays compact, this is the depth.' This identifies the tool's specific verb (provide a deep dossier) and resource (citizen), distinguishing it from alternatives.

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 explains the chaining context: 'chained by unit_id from find_unit (or chronicle)' and contrasts with find_unit. This provides clear context on when to use the tool, but it doesn't explicitly list exclusions or say 'don't use when you only need a compact summary.' The alternative is named, so it nearly meets the highest bar.

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