get_desk_summary

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

With no annotations, the description carries the full burden and does disclose the most important behavioral surprise: done cards older than the archive window are silently excluded from the list, yet the archived count is still reported, and includeArchived overrides the omission. It also caps output expectations under 800 tokens. It does not state read-only semantics or error behavior, but the truncation/filtering disclosure is substantive.

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?

Five short sentences, front-loaded with the call-priority instruction, and nothing is padding. The clipped fragments ('Compact desk under 800 tokens') are slightly telegraphic, but every sentence carries a distinct instruction.

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 zero-required-param, no-output-schema, no-annotation tool this is mostly adequate: size budget, archive filtering, and sibling routing are all covered. It never says what sections the summary actually returns (projects? card counts? statuses?), which is the main remaining gap for a summarization 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 100% and includeArchived already has a clear schema description, so the schema does the heavy lifting. The description reinforces it with the consequence (archived cards will be listed) and the reason to use it (the count already reveals their existence), which is modest added value over the schema. Baseline 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 establishes that this returns a compact/bounded summary of the desk and routes the agent away from list_projects for shallow needs. The verb is implicit rather than stated ('Compact desk under 800 tokens'), and it never enumerates what the summary contains, but an agent can tell it apart from siblings like get_project_status or search_desk.

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?

'Use this first' gives an explicit default-entry-point instruction, and 'Skip list_projects unless the user asks for a deep dive' names the alternative plus the exact condition that selects it. This is exactly the when/when-not/alternative structure the dimension rewards.

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