scheduling.getQueue

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description nevertheless adds real information: the operation is idempotent, the result is a snapshot that can go stale after scheduling changes, scope is collection, and undo is not applicable. It also enumerates four possible errors (collectionUnavailable, internalError, invalidParams, staleSession), which is behavior an agent cannot get from annotations. It stops short of describing the return payload's shape (card fields vs. counts structure), which matters since there is no output schema.

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?

Front-loaded with the one-line summary, then supporting behavior, then provenance/effect/error metadata in a scannable form. The metadata lines ("Scope: collection. Effect: read. Completion: completed. Undo: none.") border on boilerplate duplicating annotations, but they are compact and cheap to skip. No sentence is genuinely wasted, though the block format is longer than strictly necessary.

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 parameterless read of the scheduler queue, the description covers source of truth (selected deck), ordering semantics, snapshot staleness, error surface, and safety. The remaining gap is the return value: with no output schema, "with remaining counts" only gestures at the payload without saying what fields come back. Otherwise an agent has enough to call it correctly.

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 both `session` and `fetchLimit` are already fully documented in the schema, including the staleSession trade-off and the 1–1000 range. The description adds nothing about parameter meaning beyond that. Baseline 3 is correct when the schema carries the burden entirely.

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 first sentence states a specific verb and resource ("Read cards") plus two defining traits of the result: native scheduler order and remaining counts. It also pins the source to "Anki's currently selected deck" and notes it respects native limits, mixing and scheduler order, which is much more specific than a title restatement. It does not explicitly contrast itself with near siblings such as scheduling_get, scheduling_getDue or scheduling_predict, so it stops short of a 5.

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?

Usage is implied rather than stated: the reader can infer "call this when you want the actual runnable queue as Anki would serve it" and that the selected deck matters. There is no explicit when-to-use/when-not-to-use guidance and no naming of the sibling to use instead for due-date or prediction questions. The idempotency note ("subsequent scheduling changes can change the snapshot") is context, not routing guidance.

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