get_stats

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

With no annotations provided, the description must carry the behavioral burden itself. It does convey that this is a read-only aggregate operation and lists the response contents, which is the core safety-relevant trait, but it adds no depth beyond that — nothing about freshness of stats, computation cost of a DB-wide scan, or auth/rate-limit implications.

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?

Two sentences with zero filler: the first states the deliverable and its contents, the second states when to reach for it. The core identity ('DB-wide overview') is front-loaded and every sentence earns its place.

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 zero-parameter tool with an output schema, the description covers nearly everything an agent needs: what it returns and when to call it. The only notable gap is that it doesn't explicitly differentiate from the overlapping sibling get_outreach_stats, though the 'DB-wide' wording does most of that work.

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 tool has zero parameters and the input schema is empty, so the description owes nothing here; the baseline of 4 applies. The words 'date range' and 'category breakdown' describe output fields, not inputs, and the output schema documents the return shape.

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 specific verb and resource: 'Return a DB-wide overview' and enumerates the exact contents (total posts, accounts, date range, category breakdown). The 'DB-wide' framing separates it from the sibling list_* tools and the outreach-specific get_outreach_stats without requiring schema inspection.

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?

'Useful for a quick orientation before diving into posts' gives a clear temporal/use-case signal: run this first for orientation, then move to post-level tools such as list_posts or search_posts. It provides clear context but stops short of explicitly naming alternatives or stating when not to use it.

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