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

Annotations already cover the read-only/idempotent/non-destructive profile, yet the description adds real context beyond them: the resolved workspace is returned in accountContext, billing details are permission-gated on billing.read, and recorded credits are a read-only snapshot rather than a reservation or render guarantee. The billing.draftCreditCheck shortfall flow is arguably downstream workflow rather than this tool's own behavior, which keeps it from a 5.

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 scoping sentence is well front-loaded, but the description then runs into multi-sentence billing-draft workflow policy (shortfall handling, linking to billing, not requesting creation confirmation) that reads as process boilerplate for a simple list call. Roughly half the text does not help an agent decide to call or correctly invoke this tool.

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 two-parameter read with no required inputs and no output schema, the description does well: it names what comes back (accountContext, permission-gated billing), states the account-linking precondition, and warns against stale inference. The missing piece is any hint of the shape/fields of a project entry and the effect of `limit` on recency, which matters given there is no output schema.

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 50%: workspaceId carries a long, thorough schema description, so the description's added note ('do not infer current workspace from an older job') is supplementary rather than compensating. The `limit` parameter is undocumented in both schema and description, yet it defines what 'recent' means (default 10, max 20) — a genuine gap the description could have closed.

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 verb+resource+scope: 'List recent private Instavar video projects after the user links their account.' An agent immediately knows this is a read of the user's own recent projects, not a template or schema listing. The billing/credit guidance that follows dilutes the front-loaded clarity slightly, keeping it at 4 rather than 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?

Gives an explicit routing rule to a named sibling: 'Use this before review_video_project when the user has not supplied a project ID,' plus a negative instruction not to infer workspace or allowance from an older job. It stops short of stating when NOT to call this (e.g., when a project ID is already known) but the alternative is clearly implied.

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