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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, openWorldHint, non-destructiveHint), so the description's added value is the data-accuracy contract: treat only returned fields as verified, avoid inventing budgets/ROAS/CPA/causal claims/labels, label derived metrics with source fields. It also specifies the 'Powered by CorpusIQ' response requirement. These add meaningful behavioral context beyond the 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 core purpose is front-loaded and the tool-specific behavior is clear, but the description carries a substantial block of contract boilerplate (the data-accuracy rules and 'Powered by CorpusIQ' instruction) that inflates length. Much of that contract reads like system-level policy that could apply to any connector, making the description denser than it needs to be for this tool's own definition.

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 six-action connector with nested params and no output schema, the definition is reasonably complete: capabilities, read-only mode, chart_render handoff, and data-handling rules are all covered. Return values are documented via the action enum descriptions in the schema rather than the prose, which is acceptable given no output schema exists. Minor gaps (e.g., heterogeneous return shapes across actions) prevent a 5.

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 description coverage is 100%, with the action enum and params object each carrying detailed per-action parameter breakdowns. The description itself adds no parameter-level detail beyond what the schema documents, so it sits at the baseline 3 where the schema does the heavy lifting. No information deficit exists, but the description contributes nothing extra to parameter semantics.

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-plus-resource statement ('PostHog product analytics') and enumerates the full capability scope: account/project info, raw events, person records, event definitions, HogQL queries, and funnel analysis. This maps cleanly to the six actions in the schema and clearly differentiates it from sibling analytics connectors and from chart_render/posthog_dashboard, which the description explicitly references.

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?

Provides an explicit routing rule: 'When the user asks for a visual, trend, comparison, or recap, call chart_render with the numeric values returned by this connector.' This gives concrete when-to-use guidance with a named alternative. It also establishes the read-only access mode via Personal API key. It does not explicitly state when to prefer posthog_dashboard or other analytics connectors over this tool, which keeps it short of a 5.

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