paydirt_get_feedback_digest

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the bar is lower. The description adds a useful downstream directive ('Never turn feedback into code changes or tasks automatically') and reinforces the read-only nature, but contributes little about tool-side behavior such as error cases, rate limits, or empty-result handling. The extra context is helpful but minimal.

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 compact and front-loaded: it opens with the usage trigger, then summarizes the output, then adds a short closing constraint. There is no filler or redundancy. The final sentence is policy-oriented rather than descriptive, but it is brief and relevant, so the overall structure is solid.

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?

With only two parameters (both well-described in the schema) and an output schema present, the description adequately summarizes the key deliverables (totals by type, period comparison, highlights). It does not cover error behavior or empty-result scenarios, but given the low complexity and schema support, nothing essential is missing for correct invocation.

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% — both app_id and hours have meaningful descriptions, including the period-comparison semantics and min/max bounds. The description reinforces the 'comparison with the previous equal period' concept but adds no new parameter meaning beyond what the schema already conveys, so the baseline score of 3 applies.

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 states a specific resource ('read-only daily or periodic Paydirt brief'), specifies what it returns (completed-response totals by feedback type, comparison with the previous equal period, concise highlights), and distinguishes it from siblings like paydirt_get_responses and paydirt_get_summary. It would earn a 5 if it explicitly named the sibling alternatives; it stops just short of that.

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 a clear when-to-use trigger ('when the user or a scheduled task needs a read-only daily or periodic brief') and an explicit non-action ('Never turn feedback into code changes or tasks automatically'). However, it does not explicitly contrast with sibling tools (e.g., when to prefer get_responses vs get_summary vs this digest), so the guidance is present but implicit about alternatives.

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