Get project context (call this first)

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

Annotations only declare readOnlyHint and idempotentHint; the description goes well beyond that with cap limits (fifty tasks, three entries per kind), byte budgets, the guarantee that nothing is truncated and every record keeps `id`/`head`, and the meaning of a null `body`. It also disambiguates the two families of omission counters and explains idle-task handling after 14 days.

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 purpose and the 'call it first' instruction are front-loaded before the truncation mechanics, and nearly every clause carries distinct operational information. The cost is a single dense block of backticked jargon that is hard to scan, and a few details (the `focus` semantics) are repeated from the schema.

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?

There is no output schema, so the description must carry the return contract itself, and it does: record shape (id/head/body), both counter families, the idle_tasks shape, ranked_by fields, and the summary_missing signal with the remedy. An agent can interpret every branch of the response without further sources.

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%, so the baseline is 3, but the description adds real semantic weight: `focus` spends budget on relevance rather than recency and 'can only move a record up, never drop one', plus the interaction between `focus` and the ranked_by fields. It adds less on `model` and `create_if_missing`, which the schema already carries.

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?

Opens with a specific, concrete framing ('The session-start briefing') and enumerates exactly what it returns: standing rules, decisions, dead ends, open questions, open tasks with linked files, and the last handoff. It also distinguishes itself from siblings by naming get_task and get_context_note as the tools that read the bodies this one truncates.

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?

'Call it first, with `cwd`' is an explicit ordering instruction, and the description routes follow-up reads to get_task/get_context_note and the summary gap to update_project. It also explains when `focus` is worth supplying versus letting recency drive the budget.

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