get_team_dashboard

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

The description is consistent with the annotations (a read-only, idempotent, open-world dashboard) and implicitly communicates read-only aggregation through 'dashboard' and 'summary stats.' It does nothing meaningful beyond that — it does not describe what defines 'active' vs 'blocked', how the summary stats are computed, or what the return format implies.

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 opening purpose sentence precedes an efficient Args block that maps each field and default directly. Each line earns its place with no filler or redundant prose.

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?

The output schema covers the return format, so that omission is fine, and the safety profile is covered by annotations. But the definition doesn't characterize what 'top blocked' or 'top active' mean, what the 'summary stats' contain, or how instance scoping interacts. It's a serviceable but not complete spec for a composite-data tool.

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 0%, but the description provides meaningful meaning for all six fields — project short name, top N for active/blocked, grouping by Product, comma-separated regex for exclusions, and optional youtrack instance. The main gap: exclude_patterns doesn't say what is being excluded, and 'active'/'blocked' are not defined.

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?

States a specific combined purpose — a dashboard of top active, top blocked, and summary stats for a project — with a clear verb-resource structure that sets it apart from separate top-issue tools in the sibling set. It doesn't explicitly name the sibling alternatives, but the 'combined' framing effectively distinguishes it from get_top_active_issues and get_top_blocked_issues.

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 offers no guidance on when to call this tool instead of alternatives like get_top_active_issues, get_top_blocked_issues, or get_multi_team_dashboard. The word 'combined' hints at the intended use, but there's no explicit when/when-not rule or mention of which sibling to reach for.

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