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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes well beyond: it discloses in-process polling, the ~timeout bound, that a transport reset does not lose the wait, and the duplicate-risk of the unconfirmed state. That is behavioral context the annotations cannot carry.

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?

Purpose and parameter guidance are front-loaded, and the status bullets are each actionable rather than decorative. It is longer than a minimal definition and repeats the same-link reuse point, but no line is pure filler.

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?

Despite an output schema existing, the description enumerates the status payloads so the agent can branch on results, and it covers the required parameter and the polling/timeout behavior. Nothing needed to call it correctly or react to its output is missing.

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 0%, so the description must compensate, and it does for upload_link by explaining it accepts either the human_upload.url or a bare token. The timeout parameter is only referenced obliquely ("after ~timeout s") without clarifying units or tuning guidance, leaving a small gap.

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?

States a specific verb and resource — wait for a file upload issued through source_add(source_type="file") to commit — and ties it to a concrete URL/token returned by that call. The scoping to the file-upload flow makes it distinguishable from the other wait-style siblings.

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 explicit routing for every outcome: re-invoke with the same link on pending, check source_list on unconfirmed to avoid duplicate sources, and mint a fresh link via source_add on expired_or_invalid. This is when-to-use, when-not, and alternatives in one place.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it explains conversation continuation behavior, the rejection when neither question nor history is passed, the recall-only echo of conversation_id, the lack of an unbounded 'all' value for history, the structure of returned references (lite vs full), and the conditional presence of suggested_prompts. This is rich, transparent behavioral disclosure that goes well beyond what the schema provides.

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 long but front-loaded with the core purpose, then organized into focused paragraphs per parameter and behavior. Every sentence earns its place by explaining a distinct rule or edge case (e.g., the comma-separated source_ids caveat, the recall-only echo, the rejection condition). There is no redundancy or filler.

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?

Given the complexity (7 parameters, no annotations, an output schema that exists but is not shown here), the description is complete enough for an agent to invoke the tool correctly. It covers all inputs, defaults, edge cases, return shape details, and the interaction between question, history, and suggest_followups. Nothing essential is missing.

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 0%, so the description must compensate and it does. Every parameter is documented in prose: notebook (name or ID), question (omitted for recall-only), conversation_id (continue a specific conversation), source_ids (scoping, accepted formats including the comma limitation), history (default 0, max prior Q&A pairs, no unbounded value), references (lite/full detail), and suggest_followups (default False, works alone). This fully covers the 7 parameters and adds meaning beyond the bare schema types.

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 opens with a specific verb and resource: 'Ask a notebook's sources a question, and/or recall prior turns.' It clearly distinguishes this tool from siblings like chat_start, chat_status, and suggest_prompts by focusing on question-answering and recall, and it names the required input (notebook name or ID). An agent can tell what the tool does without opening the schema.

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?

The description gives clear context for when to use the tool (ask a question, recall history, or get suggested follow-ups) and explains key decision points such as passing conversation_id vs omitting it, and using history > 0 with an empty question for recall-only. However, it never explicitly names alternative tools like suggest_prompts or chat_start, so it lacks direct when-to-use-vs-alternatives guidance.

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

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

With no annotations, the description carries the full burden and delivers real behavioral detail: the default for conversation_id, the ordering of the cancel (local stream abandoned before the Google session), and rejection of unknown or cross-notebook task IDs. It doesn't say whether cancellation is idempotent or what an already-finished generation yields.

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?

Purpose is front-loaded in the first sentence, then defaults and the task_id workflow follow in tight order. The sentence about abandoning the local stream is slightly dense but still earns its place by explaining cancellation ordering.

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?

An output schema exists, so return values need no explanation, and the description covers the mutation's effect and its error case. It is nearly complete for a 3-param, no-annotation tool; only the notebook identifier's expected form is unaddressed.

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 0%, so the description must compensate, and it does: conversation_id defaults to the notebook's most-recent session and task_id must come from chat_start and pertain to the same notebook. The 'notebook' parameter's format is not elaborated, leaving one gap.

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?

States a specific verb and resource: 'Stop a notebook's active chat generation.' The scope (notebook's active chat generation) clearly separates it from siblings like research_cancel and chat_start, so an agent can identify it without opening the schema.

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?

Explains the condition for using the optional task_id ('when cancelling a detached ask') and routes the agent to chat_start as the source of that value. It does not explicitly name an alternative cancellation tool or state when cancellation is unnecessary, so it stops short of a full when/when-not pair.

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

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

With no annotations, the description carries the full burden and delivers substantive mutation semantics: chat_mode wholesale-replaces settings, partial custom calls merge and preserve omitted fields, and a bare call is rejected because it would reset everything to default. It stops short of 5 only because permission/auth requirements and the exact reset scope are unstated.

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 purpose sentence, then two tight bullets that each encode a distinct rule with no filler. The nested emphasis formatting is slightly heavy for the amount of content, but every sentence carries a usable constraint.

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 mutation tool with no annotations and an output schema (so return values needn't be described), the description covers mutually-exclusive modes, merge behavior, and rejection cases. Only auth/permission context and the full list of affected settings are missing, leaving a minor gap.

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 0%, so the description must supply all meaning and does: it names the chat_mode presets, explains goal as a custom persona that selects the CUSTOM goal, gives the response_length options, and confirms notebook accepts a name or ID. Every parameter is semantically documented beyond the bare schema.

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?

States a specific verb and resource: 'Configure a notebook's chat behavior,' which is clearly a configuration action distinct from chat_ask/chat_start/chat_status siblings. It never names a sibling explicitly, so it stops short of a 5, but an agent can place it in the chat family without opening the schema.

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?

Explicitly lays out when each path applies: a preset via chat_mode replaces the whole block and is rejected if combined with goal/response_length, while goal/response_length set a custom config that merges on partial calls and is only rejected when the call is bare. This is a precise when/how-not map for a 4-param tool.

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

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

With no annotations, the description carries the full burden and does so: it discloses server-side execution independent of call outcome, both return statuses and their meaning, the ~20-30s polling guidance, double-generation prevention via already_running, the ~30-minute pollability window, and the no-replay rule after source_add/chat_configure. This is unusually rich behavioral context.

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 core purpose is front-loaded in one sentence and the return shapes are bulleted for scannability. It is on the long side, but nearly every clause carries actionable information (timeouts, polling interval, retention window), so little is wasted.

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 background-task tool with no annotations, the description covers the full lifecycle an agent needs: when to use it, what it returns, how to poll, how long results persist, and how repeated asks behave. Output schema exists, yet the description still usefully explains status semantics that a schema alone would not convey.

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 0% across 5 parameters, so the description must compensate. It does partially by stating parameters mirror chat_ask's ask path and that history/suggest_followups are chat_ask-only, but it never explains notebook, question, references (lite/full enum), source_ids, or conversation_id semantics. Some compensation, but a real gap remains.

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 opening sentence states a specific verb (start) and resource (chat ask) plus the key behavioral fact (detached background task, returns immediately). It explicitly contrasts itself with chat_ask and chat_status, so an agent can distinguish it from siblings without opening any schema.

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?

It states exactly when to use this tool (generation may run long; remote transports cut blocking calls at ~60s of silence) and names the alternative for the opposite case ('For questions expected to answer quickly, chat_ask stays the one-call path'). It also directs the agent to chat_status for collection, which is the required follow-up.

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

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

Annotations only declare readOnlyHint=true and destructiveHint=false. The description goes well beyond them by enumerating per-task states (pending/completed/failed/unknown), their sub-states (queued vs generating), the timing fields (queued_s/generation_s), the error object shape, batch ordering behavior, and the 64-id cap. This is exactly the behavioral detail an agent needs and cannot get from annotations.

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?

It is long, but the length is justified by two distinct modes and four status classes. It is front-loaded with the mode summary and uses headers and bullets to structure the detail. Slightly heavy, but nearly every sentence carries substantive information.

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 3-optional-param tool with two modes and an output schema present, the description covers both modes, all parameters, return shapes, and error handling. Even though the output schema exists, it explains return structure usefully. Nothing an agent needs to call it correctly is missing.

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 0%, so the description must carry the load, and it does: task_id accepts a single id, a list, or a comma-separated string; notebook is the alternate mode selector; conversation_id is optional and defaults to the notebook's most-recent conversation. It also documents the divergent return shapes (single dict vs {"tasks": [...]}) per input type.

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 opening line states a specific verb+resource with two distinct scopes: 'Poll detached asks, or inspect a notebook's live generation session.' This clearly separates it from siblings like chat_ask, chat_start, and studio_status. An agent can identify the tool's function without opening the schema.

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 strong operational context: re-invoke every ~20-30s while pending, polling never restarts a generation, at most 64 ids per call, and that the two modes are mutually exclusive. It also routes the agent by outcome (retriable failure -> one chat_start retry; unknown -> chat_start again). It stops short of explicitly naming alternative tools in a 'use X instead' form, so it does not reach the top tier.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not state whether the title must be unique, whether the call is idempotent, what side effects occur, or what permissions are required for a mutating operation.

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?

A single front-loaded sentence with no wasted words. It is appropriately sized, though the brevity comes at the cost of under-specification rather than being genuinely complete.

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?

An output schema exists, so return values need not be explained, and the tool is a simple one-parameter create. Still, with zero annotations the description leaves mutation semantics and title constraints unstated, making it only minimally adequate.

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 0% for the single parameter, so the description must compensate. 'With the given title' only restates the parameter name; it adds no constraints on format, length, or uniqueness.

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?

States a specific verb and resource ('Create a new notebook'), which is clearly distinct from sibling mutation tools like notebook_rename or notebook_delete. However, it does not explicitly contrast itself with any sibling or scope what a 'notebook' is in this context.

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?

There is no guidance on when to use this versus alternatives (e.g., notebook_rename for an existing notebook, or whether creation is a prerequisite for source_add). The agent must infer usage entirely from the name.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds substantially more: the operation is irreversible, the default behavior does NOT delete, and the call returns a needs_confirmation preview. The requirement to re-submit the canonical notebook_id identifies a real behavioral constraint not expressible in the 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?

Three tightly packed sentences: effect and irreversibility first, then the resolution rule, then the two-step confirmation flow. No filler, and the most consequential fact (irreversible) is front-loaded.

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?

An output schema exists, so return-value documentation isn't required, yet the description still names the needs_confirmation preview. For a 2-parameter destructive tool, everything needed to invoke it safely and correctly is present.

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 0%, so the description carries the full burden and does so: 'notebook' accepts a name or ID, and 'confirm' defaults to false and gates actual deletion. Both parameters gain meaning that the type-only schema lacks.

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?

States a specific verb and resource ('Delete a notebook') and immediately flags irreversibility. It is trivially distinguishable from siblings like notebook_rename, notebook_create, and notebook_describe.

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 operational workflow: call with confirm=False to get a preview, then re-submit the canonical notebook_id with confirm=True. That is clear when-to-use guidance, though it never names alternatives (e.g., notebook_list to resolve a name) or states preconditions such as required permissions.

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

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 adds real value beyond that: it discloses the resolved return shape (``notebook_id`` plus ``description``), the conditional ``metadata`` key, and explicitly promises that the default output is unchanged when ``include_metadata`` is omitted.

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 core action in the first sentence, then the return contract and the optional flag. Mostly efficient, though the second sentence is slightly dense with formatting artifacts. No filler sentences that fail to earn their place.

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 an output schema present, return values need not be spelled out, yet the description still explains the resolved ID, description, and conditional metadata key, so nothing critical is missing. Minor gaps remain around error behavior when the notebook lacks a description or does not exist.

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 0%, so the description must carry the parameter burden, and it does: it clarifies that ``notebook`` accepts either a name or an ID (the schema only says 'string') and explains what ``include_metadata=True`` fetches and how it changes the response. It does not mention the boolean default of false directly, but that is covered by the schema.

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?

States a specific verb+resource: fetch a notebook's AI-generated description from a name or ID. That distinguishes it from siblings like notebook_list, notebook_rename, and notebook_delete, though it never explicitly names an alternative. The purpose is clear without being tautological.

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 only implied by the purpose statement: you call it when you need a notebook's AI description. There is no stated when-not-to-use, no mention of prerequisites (e.g. notebook must exist or already have a generated description), and no routing to a sibling such as notebook_list.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context on top: results are a bounded page, limit defaults to 50, offset defaults to 0, and has_more signals termination. That is the kind of pagination contract an agent needs and is not derivable from the annotations.

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?

Two short paragraphs, front-loaded with the purpose before the pagination mechanics. Every sentence earns its place, though the return-field enumeration in the first sentence is partially redundant with the existing output 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?

For a simple two-parameter, zero-required list tool with an output schema present, the description covers the essentials: what is listed, what comes back conceptually, and how to page. It does not need to explain return values further, though a note on ordering would have closed the last gap.

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 0%, so the description carries the burden, and it does so well: it states limit's default (50), offset's default (0), and the arithmetic for advancing (offset += limit). The only gap is that it doesn't warn about a maximum limit or behavior when limit is very large.

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 opens with a specific verb and resource: "List all notebooks (id + title + metadata)." It even previews the returned fields. It does not explicitly contrast itself with siblings like source_list or studio_list, but the resource noun is distinctive enough that an agent can route to it reliably.

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?

The description explains the pagination workflow (re-call with offset += limit while has_more is true), which is genuine procedural guidance. However, it says nothing about when to choose notebook_list over the other list-style siblings (source_list, studio_list), so tool selection guidance is only implied.

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

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

No annotations are provided, so the description carries the full burden. It does not say whether rename requires ownership/permissions, whether duplicate titles are allowed, whether the change is reversible, or what happens if the name is ambiguous. For a mutation tool this is a significant gap.

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?

Two short sentences, verb and resource front-loaded, no filler. It is terse to the point of omitting necessary behavioral context, but nothing is wasted.

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?

An output schema exists so return values need not be described, but for a mutation tool with no annotations and no schema descriptions, the definition omits permissions, error/ambiguity behavior, and title constraints, leaving the agent under-informed before calling.

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 0%, so the description must compensate. It clarifies that the `notebook` parameter accepts either a name or an ID, which is genuine added meaning, but says nothing about `new_title` (constraints, length, uniqueness).

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?

States a specific verb and resource ("Rename a notebook"), which is immediately clear. It does not, however, differentiate from potential siblings like studio_rename or source_rename, nor explain what a "notebook" is in this system.

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?

No guidance on when to use this versus notebook_create, notebook_describe, or the rename tools for other resources. No prerequisites or conditions are stated.

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

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

With no annotations, the description carries the full behavioral burden and mostly succeeds: it discloses upsert semantics, per-mode required inputs, that content-only replaces the body, and that unresolved refs error rather than create. It also names the returned status values. It does not mention permissions, rate limits, or idempotency guarantees, which keeps it short of 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 core upsert behavior is front-loaded in one sentence, then the create/update branches are laid out as scannable bullets. Every sentence conveys operational detail with no redundant restatement of the name or title.

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?

An output schema exists, so return values need not be detailed, though the description helpfully mentions status='created'/'updated'. It covers mode dispatch and error semantics thoroughly, but omits what happens if the notebook reference itself is invalid or whether notebook existence is required, leaving a small gap for an upsert mutation with no annotations.

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 0%, so the description must compensate, and it does: it explains 'note' as the mode switch, defines title-only as rename and content-only as body replacement, and clarifies 'notebook' accepts a name or ID. All four parameters gain meaning beyond their bare types.

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 verb and resource with dual scope: 'Create a note, or update an existing one (upsert).' It precisely names the parameter that dispatches behavior and the notebook reference it accepts, so an agent can identify the tool's job immediately without opening the schema.

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?

It gives explicit when-to-use rules for both modes: omitting 'note' triggers create with both title and content required; supplying 'note' triggers update with at least one of title/content. It also states edge behavior ('A ref that doesn't resolve is a not-found error, NEVER a stray create'), removing any ambiguity about branch selection.

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

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

With no annotations, the description carries the full burden and does so: fire-and-forget semantics, no RPC when the run is terminal, the cancel_requested:false plus observed status response, replication-lag handling for not_found/no_research, and exact return fields.

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 purpose sentence followed by tightly packed behavioral detail; every clause carries information. Slightly dense but no wasted sentences.

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 mutation tool with no annotations, the description covers async behavior, edge cases, parameter sourcing, and return semantics; the accompanying output schema is not required to carry anything the description omits.

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 0%, yet the description explains all three parameters: notebook accepts a name or ID, poll_task_id is the value from research_start/research_status, and run_id is a deprecated alias removed in v0.9.0. This fully compensates for the empty schema descriptions.

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 ('Cancel an in-flight research run in a notebook') and scopes it to research runs, cleanly separating it from siblings like research_start and research_status. An agent can identify the tool without opening the schema.

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?

Explicitly states where poll_task_id comes from (research_start/research_status) and tells the agent to poll research_status afterward, plus the terminal-state no-op case. It lacks an explicit 'do not use when X' beyond the terminal case, but the routing context is clear.

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

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

With no annotations, the description carries the full burden and does so well: it discloses timeout tolerance and reconciliation of committed imports, idempotency (URL-based skipping as 'already_present'), the allow_duplicate override, cited_only fallback behavior, and max_sources capping. It also flags task_id as a deprecated alias removed in v0.9.0, which is essential migration context.

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 leads the description and each subsequent paragraph covers a distinct concern, so it is well front-loaded and mostly earns its space. It is somewhat dense with backticked identifiers, but there is little outright waste.

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?

An output schema exists, so return values need not be explained, and the description richly covers behavior for a 6-parameter mutation tool. It omits any note on required permissions or write access to the notebook, which would round out the picture given the absence of annotations.

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?

Despite 0% schema description coverage, the description explains every parameter: notebook (name or ID), poll_task_id (source from research_start/status), the deprecated task_id alias, cited_only semantics including the 'all if none resolve' fallback, max_sources as a cap, and allow_duplicate re-add behavior. It fully compensates for the schema gap.

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?

States a specific verb and resource ('Import a completed research task's sources into the notebook') and pins the scope to a completed research task, clearly distinguishing it from research_start/research_status. An agent can identify the operation without opening the schema.

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?

Explicitly ties usage to the sibling tools by saying poll_task_id is 'the value from research_start / research_status', giving a clear when-to-use context. It stops short of stating when not to use this tool or naming an alternative for other import scenarios, so it does not reach a 5.

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

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 meaningful behavior: the call is non-blocking, returns a poll_task_id that drives polling across three other tools, sources are not added until research_import, and deep mode is web-only. It omits auth/permission requirements, rate limits, and error behavior, keeping it short of 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?

Front-loaded with the purpose, then the workflow, then parameter semantics. Dense but every sentence carries useful information; the middle pipeline paragraph is slightly heavy but earns its place by naming the exact companion tools.

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?

Given an output schema exists, return values need not be re-explained, yet the description usefully highlights the poll_task_id from the return. Combined with the enum parameter semantics and workflow, an agent has enough to invoke this correctly; only the absence of failure/auth context keeps it from being fully complete.

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 0%, so the description must compensate and largely does: source (web default / drive), mode (fast default / deep, web-only constraint), and notebook (accepts name or ID) are all explained with defaults and constraints. Only query is left implicit, which is self-evident.

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?

States a specific verb and resource ("Start a research session in a notebook") and distinguishes itself cleanly from siblings like research_status, research_cancel, and research_import, which it references directly. An agent can tell what this does without opening the schema.

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 workflow: it is non-blocking, the returned poll_task_id should be carried into research_status/research_import/research_cancel, and you poll status until completed before importing. This tells the agent exactly how this tool fits the pipeline, though it never states when NOT to use it (e.g., vs chat_ask) or any preconditions.

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

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 goes well beyond by disclosing that report/report_markdown are omitted unless include_report=True, truncation semantics (report_char_count/report_truncated), pagination via source_limit/source_offset, how termination_reason splits 'failed', and that task_id is a deprecated alias removed in v0.9.0.

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?

Dense but front-loaded, leading with purpose and the poll-to-import workflow before parameter minutiae. Each sentence carries substantive information, though the backtick-heavy formatting makes it 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?

An output schema exists, yet the description still explains the key return fields and their conditional presence, and every parameter is accounted for. For a 7-parameter polling tool with deprecated-alias and pagination quirks, nothing an agent needs to call it correctly is missing.

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?

With 0% schema description coverage, the description carries the full burden and does so: it documents notebook (name or ID), poll_task_id (pins an in-flight task, ambiguity behavior), task_id (deprecated alias), include_report, report_max_chars (truncation cap), and source_limit/source_offset (paging). Nearly all seven parameters gain meaning absent from the raw schema.

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?

States a specific verb+resource ('Check a notebook's research status') and immediately enumerates the returned status values (no_research|in_progress|completed|failed|not_found), which distinguishes it from siblings like research_start, research_cancel, and research_import. An agent can identify the tool's role without opening the schema.

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?

Explicitly prescribes the workflow: poll until 'completed', then pass 'poll_task_id' to research_import. It also explains the disambiguation rule ('omit for a single task (ambiguous with two+)') and that an unmatched pin yields not_found, leaving nothing to inference for a polling tool.

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

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

Annotations only cover the read-only safety profile; the description adds substantial behavioral context beyond that: the default call is a 'fast, network-free probe,' include_account requires a live session, and failures degrade to {available: False, reason} instead of erroring. It also explains a deliberate omission (on-disk storage path) for security reasons.

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 information is front-loaded: purpose, then default behavior, then the opt-in block, then the security rationale. It is long for a one-parameter read tool, and the security-rationale paragraph, while useful, is more prose than an agent strictly needs, so it falls short of maximum conciseness.

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?

Despite an output schema existing, the description fully explains the meaningful blocks and their degraded states, the default-vs-opt-in tradeoff, and the login prerequisite. Nothing an agent needs to call this correctly or interpret a failure is missing.

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 0% and the single parameter is undocumented in the schema, so the description carries the full burden — and does: it explains exactly what include_account=True adds (account identity plus quota fields), why it is off by default, and how its fields behave when the session is stale.

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 opens with a specific verb+resource: 'Report the server version and local authentication health,' and enumerates the exact return blocks (version, chat_tasks gauges, auth). No sibling tool does this, so an agent can distinguish it immediately.

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?

It gives two concrete usage conditions: check chat_tasks load 'before submitting a chat_start batch' and confirm login 'before driving notebook tools,' plus a remediation step ('run notebooklm login'). It lacks any explicit when-not-to-use guidance or named alternative, which keeps it at 4 rather than 5.

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

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

Annotations disclose readOnlyHint=false and destructiveHint=true, but the description goes well beyond: it explains the confirm-gated two-step protocol, that the default call is a non-mutating preview, and that confirm=True is required to actually mutate. This reveals behavior the annotations alone would not convey.

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 purpose sentence, then a tight confirm-gate paragraph. No filler, and the safety-critical detail (default is a preview) is surfaced early. The inline `` `` markup is slightly noisy but harmless.

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?

An output schema exists, so return-value explanation is unnecessary, and the confirm flow covers the safety story for a destructive operation. It could mention whether removal is reversible or what the preview contains, but for a destructive mutation it is otherwise complete.

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?

With 0% schema coverage, the description must compensate, and it largely does: 'notebook' accepts a name or ID, 'confirm' defaults to False and gates mutation, and 'email' must be submitted 'verbatim.' The confirm mechanics and the name/ID flexibility add real meaning beyond the bare schema.

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?

Specific verb + resource + target: 'Remove a user's access to a notebook.' The verb 'remove' cleanly distinguishes it from siblings share_set_user and share_set_access, which grant/set rather than revoke access. An agent can identify the operation without opening the schema.

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?

The description gives clear invocation context via the two-phase confirm pattern: 'called with confirm=False (default) it does NOT mutate — it returns a preview,' then re-submit with confirm=True. This is strong operative guidance, but it never names an alternative tool (e.g., when to prefer share_set_user/share_set_access over this revocation).

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

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

With no annotations, the description carries the full burden and does so: it names the confirmation gate, the token needed to confirm, that the returned view_level is only echoed when set and that the read API cannot report it, and the ordering (view_level before public) chosen so a partial failure fails closed. This is unusually rich behavioral disclosure for a mutation tool.

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?

Four tight sentences, front-loaded with the purpose and the field semantics before the encoding of edge cases. The parenthetical asides (canonical notebook_id, view_level echo) are dense but each earns its place; a small amount of re-reading is required.

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 4-parameter mutation tool with no annotations and a 0% schema description coverage, the description covers purpose, field semantics, the confirmation workflow, and failure-ordering behavior. An output schema exists, so return shape needn't be fully documented, and the one return caveat that matters (view_level echo) is included.

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 0%, so the description must compensate, and it does for all four parameters: notebook accepts name or ID, public is defined as True=anyone-with-link / False=restricted, view_level takes full or chat, and confirm is explained through the confirmation flow. It adds genuine meaning beyond the bare schema types.

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?

States a specific verb and resource ('Set a notebook's link-access settings') and immediately scopes it to link-level access, which cleanly separates it from the per-user siblings share_set_user and share_remove_user. It also discloses the accepted identifier form (name or ID), so an agent can pick it without opening the schema.

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 clear conditions for the confirmation path ('public=True on a restricted notebook returns a needs_confirmation preview; confirm with its canonical notebook_id') and explicitly excludes restricting and view_level changes from gating. It does not name sibling alternatives (e.g., share_set_user) or state when to prefer them, so it stops short of a 5.

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

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

With no annotations the description carries the full burden and does reasonably well: it discloses upsert semantics, the 1-100 grant limit, that batches may mix editor/viewer, that notify/message apply to all grantees, and the preview/confirm behavior. It does not cover auth/permission requirements or what happens to grants not re-listed, which keeps it short of 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?

Front-loads the core upsert contract, then layers the workflow and batch/scope details in short lines. Dense and largely waste-free, though the backtick-heavy formatting makes it slightly harder to scan than plain prose.

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?

An output schema exists, so return values needn't be re-explained. For a 7-parameter upsert with mixed grant batching, the description covers the essential selects and behaviors; only permission/auth prerequisites and partial-failure behavior are left uncovered.

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 0%, so the description must compensate, and it largely does: it explains email + permission, the grants array shape and its editor/viewer values, notify and message scope, and the confirm/notebook_id step. Remaining ambiguity is minor (exactly what notify sends, what confirm does on failure).

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?

States a specific verb+resource ("Upsert access") and immediately disambiguates its two input modes (single email+permission vs. a batch of grants). It is clear about what the tool mutates, though it never explicitly contrasts itself with the nearby share_set_access or share_remove_user siblings, leaving some routing to inference from the tool name.

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 concrete conditional guidance: use email+permission for a single grant or 1-100 grants for a batch, and it describes the preview-then-confirm workflow with the notebook_id. It lacks any explicit when-not-to-use or sibling-alternative statement (e.g. share_set_access vs. share_remove_user).

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

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

Annotations already declare the safe read-only profile, and the description adds real value on top: it enumerates the returned fields and discloses the non-obvious quirk that view_level is deliberately omitted because the read API always reports "full". It does not mention auth or rate-limit behavior, so it is not exhaustive.

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-loads the purpose and the accepted identifier, then gives the return shape and the view_level caveat. The NOTE is slightly verbose but each clause carries information the agent would otherwise lack.

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 one-parameter read tool with annotations and an output schema, the description is close to complete: purpose, input shape, and behavioral caveat are all covered. The main omission is the type/mutual-exclusivity semantics of the identifier, though 'name or ID' largely addresses it.

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 0% and the single 'notebook' property is an undescribed string, but the description compensates by stating it 'Accepts a notebook name or ID' — a meaningful constraint the schema does not convey.

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?

States a specific verb+resource ('Get a notebook's sharing status') and tells the agent what the tool returns. It is clearly distinguishable from siblings like share_set_access and share_set_user, which mutate sharing rather than read it.

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 clear routing context: it explains that view_level cannot be read here and directs the agent to share_set_access for that value. It stops short of an explicit when-to-use/when-not statement versus the other share_* tools, but the intended context is unambiguous.

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

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

With no annotations, the description carries the full burden and does so richly: imports are asynchronous with typically 'processing'/'preparing' echoes, failures are flagged inline with status_label='error' plus a warning, remote file-adds return upload_required with two actor paths, private destinations are blocked, and wait semantics/timeout behavior are spelled out. This is far beyond what any structural field conveys.

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?

Long but well out-organized: the mode-selection rule is front-loaded, bold headers separate single vs batch, and bullets map inputs to source_type. It loses a point for embedded internal issue references (#1827, #1960) that add noise rather than agent-usable information.

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, yet the description explains the return shapes it can produce (source_wait aggregate with buckets and counts, a top-level source_id even on failure, the source echo with kind/status_label, and batch results with commit_state). For a 17-parameter, multi-mode tool this covers everything an agent needs 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 0% across 17 parameters, so the description must compensate, and it does for most: source_type, url, text, path, filename, document_id, mime_type, bytes_base64 (with format and size limits), wait/timeout/interval, title, and urls all get concrete semantics. A few (allow_internal, cleanup_on_failure's exact target) get only glancing treatment, leaving the full compensation slightly incomplete.

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?

States a specific verb and resource ('Add sources by notebook name or ID') and immediately enumerates the three operating modes (single, batch, in-channel bytes), so an agent knows exactly what the tool does before reading any schema. The mode taxonomy is precise enough that the tool is distinguishable from siblings like source_list or source_wait.

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?

Explicitly tells the agent to 'Choose ONE mode' and gives the selection rule for each ('pass source_type' vs 'pass urls'), plus exclusion rules ('Single-mode inputs and wait are invalid with urls'). It does not, however, address when to prefer this tool over the sibling source_add_drive_file or source_add_play_book, both of which overlap with modes described here.

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

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

No annotations are provided, so the description carries the full burden and delivers: server-side fetch using the profile's session, works on the remote (http) connector with no upload_required step, and asynchronous processing with wait=true / source_wait / source_list(status="error") for confirmation. Rich behavioral disclosure well beyond structured fields.

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 core action and supported types, then routing, then parameter details, then async behavior. Dense but every sentence earns its place; only slight verbosity in the parenthetical URL examples keeps it from a 5.

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?

An output schema exists so return values need not be explained. The description covers routing, error cases, parameter formats, and the asynchronous completion path — everything an agent needs to invoke this correctly against a rich sibling set.

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 0%, so the description must compensate and does: notebook accepts a name or ID, document_id accepts a Drive file id or share URL with explicit URL patterns (/d/<id>, /file/d/<id>/…, ?id=<id>), and wait=true blocks until READY. Only 'title' is left implicit, which is self-evident.

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?

States a specific verb and resource ('Add a Google Drive file by downloading it server-side and uploading it'), including the supported file types. It distinguishes itself from siblings source_add, source_add_play_book, and await_upload by naming exactly what it does that they don't.

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?

Explicitly routes the agent: Google-native Doc/Slides/Sheet aren't downloadable and return a pointer error → use source_add(source_type='drive', mime_type=…); use source_add(source_type='file') when bytes are held locally. Names when-not conditions and concrete alternatives.

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

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

With no annotations, the description carries the full burden and does well: it discloses that publisher-blocked titles are refused up front, that processing is asynchronous, that wait=true blocks until READY, and that the source reads back as expert_intelligence. Auth/permission requirements remain unstated, 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?

Front-loads the core action, then layers the id source, the exportability caveat, notebook handling, output type, and async/wait behavior without filler. Slightly dense, but each sentence earns its place.

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 an async mutation tool with an output schema, it covers the operational essentials an agent needs: id provenance, refusal condition, blocking behavior, and backend scope. Return value detail is correctly delegated to the 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 0%, so the description must compensate for all three params and does: content_id is a volume id from source_list_play_books, notebook accepts a name or ID, and wait=true blocks until READY. Every parameter gains meaning beyond the bare types.

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?

States a specific verb+resource ('Add a Google Play Book as a source by its content id') and qualifies it with the 'Expert Intelligence' type, which cleanly distinguishes it from source_add and source_add_drive_file. An agent can identify the operation without opening the schema.

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?

Routes the agent to source_list_play_books for obtaining the content_id and states the exportability prerequisite. It lacks an explicit 'use this instead of source_add_drive_file when...' exclusion, so it stops just short of the 5 tier.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing a preview/dry-run mode and the requirement to echo back the preview's canonical notebook_id and source ids. It does not state what exactly is destroyed or whether it is reversible.

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?

Three short, front-loaded sentences with no filler, leading with the verb and resource before the workflow detail. The telegraphic style is efficient, though the terse backtick notation risks ambiguity.

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?

An output schema exists, so return values need not be described. The preview/confirm flow is covered, but the `confirm` parameter goes unexplained and the notebook_id/notebook naming discrepancy leaves ambiguity for a destructive tool with 0% schema coverage.

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 0%, so the description must carry the full burden. It does explain the source XOR sources exclusivity and the omit-both preview mode, but it never mentions the `confirm` boolean parameter, and it refers to 'notebook_id' while the schema field is named `notebook`, creating a naming mismatch.

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?

States a specific verb and resource ('Delete sources'), which cleanly distinguishes it from siblings like source_read, source_rename, and source_add. It does not explicitly name a sibling, but the destructive delete intent is unambiguous.

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?

Describes the two-phase workflow clearly: omit both id parameters to get a preview, then supply them to confirm. This tells the agent when to call the tool in each mode. It stops short of naming alternative siblings or stating exclusions.

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

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

With readOnlyHint/destructiveHint already covered by annotations, the description goes further and explains a non-obvious behavior: drive_status_label is a separate axis that can show deleted/inaccessible/syncing while status_label stays "ready", meaning answers may be stale. It also flags that status=error returns a broken import's ghost row. It omits pagination behavior and any auth/rate-limit notes, keeping it short of 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?

Front-loaded with the one-sentence purpose, then organized by parameter/topic in short paragraphs. Dense but every sentence carries information; the inline code formatting makes it scan well without wasted preamble.

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?

An output schema exists, so return values need not be spelled out, yet the description still maps the detail modes to concrete field sets and explains the two status axes. The only real gap is pagination semantics for limit/offset, which leaves an agent guessing about result windows.

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 0%, so the description carries the burden. It explains ``detail`` (full vs compact and the exact fields returned), ``status`` (matching status_label with the error case), ``label`` (name or ID, composes with status), and that ``notebook`` accepts a name or ID. It says nothing about ``limit`` or ``offset``, leaving two of six parameters fully undocumented.

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?

States a specific verb and resource ("List a notebook's sources") and clarifies the key identifier accept (name or ID). It is instantly distinguishable from source_read/source_delete, but it never contrasts itself with the near-identical sibling source_list_play_books, so a small amount of sibling differentiation is missing.

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 by the listing purpose plus conditional hints ("Pass ``status`` to list only...", "Pass ``label``..."). However there is no explicit when-to-use/when-not guidance, no guidance on choosing between this and source_list_play_books or source_read, and no mention of pagination workflow.

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

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

Despite annotations already covering the safety profile (readOnlyHint/destructiveHint), the description adds substantial context: US-only/18+ eligibility, empty result for accounts with no library, web-backend-only constraint, and the semantics of export_disabled/reason (a non-exportable title cannot be added). This is genuinely useful behavioral detail beyond structured fields.

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?

Purpose is front-loaded in the first sentence, followed by eligibility constraints and a compact field list. Every sentence carries distinct information with no filler.

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?

Coverage of eligibility rules, gating fields, and the downstream tool is strong, and an output schema exists to carry return structure. The one gap is pagination behavior for limit/offset, which is undocumented in both the schema and the description.

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 0% and the two input parameters (limit, offset) are never mentioned in the description. Since coverage is below 50%, the description should compensate by explaining pagination, but it does not — it only describes output fields.

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 opens with a specific verb+resource ('List Google Play Books eligible to be added as sources') and scopes it to purchased ebooks NotebookLM can ingest. This clearly separates it from siblings like source_list (all sources) and source_read.

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?

It establishes the context of use (finding Play Books to add) and explicitly routes the agent forward: 'pass it to source_add_play_book'. There is no explicit when-not or comparison against source_list, but the downstream linkage makes the intended workflow clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description adds substantial behavior: content is ALWAYS bounded at 10,000 chars by default, char_count stays full length, content is null (char_count 0) when the source isn't ready, and markdown output needs the server's markdownify extra. These are non-obvious traits an agent needs to avoid misreading results.

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?

Long but front-loaded (the purpose is the first clause) and organized with bullets separating the two shapes. Density is justified by 6 parameters at 0% schema coverage, though a couple of parenthetical asides could be trimmed.

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 6-param tool with no output schema and no schema descriptions, the description covers return shapes, bounding/truncation, readiness edge cases, and the sibling routing. Nothing required to invoke it correctly is missing.

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 0%, so the description carries the full burden and does: it gives the exact return shape for each detail value, explains max_chars/offset as the slice [offset : offset+max_chars], notes offset is ignored for summary, and states notebook/source accept name or ID.

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?

States a specific verb+resource ('Read a source') and immediately scopes it with 'one of two detail levels,' which distinguishes it from source_list (listing), source_add (writing), and chat_ask (querying). An agent can separate it from every sibling without opening a schema.

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?

Explicitly routes on detail level ('summary' for low-token triage fan-out, 'full' for the body) and names the alternative for large sources: 'Prefer chat_ask for querying large sources rather than pulling the whole body.' This is when-to-use plus an explicit alternative.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not disclose permission requirements, whether the rename is in-place or destructive, error conditions, or any side effects. For a mutation tool this is a notable gap.

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?

Two short, front-loaded sentences with no wasted filler. It is efficient, though the brevity comes at the cost of substance rather than being paired with it.

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?

An output schema exists, so return values need not be explained, but with zero annotation coverage and 0% schema description coverage on a required 3-parameter mutation tool, the definition is too thin to call it complete.

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 0%, so the description must compensate, and it only partly does: "Accepts a notebook/source name or ID" clarifies the format of two of the three parameters. The required new_title is left entirely undefined, and no format or constraint details are given.

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?

States a specific verb and resource ("Rename a source"), which cleanly separates it from the sibling notebook_rename at the naming level. It does not, however, explicitly call out the distinction or scope, so an agent must infer the difference from the name alone.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as notebook_rename or studio_rename. The description gives no conditional context for selecting this tool over its many siblings.

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

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

Annotations only state readOnly/non-destructive; the description goes well beyond them by documenting that all modes return an identical aggregate shape so the caller never branches, that subset/all modes report partial progress, that a READY web-page may carry a non-blocking advisory `warning`, and the crucial distinction between an unresolved ref raising NOT_FOUND (input error) and a resolved source landing in failed/timed_out/not_found buckets.

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?

Purpose and mode rules are front-loaded in the first two lines, and the JSON return snippet compacts a lot of information efficiently. Some density (bold emphasis, inline code, multi-clause sentences about buckets) is heavier than needed, but each sentence carries distinct information.

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 no output schema and no annotation detail, the description fully absorbs that burden: it specifies the exact aggregate keys, per-bucket entry shape, the `ok` invariant, the partial-progress guarantee, the advisory-warning case, and the error taxonomy. An agent can interpret every return path without guessing; only timeout/interval tuning semantics remain unstated.

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 0%, so the description must carry the burden. It does explain the accepted forms of `sources` (list or comma/JSON string) and `source` (name or ID) and implies `notebook` semantics, which is the core of the tool. However, `timeout` and `interval` are completely unaddressed in both schema and description, leaving their units and retry behavior undefined.

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?

States a concrete verb and resource ('Wait for sources to finish processing') and immediately delineates the three operating modes (subset via `sources`, single via `source`, else all). It also points the agent at a sibling ('verify with source_read (detail="full")') for the one case where follow-up is needed, so it is not confused with source_read or source_list.

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?

The mode-selection rules ('waits for a subset when sources is given, a single source when source is given, else every source') are clear parameter guidance, but there is no explicit when-to-use/when-not versus alternatives such as polling with source_list or await_upload. The one sibling reference (source_read) is for verifying a warning, not for choosing between tools.

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

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

Annotations already declare destructiveHint=true, and the description adds substantial depth beyond them: irreversibility, the batch-confirmation requirement for full IDs, the batching-versus-per-item routing for text notes vs artifacts (including mind maps), the deleted/not_found response arrays, and the idempotent-success behavior for a missing single full ID. This is well beyond what the annotations convey.

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-loads the destructive scope and XOR constraint in the first line, then adds workflow and return behavior in short, information-dense sentences. No filler; every sentence carries a distinct constraint.

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?

An output schema exists, so return-value explanation is not required, yet the description still notes the deleted/not_found arrays as useful context. Combined with the XOR rule, preview/confirm workflow, routing behavior, and idempotency note, an agent has everything needed to invoke this destructive tool 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 coverage is 0%, so the description must carry the parameter burden, and it does for most: item XOR items with a 1-100 ref bound, the requirement to confirm with canonical notebook_id and item IDs, and the batch-confirmation constraint. The notebook parameter itself is only implied via 'resolve over Studio' rather than directly explained, leaving a minor gap.

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?

States a specific verb and resource ('Delete notes/artifacts irreversibly') and scopes it to Studio content, which separates it from the sibling source_delete and notebook_delete tools. An agent can identify the target domain without opening the schema.

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 workflow ('Preview first; confirm with canonical notebook_id and item ID(s)') and the item XOR items rule, which is actionable usage guidance. It does not explicitly name sibling alternatives (e.g., why studio_delete vs notebook_delete), but the scope of notes/artifacts makes the boundary reasonably clear.

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

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

With no annotations to lean on, the description carries the full behavioral burden and does so richly: it differentiates stdio (writes to required path) from the remote http connector (path ignored, returns a resource_link plus a signed short-lived URL, status=download_ready), notes inline bounded content for text kinds, and discloses that explicit artifact_id/output_format are validated up front rather than failing lazily.

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?

It is long, but the length is justified by genuine dual-transport complexity, and it is front-loaded with the core action before the targeting detail. Bullets and inline code keep it scannable; a little redundancy around the id-validation note could be trimmed.

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 6-parameter, no-annotation, no-output-schema tool, the description covers the gaps that structured fields leave: both transports, the return shapes, validation timing, and the full targeting contract. An agent can call this correctly without further context.

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 0%, so the description must compensate, and it largely does: it defines artifact as a name-or-id ref, artifact_type as a registry type with optional artifact_id, output_format as an override, and path as stdio-only. Only the required 'notebook' parameter is handled terse-ly, and the enum provenance is attributed to the live schema rather than enumerated here.

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 ('Download a generated artifact') and states the accepted identifier ('notebook name or ID'). It clearly establishes what the tool does, but does not explicitly contrast itself with siblings like studio_generate or studio_list (its only sibling reference, 'the other artifact_* tools', names tools not present in the sibling list).

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 strong, explicit guidance on the two mutually exclusive targeting modes ('exactly one' of artifact vs artifact_type), including the omit-artifact_id case for the latest artifact. It covers how to invoke but stops short of stating when to use this tool versus studio_status/studio_list alternatives.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses non-blocking async behavior, the task_id return, polling requirements, synchronous mind-map behavior with its return fields, and validation behavior for per-kind options.

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 well-structured with a front-loaded summary followed by a bullet-style breakdown of artifact types and their options. Given the large number of parameters and artifact kinds, the length is justified and every sentence adds needed clarity.

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?

Despite having an output schema, the description still covers the key async/sync behavior and return shapes needed to invoke the tool correctly. It also explains validation rules and complex source_ids formats, making it complete for this highly parameterized generation 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 description coverage is 0%, so the description must compensate. It documents all 18 parameters, including per-kind validity constraints, enum values for each artifact type, source_ids input formats, instructions, and language codes.

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 opens with a specific verb and resource: 'Start generating a studio artifact.' It clearly distinguishes the tool from its siblings by explaining that it returns a task_id for polling via studio_status, with mind-map as a synchronous exception.

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?

It gives clear context for use: start generation, then poll studio_status until is_complete is true, and notes the mind-map exception. It does not explicitly state when not to use this tool or point to other related siblings like studio_download or studio_list.

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

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

Annotations already establish the safe-read profile, and the description goes well beyond them: merged ``items`` shape, per-item fields, ``status_label``/``url`` on artifacts, pagination semantics (``total``/``offset``/``has_more``), null handling for unknown metadata, and the NOT_FOUND behavior on ``item``. It even discloses which parameters are silently ignored when ``item`` is supplied.

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 is front-loaded and the bulleted structure keeps the parameter semantics scannable rather than buried in prose. It is dense and runs long, but nearly every clause carries distinct operational information, so little is wasted.

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 6-parameter list tool with an output schema, the description supplies everything needed to call it correctly: parameter interactions, pagination, detail modes, and the one cross-tool handoff for artifact bodies. Nothing an agent needs is missing.

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 0%, so the description carries the full burden and does: ``notebook`` accepts name or ID, ``kind`` filters to one type, ``detail`` is defined as a three-rung ladder with per-mode fields, ``limit``/``offset`` define a bounded page, and ``item`` overrides the rest. This meaningfully exceeds anything inferable from the bare schema types.

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 opening sentence gives a specific verb and resource ("List a notebook's Studio panel") and immediately clarifies scope ("text notes AND generated artifacts"), which is the key distinction from artifacts-only or note-only siblings. An agent can tell this apart from studio_status and studio_download without opening a schema.

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?

It explicitly routes the agent elsewhere for one case ("read a report/data-table body via studio_download") and explains the single-item shortcut via ``item`` versus listing. However, it never contrasts this tool with close siblings like studio_status or notebook_describe, so the when-not-to-use picture is only partially drawn.

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

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 meaningful behavior: title-only mutation, type-based routing, note content preserved via a get-then-update, and note-backed mind maps routing back through the note system. It omits auth/permission requirements, error behavior, and whether the operation is idempotent.

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 core action in the first sentence, then structured detail about routing. The routing paragraph is long but earns its place by telling the agent it can pass any item without knowing its backing; a small amount of internal-RPC detail (e.g., the specific artifact type enumeration) could be trimmed.

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?

An output schema exists, yet the description still briefly summarizes the return (item_id/type/new_title/is_mind_map), and it fully covers the routing complexity an agent would otherwise have to infer. Missing only failure/permission semantics, which are minor for a title-only rename.

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 0%, so the description must compensate. It explains that 'notebook' accepts a name or ID and that 'item' is a name-or-id ref resolved over the merged notes+artifacts list, which is real meaning beyond the bare schema. Only 'new_title' is left to inference from 'title only'.

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 opens with a specific verb+resource+scope: 'Rename a Studio item (title only) — a text note OR an artifact.' That distinguishes it from the sibling notebook_rename and source_rename by naming the resource domain (Studio items: notes/artifacts) rather than notebooks or sources.

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?

It establishes clear context for use — a notebook name/ID plus an item ref resolved over the merged notes+artifacts list, mirroring studio_delete — and signals that callers need not know the item's backing. It does not explicitly say when to prefer this over notebook_rename or source_rename, so it stops short of full alternative routing.

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

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

No annotations are provided, so the description carries the full burden, and it does well: it discloses non-blocking asynchronous semantics, the return shape (task_id equal to artifact id, plus new status), the required polling step, and the failure modes. It omits idempotency/side-effect details and any auth or permission requirements, which keeps it short of 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?

Four tight sentences, front-loaded with the action, then the async contract, then the error case. No filler and every clause adds operational value.

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?

An output schema exists, so explaining return values is optional, yet the description nonetheless conveys the async contract and error behavior thoroughly. It falls slightly short on permission/rate-limit specifics and on what 'in place' means for the existing artifact state.

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 0% and the two params (notebook, artifact) are undocumented in the schema. The description compensates partially by stating both accept a 'notebook/artifact name or ID', but it does not clearly bind which param takes which name/id, leaving some ambiguity.

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?

Specific verb + resource with scope: 'Retry a failed Studio artifact in place', plus a mapping to the UI 'Retry' action. It clearly distinguishes itself from studio_generate (creates) and studio_status (polls) by naming the polling sibling explicitly.

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?

Tells the agent the precondition (a failed artifact) and the follow-up workflow: poll studio_status(notebook, task_id) until complete. Also notes that refusals (rate limit / quota / not-retryable) surface as synchronous errors. No explicit when-not guidance beyond 'not-retryable', but the context is clear.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false). The description adds real behavior beyond that: the tool is stateless, the url may be provisional, and the caller must gate on media_ready — none of which is derivable from the annotations or 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?

Three short sentences, front-loaded with purpose, then usage, then the output caveat. Every clause carries information the caller needs; nothing is padding.

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 polling tool with an output schema present, the description covers invocation (task_id source, notebook form) and the one non-obvious interpretation rule (provisional url vs media_ready). Nothing needed to call it correctly is missing.

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 0%, so the description must carry the load. It does most of it: notebook accepts a name or ID, and task_id comes from studio_generate. It could say more about format constraints, but both required params are given meaning.

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?

States a specific verb+resource ('Poll a generation task's status') and pairs it with the input form ('Accepts a notebook name or ID'). An agent can distinguish it from studio_generate, studio_retry, and studio_list without opening any schema.

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?

Explicitly tells the agent to pass the task_id from studio_generate and to poll until done, plus the condition for trusting the url. It does not name alternatives such as studio_list or studio_download, but the usage context is clear.

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

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 adds real behavioral context beyond that: what each surface produces, that source_ids scopes to specific sources with 'omit for all', and how the returned prompts are consumed. It stops short of noting rate limits or auth needs, but with annotations carrying the safety burden this is solid.

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 purpose and accepted input, then a bulleted list whose bullets each earn their place by defining an enum value. The closing 'Related' sentence is compact and adds routing value rather than padding.

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?

An output schema exists, so return values need not be spelled out, yet the definition still clarifies that each result is a ready-to-send instruction. Combined with full enum coverage, downstream routing, and the sibling alternative, nothing an agent needs to call this correctly is missing.

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 0%, so the description must carry the load and it does: it enumerates every enum value of 'surface' with a plain-language meaning, notes 'notebook' accepts a name or ID, explains source_ids as an optional scope, and describes query as an optional steering hint. This fully compensates for the empty schema descriptions.

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?

States a specific verb and resource ('Get AI-suggested, ready-to-send prompts for a studio surface') and immediately scopes it via the required notebook input. It distinguishes itself from the nearest sibling by contrasting with chat_ask(suggest_followups=true) at the end, so an agent can route without opening either schema.

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?

Explicitly tells the agent that each result is meant to be passed to chat_ask for the 'ask' surface or to studio_generate's 'instructions' for studio formats, giving concrete downstream usage. The 'Related' section names the inline alternative and the condition that selects it ('ask + follow-ups in one call' vs 'standalone selector across every surface').

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