get_dashboard_report

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

With no annotations, the description carries the full transparency burden. It discloses that the tool returns a structured JSON report with detailed fields and may return an error message. It also explains the behavior of activity_days ('Days of activity history to include'). It stops short of declaring read-only status or rate-limit behavior, but the 'Get' framing and report-only output are adequate for this reporting tool.

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 well-structured and front-loaded: a one-line summary, a compact but informative breakdown of the return payload, explicit use cases, then clear Args and Returns sections. Every sentence adds useful information without redundancy.

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 tool with two optional parameters and an output schema, the description is complete. It explains the return structure, parameter semantics, and appropriate usage contexts. The presence of an output schema means return-value details do not need to be fully restated, and the description already provides a strong overview.

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%, so the description is the only source of parameter meaning. It fully compensates: project is explained as 'Scope to a specific project (ID or folder name)' and 'Omit for vault-wide report'; activity_days is explained as 'Days of activity history to include' with its default of 30. This exceeds the schema's bare type definitions.

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?

Description uses a specific verb and resource: 'Get a structured dashboard report with project metrics, velocity, and activity.' It clearly enumerates the report contents (vault summary, per-project breakdowns, daily activity, task lists), so an agent understands exactly what the tool produces and can distinguish it from siblings like get_daily_dashboard or get_activity_report based on content.

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 explicitly states use cases: 'Use for rich status checks, project reviews, and weekly/monthly reporting.' It also gives scoping guidance for the project parameter ('Omit for vault-wide report'). It does not explicitly name sibling alternatives or exclusion conditions, but the context is clear enough for an agent to decide when this tool fits.

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