get_overview

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

With no annotations provided, the description carries the full burden. It discloses the token-efficient nature and mentions 'key metrics' and 'recent items' as return contents. However, it omits response structure, calculation methods for metrics, pagination behavior, and whether the user_id filter restricts the entire overview or just recent items.

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?

Single sentence with zero waste. The core action and resource appear first ('Get a high-level overview'), followed by content details ('key metrics and recent items'), and ends with the efficiency characteristic. Every clause 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?

Given three optional parameters and no output schema, the description adequately hints at return contents ('metrics', 'recent items') but falls short of describing the actual response structure. For a read-only overview tool with 100% schema coverage, the description covers intent but lacks operational specifics expected when no annotations or output schema exist.

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 100%, establishing a baseline of 3. The description mentions 'recent items' which maps to the include_recent_deals and include_recent_activities parameters, reinforcing their purpose. However, it adds no semantic detail about the user_id parameter beyond the schema's 'optional' designation, nor does it explain interaction effects between parameters.

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 uses a specific verb ('Get') and resource ('high-level overview'), clearly indicating this is an aggregate dashboard endpoint rather than a specific entity fetcher. The mention of 'key metrics and recent items' clarifies the content scope, distinguishing it from siblings like get_deal or get_activities that return full records.

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 parenthetical '(very token-efficient)' implies usage for quick summaries versus detailed data retrieval, but lacks explicit when/when-not guidance. It does not name alternatives (e.g., 'use get_deals for full deal details') or specify prerequisite conditions.

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