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

Annotations already declare readOnlyHint=true / destructiveHint=false, and the description adds substantial behavior beyond them: in-process polling, resumable waits that survive a transport reset, a ~timeout bound, and the full status vocabulary with remediation for each state.

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 input, then a compact bulleted status table where each entry earns its place. It is slightly long, but the bulleted handling of each status prevents the length from becoming noise.

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, yet the description still maps each status to an agent action. Combined with the read-only annotations and the pending/retry semantics, an agent has everything needed to call and recover from this 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 carry both parameters. It thoroughly explains upload_link (source, accepted forms), but only alludes to timeout as '~timeout s' without stating units or the default of 45. Good but not full compensation.

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 uploaded... to land') and ties it to a precise workflow ('source_add(source_type="file")'). It is clearly distinguishable from siblings like source_add, source_wait and source_list because it names the link/token flow that produces its input.

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 tells the agent exactly what to pass (the human_upload.url or bare token from source_add) and prescribes per-outcome actions: re-invoke with the same link on pending, check source_list on unconfirmed, and mint a fresh link via source_add on expired.

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 the rejection condition, the absence of an unbounded history value, the conditional presence of suggested_prompts, and the citation detail levels. It does not mention permission/auth requirements or any rate limits, so a small gap remains.

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 and organized by parameter, with no filler sentences. The final suggest_followups paragraph is dense and slightly sprawling, and some return-value detail duplicates the output schema, but nearly every clause conveys non-obvious behavior.

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 7 parameters, 0% schema coverage, no annotations, and an existing output schema, the description covers all invocation-relevant details: defaults, mutual-exclusion rules, mode switching, and error conditions. An agent could call this correctly without further documentation.

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 every parameter: notebook (name or ID), source_ids formats and the comma-in-title caveat, history semantics and the lack of an 'all' value, question-omission behavior, and the exact fields returned by references=lite vs full.

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 names a concrete verb and resource ('Ask a notebook's sources a question, and/or recall prior turns') and states accepted identifiers, so the core operation is unambiguous. It does not, however, differentiate itself from siblings like suggest_prompts or chat_start, which overlap with the recall/follow-up modes described later.

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 when to pass conversation_id vs omit it, when source_ids scoping applies vs omitting to query every source, how history interacts with question (recall-only mode), and the failure case ('Pass neither and the call is rejected'). These are exactly the decision rules an agent needs before invoking.

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 substantial work: it discloses the cancellation ordering (local response stream abandoned first, then the Google session when present) and the task-ID rejection semantics. It stops short of stating idempotency or what happens when no active generation exists, so it is strong but 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?

The leading sentence gives the core action before any nuance, and the remaining sentences each add actionable detail rather than padding. The mid-sentence implementation aside about the local response stream is slightly verbose but justified by the ordering it explains.

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, and the description covers the cancellation path and error conditions adequately. Remaining gaps are minor: no statement of success semantics or idempotency for a repeated cancel.

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 two of three parameters: conversation_id's default to the most-recent session and task_id's origin in chat_start plus its rejection conditions. The required notebook parameter carries no explanation, 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?

The first sentence states a specific verb and resource ('Stop a notebook's active chat generation'), which immediately separates it from chat_start and chat_status in the sibling list. The follow-up sentences refine the scope by tying behavior to a specific session and task.

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 states the default for conversation_id and the condition under which task_id should be supplied ('when cancelling a detached ask'), plus the rejection rule for foreign/unknown IDs. It doesn't compare itself against research_cancel or say when the tool is unnecessary, but the primary selection context is covered.

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 disclosure burden. It explains that chat_mode replaces the whole block, custom fields merge with existing settings, and a bare call is rejected. It stops short of discussing persistence or permissions, but the key behavioral traits are well covered.

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 clear opening sentence and bullet-style explanation of configuration modes. Every sentence contributes to understanding behavior, with no filler or redundancy.

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 output schema exists, the description needn't document return values. It covers all parameters, required field, edge cases, and interaction rules, making it complete for a configuration 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?

The description adds substantial meaning to all four parameters beyond the schema, mapping notebook to name/ID, enumerating chat_mode and response_length values, and explaining goal's role as a custom persona. It clarifies interaction semantics (mutual exclusion, merging, rejection), which the schema alone does not convey. This fully compensates for the 0% schema description coverage.

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 clearly states the tool configures a notebook's chat behavior, using a specific verb and resource. It distinguishes itself from sibling chat_ask by focusing on configuration rather than querying. The two configuration modes add specificity.

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 provides detailed usage guidance through two mutually exclusive configuration paths, including what combinations are rejected and how partial calls merge. It implies when to use it (when needing to set chat behavior) though it doesn't explicitly name alternative tools. This is clear context.

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 and does so richly: the task runs server-side regardless of the call's fate, duplicate asks return already_running without double generation, a finished ask is never replayed and re-asking appends a new turn, and payloads stay pollable ~30 minutes before reporting unknown. This is exactly the lifecycle and side-effect information an agent needs and cannot get from 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 one-sentence purpose, then organized into a rationale paragraph and bulleted return states. It is long, but every section (timeout rationale, status semantics, poll window) carries information the agent needs given the absence of annotations, with minimal 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?

For a detached async tool this is nearly complete: it covers start, dedup, polling cadence, and payload expiry, and even describes return shapes despite an output schema existing. The one real gap is that the five input parameters remain semantically unexplained, which slightly undercuts completeness for invocation.

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 but largely does not. It only notes that parameters mirror chat_ask's ask path and that history/suggest_followups are chat_ask-only; it never explains notebook, question, references (the lite/full enum), source_ids, or conversation_id, leaving the agent to guess from the schema alone.

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 chat ask) plus the defining trait (detached background task, returns immediately). It explicitly separates itself from chat_ask (the one-call path) and chat_status (the collector), so an agent can choose correctly 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?

Gives an explicit when-to-use: generation that may run long, with the concrete trigger (1-3 min notebooks, ~60s transport silence killing a blocking chat_ask). It names the alternative and the condition that selects it ('for questions expected to answer quickly, chat_ask stays the one-call path'), then prescribes the follow-up (poll chat_status with task_id in ~20-30s).

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, and the description goes well beyond that: it discloses side-effect safety ('polling never restarts a generation'), result expiry under 'unknown', batch limits (64 ids), ordering guarantees, and timing fields returned on completion. This is the kind of behavioral context agents cannot infer 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?

Long but dense and front-loaded: the two modes are announced in the first sentence, then elaborated in labeled blocks with a status bullet list. Every sentence contributes either a decision rule, a format guarantee, or a constraint; there is 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?

An output schema exists so return values need not be re-explained, yet the description still maps each status value to its shape and follow-up action, and documents edge cases (expired results, input-order preservation, mode exclusivity). Nothing needed to call this tool 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: task_id accepts one id, a list, or a comma-separated string (a format the schema's anyOf does not convey), returns a bare dict vs. a {"tasks": [...]} wrapper depending on input shape, capped at 64. It also explains notebook vs. conversation_id, including the default-to-most-recent behavior of conversation_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?

The opening line states a specific verb pair ('poll' / 'inspect') mapped to two clearly named resources (detached asks, a notebook's live generation session). It explicitly distinguishes its two modes and positions itself against siblings like chat_start and chat_ask, which it names directly.

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 when-to-use guidance: re-invoke every ~20-30s while anything is pending, retry chat_start only for a retriable 'failed' code, start fresh on 'unknown'. It also states that the two modes are mutually exclusive and that polling never restarts a generation, removing the main ambiguity an agent would face.

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 burden of behavioral disclosure. It only says 'create a new notebook' without mentioning side effects, permissions, idempotency, or whether existing notebooks with the same title are allowed. This lacks critical behavioral context for an agent.

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 a single concise sentence that is front-loaded with the action and resource. No unnecessary words, making it highly efficient for an agent to parse.

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?

The tool is simple with one parameter and an output schema, so return values are covered by the schema. However, the description lacks behavioral context like error conditions, validation, or creation semantics (e.g., requires a workspace or handles duplicates). For a create operation, this is minimally sufficient but leaves gaps in operational 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?

The input schema has one required parameter 'title' (string), and the description merely restates 'with the given title'. This adds no meaning beyond the parameter name and type. For 0% schema description coverage, the description fails to provide additional semantic value such as title format, uniqueness, or constraints.

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 uses a specific verb 'Create' and resource 'notebook', clearly indicating the action. It distinguishes from siblings like notebook_list and notebook_rename by focusing on creation with a title.

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 no guidance on when to use this tool versus alternatives like notebook_rename or notebook_delete. It simply states the function without context on prerequisites, exclusions, or alternative 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds materially more: irreversibility, that the default call does NOT delete, that it returns a needs_confirmation preview of the resolved notebook, and the exact re-submission contract. This is the kind of behavioral detail an agent cannot infer from 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 destructive action and its irreversibility, then the confirmation protocol in two tight sentences. No filler; every sentence changes agent behavior.

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?

Complete for a two-parameter destructive tool: the safety profile, the irreversible consequence, the parameter semantics, and the confirmation workflow are all covered. An output schema exists, so return-value documentation is not required, and the description still notes the preview shape.

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% (both parameters are bare), so the description carries the full burden and does: it clarifies that notebook accepts a name or ID, and fully specifies confirm's two-state behavior including the default and the required follow-up value.

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") plus scope ("irreversible"), which cleanly separates it from the sibling notebook_list, notebook_describe, notebook_rename and notebook_create tools.

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 operational context: call with confirm=False first to get a preview, then re-submit the canonical notebook_id with confirm=True. It doesn't name a sibling alternative (e.g., when to rename vs delete), but the invocation guidance is explicit and 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?

Annotations already declare this as read-only (readOnlyHint=true, destructiveHint=false), and the description complements this by detailing the return structure (notebook_id, description, and optional metadata) and the effect of include_metadata. It does not contradict the annotations and adds context about output formatting. It doesn't cover error cases or rate limits, but for a read operation that's acceptable.

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 two sentences, starts with the core purpose, and every clause provides useful information. It avoids fluff and repetition, making it highly concise and well-structured.

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 tool's simplicity, the presence of an output schema, and supportive annotations, the description covers the main behavior, parameters, and return shape. It's sufficiently complete for an agent to invoke confidently, even without mentioning error scenarios.

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?

Although the schema has no parameter descriptions (0% coverage), the description fully compensates by explaining that 'notebook' accepts a name or ID and that 'include_metadata' controls whether metadata is included, with the default behavior unchanged. This adds meaning beyond the raw schema types, so it earns a high score.

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 uses a specific verb ('Fetch') and clearly identifies the resource ('a notebook's AI-generated description'). It also notes that it accepts a name or ID, which distinguishes it from notebook_list and other mutation siblings. No ambiguity about what the tool does.

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 does not explicitly state when to prefer this tool over alternatives or mention exclusions, but the purpose is clear enough that an agent can infer when to use it (whenever the AI description of a specific notebook is needed). It also explains how to optionally get metadata via include_metadata, which guides parameter usage. However, it lacks explicit when-to-use vs alternative statements, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavior beyond that: it reveals the bounded page nature, default values, and the pattern for forward pagination with offset/limit and has_more. This discloses the actual behavior without contradiction.

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 concise sentences, front-loaded with the core purpose and followed by pagination details. Field names are in backticks for clarity. No filler or redundant 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?

Given that this is a simple read-only list tool with an output schema, the description covers all essential aspects: what is listed, pagination mechanics, defaults, and the page-advance algorithm. Nothing substantive 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%—the schema only provides types and defaults. The description compensates fully by explaining what limit and offset do, including defaults (50, 0) and how to use them for paging (offset += limit). This gives the agent everything needed to pass parameters correctly.

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 uses a specific verb 'List' with a clear resource ('all notebooks') and specifies the returned fields (id + title + metadata). This clearly distinguishes it from sibling tools like notebook_describe (single notebook details) and mutation tools like notebook_create/delete/rename.

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 explicitly explains how to page through results using limit/offset and has_more, which is usage guidance. However, it does not explicitly state when to use this tool versus alternatives like notebook_describe or notebook_search, nor does it mention any exclusions. Clear context without alternative naming.

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?

The description does not disclose any behavioral traits beyond the action of renaming, which is also apparent from the tool name. It does not mention side effects, reversibility, permissions, or error conditions. With no annotations provided, the description carries the full burden of safety disclosure, and it fails to do so.

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 one short sentence, front-loaded with the primary action. It contains no filler or redundant information. Every word contributes to understanding the tool's purpose and key parameter behavior.

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 tool's low complexity and the presence of an output schema (which presumably documents return values), the description covers the essential usage. It states the action and the acceptable input format. However, it lacks context about error cases or whether the notebook must exist, but for a simple rename operation, it is reasonably 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?

The description partially compensates for the 0% schema coverage by clarifying that the 'notebook' parameter accepts a name or ID. However, it provides no additional meaning for 'new_title', leaving that to be inferred from the name. It adds value for one parameter but not the other.

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 clearly states the tool's function with a specific verb and resource: 'Rename a notebook.' This distinguishes it from sibling tools like notebook_create, notebook_delete, and notebook_describe. It also adds useful detail that it accepts a notebook name or ID, further clarifying its purpose.

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 provides no guidance on when to use this tool versus alternatives like source_rename or studio_rename. It does not mention prerequisites, exclusions, or context. The only hint is the tool name itself and the generic action, which is insufficient for an agent to decide between rename 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?

With no annotations provided, the description carries full responsibility. It discloses critical behaviors: create vs. update modes, required fields, status returns ('created'/'updated'), title-only rename, content-only body replacement, and the never-stray-create error policy. This is thorough and preempts common misuse.

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: a one-sentence purpose followed by a bulleted list of mode-specific rules. Every sentence adds value, with no filler. The formatting makes the create/update distinction easy to parse.

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 tool with no annotations and an output schema, the description covers the essential logic, required parameters, error behavior, and status returns. It does not explicitly state whether the notebook must already exist, but this is a minor gap given the level of detail provided.

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 has 0% description coverage, so the description is the sole source of parameter meaning. It explains that 'notebook' accepts a name or ID, 'note' governs mode, and 'title'/'content' have different requirements depending on mode. This fully compensates for the lack of 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?

The description clearly states the tool creates or updates a note (upsert) and accepts a notebook name or ID. The verb 'Create' and 'update' are specific, and the note resource is unambiguous. Although there are no sibling note tools, the description fully clarifies the tool's scope.

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 explicit usage guidance: mode is chosen solely by the 'note' parameter, with clear instructions for create (require title and content) and update (supply at least one of title/content). It also explains that an unresolved ref errors rather than creating. It does not compare to alternatives, but no alternative note-save tool exists.

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, but the tool is a zero-parameter read-only probe, so there is very little behavioral surface to disclose. The description confirms it is a non-mutating health check, but says nothing about failure semantics (e.g., what an unhealthy response looks like), which would be the only meaningful added 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?

A single front-loaded sentence with zero filler, appropriately sized for a trivial diagnostic tool. Every word 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?

With an output schema present, the return shape need not be described, and with no parameters there is little else to cover. The only gap is the absence of guidance on how this differs from server_info.

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?

The tool takes no parameters, so the baseline is 4. There is no parameter meaning for the description to clarify, and the empty schema is self-explanatory.

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?

"Health check for this wrapper server" states a specific diagnostic function and its target (the wrapper server), so an agent knows exactly what it does. It does not, however, distinguish itself from the sibling server_info, which an agent could reasonably mistake for the same purpose.

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: a health check is conventionally used to verify connectivity/liveness before other calls. No explicit when-to-use, when-not-to-use, or comparison against server_info is given, leaving the agent to infer the distinction.

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 rely on, the description fully discloses behavior: terminal-run behavior (cancel_requested: false, no RPC), non-terminal behavior (cancel_requested: true, run_status_before), replication-lag edge case, and fire-and-forget semantics. This is exceptional transparency.

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 concise yet comprehensive, organized into three short paragraphs: purpose, parameters, and behavioral details. Every sentence adds essential 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?

Given the tool's complexity and lack of annotations, the description covers all key aspects: what it does, required parameters, edge cases, return flag semantics, and next steps. An output schema exists, but the description still adds value by explaining the cancel_requested flag and statuses.

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 explain parameters. It does so thoroughly: notebook accepts name/ID, poll_task_id comes from research_start/research_status, and run_id is a deprecated alias. All three parameters are semantically covered.

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: 'Cancel an in-flight research run in a notebook.' This clearly distinguishes it from siblings like research_start and research_status, which are explicitly mentioned for 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?

The description states the main use case (cancel in-flight research) and gives a follow-up guideline: 'Fire-and-forget; poll research_status afterward to confirm.' It does not explicitly exclude alternatives, but the context and mention of related tools make usage 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 of behavioral disclosure. It does this well by explaining timeout tolerance ('reconciles what committed'), idempotency (duplicate URLs skipped as 'already_present'), the allow_duplicate re-add behavior, and the cited_only fallback. This goes beyond a simple 'import' statement.

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 compact yet information-dense. It front-loads the purpose in the first sentence, then organizes behavior into short paragraphs with clear inline code references. Every sentence adds useful context without unnecessary fluff.

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 tool's complexity (6 params, no annotations) and the presence of an output schema, the description is quite complete. It covers key behaviors, parameter origins, and edge-case handling. It could briefly mention error scenarios or what happens with invalid IDs, but the overall picture is solid.

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?

The schema has 0% description coverage, so the description must explain all parameters. It covers every parameter: notebook (name or ID), poll_task_id (source from research_start/research_status), task_id (deprecated alias), allow_duplicate (re-adds duplicates), cited_only (report-cited filtering with fallback), and max_sources (caps count). This is strong compensation for the lack of schema descriptions, though a bit more detail on max_sources and notebook resolution could push it higher.

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 clear, specific verb+resource: 'Import a completed research task's sources into the notebook.' It distinguishes this from sibling tools like research_start, research_status, and source_add by focusing on the import action and identifying the source of the poll_task_id.

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 states when to use the tool: after a research task is completed, using the poll_task_id from research_start/research_status. It also clarifies that task_id is deprecated. It does not explicitly list alternatives, but the context of importing research results makes the use case clear enough.

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, so description carries the burden. It discloses non-blocking behavior, the poll_task_id contract, and the deep web-only constraint. This goes beyond what schema reveals.

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 concise paragraphs, front-loaded with the main action, then workflow, then parameter options. Every sentence is informative.

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 async nature, it explains the full lifecycle: start, poll, import. Output schema exists, so return values aren't described in prose, but poll_task_id is mentioned. Minor omission of error/edge cases, but overall very usable.

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%, but the description explains notebook (name/ID), source (web/drive), mode (fast/deep) and the deep-is-web-only constraint. Query is implied by the tool's purpose, and parameter names are self-explanatory.

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?

Cleary states the tool starts a research session in a notebook, and distinguishes from siblings by referencing the follow-up tools (research_status, research_import, research_cancel). It has a specific verb and resource.

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 clear workflow guidance: poll research_status until completed, then research_import. It also explains source/mode options and the deep web-only constraint. Slight lack of explicit when-not-to-use, but context is strong.

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 declare only readOnlyHint=true/destructiveHint=false, but the description adds substantial behavior: the status enum, termination_reason sub-classification of failed, the not_found result for an unmatched pin, report omission/truncation rules, and pagination of sources. Well beyond what annotations provide.

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 organized into short paragraphs covering returns, report fields, pagination, and pinning. Dense and mostly waste-free, though the back-reference overload of inline ``code`` terms makes it slightly heavier than needed.

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 notable return fields and workflow linkage, leaving nothing an agent needs in order to call this correctly or interpret the result. Complete for a 7-param status tool with no schema descriptions.

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 it does: poll_task_id pinning semantics and not_found outcome, source_limit/source_offset paging, include_report and report_max_chars behavior, notebook accepting name or ID, and task_id flagged as a deprecated alias with a removal version. Nearly every one of the 7 params gains meaning absent from 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 ('Check a notebook's research status') and immediately names the accepted identifier ('a notebook name or ID'). The polling workflow and the handoff to research_import distinguish it from siblings research_start, research_cancel, and research_import without ambiguity.

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 operating loop ('Poll until completed, then pass poll_task_id to research_import') plus the condition selecting the pinned variant ('poll_task_id ... pins one of several in-flight tasks; omit for a single task'). This is concrete when/when-not guidance tied to a named 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?

Annotations already declare readOnlyHint/destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavioral facts — the default call is 'fast, network-free,' the account block needs a live session, and stale sessions degrade to `{available: False, reason: ...}` rather than failing the call. Much of the remaining text narrates return fields that the output schema already carries, which keeps it out of the top tier.

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 front-loaded with the purpose and organized into clear blocks, so the structure is good, but it is long for a one-parameter read tool whose return shape is already captured by an output schema. The multi-clause enumeration of `auth` and `account` fields, plus the closing justification paragraph, is information the agent can largely get from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An agent has everything needed: when to call it, what the default (network-free) call returns, how to opt into the account block, and how failures degrade. Since an output schema exists, the return-value detail is bonus rather than necessity, making this more than complete for the tool's complexity.

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 lone `include_account` boolean, so the description must compensate, and it does: it states exactly what setting it true fetches, that the block is off by default, and why (quota fields require a live session). No ambiguity remains about the parameter's effect or default.

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 dual resource — 'Report the server version and local authentication health' — which is far more precise than a tautology. It also implicitly separates itself from siblings like `ping` by framing itself as the pre-flight auth/health check. The only gap is that it never explicitly names a sibling it is distinct from, so it misses the top tier.

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 guidance tied to concrete siblings: check `chat_tasks` load before submitting a `chat_start` batch, and call this to confirm login 'before driving notebook tools.' It even prescribes the fallback action ('run `notebooklm login` on the server host') when `authenticated` is false, leaving nothing to inference.

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 declare destructiveHint=true, and the description adds genuinely non-obvious behavior: with the default confirm=False it does NOT mutate and returns a preview, and the mutation requires re-submitting the canonical notebook_id and verbatim email. This is exactly the kind of safety-critical detail annotations cannot 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?

Purpose is front-loaded in one sentence, followed by the confirm workflow. Every sentence earns its place, with only the 'canonical notebook_id' phrasing being slightly implementation-specific.

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 described. Purpose, the two-step confirm flow, and per-parameter meaning are all covered; minor gaps remain (permission requirements, not-found behavior), but the definition is complete enough to invoke 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%, so the description carries the burden and does so well: notebook accepts a name or ID, email must be verbatim, and confirm is the mutation gate defaulting to false. It adds real meaning beyond the bare string/boolean 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 ('remove') and resource ('a user's access to a notebook'), which naturally contrasts with the sibling share_set_user/share_set_access that grant access. It does not name the counterpart sibling explicitly, but the verb alone is enough to distinguish 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?

Explains the confirm-gated workflow clearly: call with confirm=False to preview, then re-submit with confirm=True to mutate. This tells the agent how to use the tool, though it does not explicitly route to alternatives (e.g., share_set_user for granting access).

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 the confirmation gating for widening, that restricting/view_level are ungated, the application ordering (view_level before public) chosen to 'fail closed' on partial failure, and what is returned.

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 purpose, then layers parameter meaning and gating behavior in dense but non-wasteful sentences. Every sentence carries actionable signal with no 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 mutation tool with no annotations and 0% schema coverage, the description compensates thoroughly, and the return content is mentioned though an output schema already exists. Nothing needed to invoke it correctly appears 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?

Despite 0% schema coverage, the description explains all meaningful parameters: notebook (name or ID), public (True=anyone-with-link, False=restricted), view_level (full/chat), and the confirmation flow for confirm. The tie of the boolean 'confirm' to re-invoking with the canonical notebook_id is slightly implicit rather than explicit.

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: 'Set a notebook's link-access settings.' This distinguishes it from the per-user sibling share_set_user by scoping to link-access rather than individual user shares, and it notes it accepts a notebook name or ID.

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 conditional guidance: widening via public=True returns a needs_confirmation preview requiring a confirm, while restricting and view_level changes are not gated. It does not explicitly contrast with the share_set_user sibling, so it falls short of full when/alternatives coverage.

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: it discloses that this is an upsert, that notify/message broadcast to all grantees, and that it returns updated sharing status. It never states whether the grants list replaces the existing share set or merges with it, nor any permission/auth requirements, which are exactly the traits an agent needs for a sharing mutation.

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 semantics and the parameter-shape disjunction are front-loaded, and the sentences are dense without filler. The 'confirm with its canonical notebook_id' clause is slightly cryptic and interrupts the otherwise clean structure.

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 are covered elsewhere and the description is right to only summarize them. For a 7-parameter mutation tool with zero annotation and zero schema-description coverage, though, missing auth/permission requirements and replace-vs-merge behavior leaves a meaningful 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 must compensate and largely does: it explains email+permission, the grants structure [{email, permission}] with its 1-100 bound, that notify and message apply to all grantees, and that the notebook is referenced by its canonical notebook_id. The confirm flag's exact semantics remain only indirectly implied, keeping it short of a 5.

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 (upsert) and resource (access) and spells out the two mutually exclusive input shapes: single email+permission or a 1-100 grants array. It does not distinguish itself from the near-identical sibling share_set_access, leaving an agent to guess which of the two to pick.

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 implies a preview-then-confirm workflow ('Preview lists every grant; confirm with its canonical notebook_id') and notes that batches allow mixed permissions, which gives some usage context. However, there is no explicit when-to-use/when-not guidance and no routing to share_set_access or share_remove_user, so the agent must infer the choice.

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=true and destructiveHint=false annotations, the safety profile is already known. The description adds valuable context: it discloses the exact return fields, clarifies that permission/access are string labels, and importantly explains that view_level is intentionally omitted due to API behavior. This goes beyond what annotations alone provide.

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 concise and well-structured. It leads with the primary action, lists the return fields in a clear format, and adds a note about view_level that is critical for avoiding confusion. Every sentence earns its place with no redundancy.

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 read tool with one parameter, an output schema, and clear annotations, the description is complete. It covers the return structure, the key omission (view_level), and provides cross-reference to the setter tool. The description fully supports correct invocation without unnecessary elaboration.

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?

The input schema has 0% parameter description coverage, but the description compensates by stating that the notebook parameter 'accepts a notebook name or ID.' This gives the agent the key semantic information needed to provide a valid argument, though it could add more detail about format or validation.

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 clearly states the tool's function: 'Get a notebook's sharing status.' This is a specific verb+resource combination that distinguishes it from sibling tools like share_set_access, share_set_user, and share_remove_user, which modify 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?

The description implies usage context by positioning this as a read operation and explicitly notes that view_level is not returned and should be set via share_set_access. This provides a clear alternative for a related action, though it does not explicitly state 'use this tool when you need to read sharing status' as a standalone guideline.

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: it discloses asynchronous import semantics and the usually-processing echo, the upload_required/signed-URL branch for remote file adds, base64 size limits (<=10,000 chars vs 200 MiB), title-override failure signaling (#1960), inline error/warning flags, thin-text soft-404 detection, and that private fetch destinations are blocked.

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 'Choose ONE mode' framing with bold mode headers front-loads the decision and makes a dense 17-parameter tool navigable. It is long and occasionally stacks parenthetical caveats, but for this branching complexity nearly every sentence carries necessary information, so the size is mostly earned.

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 a highly complex tool with 17 parameters, zero schema description coverage and no annotations or output schema, the description covers inputs, mode selection, return shapes (source_wait aggregate, results[i] with commit_state) and failure handling. An agent has everything needed to invoke 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%, so the description must compensate for all 17 parameters, and it effectively does: it maps source_type values to their required inputs, explains path/bytes_base64 as alternatives, documents mime_type's enum and the no-default rationale (#1827), and covers filename, title, wait, timeout/interval, urls, fallback_fetch, cleanup_on_failure and allow_internal. This is far beyond the schema's bare names.

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 concrete verb+resource ('Add sources by notebook name or ID') and enumerates the three modes, so the agent knows exactly what the tool does. However it never differentiates itself from siblings like source_add_drive_file or source_add_play_book, and it even overlaps the former by accepting source_type='drive', leaving that routing ambiguity unresolved.

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?

Guidance on when each mode applies is explicit and includes exclusions ('wait is single-mode only', 'Single-mode inputs and wait are invalid with urls', 'Batch is URL-only'). What it lacks is routing advice relative to alternative sibling tools, so an agent choosing between this and source_add_drive_file gets no help.

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 server-side fetching with the profile's session, that it works on the http connector without an upload_required step, asynchronous processing, and the wait=true blocking option with source_wait/source_list fallbacks. It stops short of stating auth requirements, size limits, or failure semantics beyond the pointer error, so not a full 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 core action, then routing, then parameter/async details across three tight paragraphs. Every sentence carries signal, though the routing paragraph is dense enough that it could be trimmed slightly.

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 described. Given that, the description covers the action, the routing alternatives, the accepted identifier formats, and the async/wait lifecycle — everything needed to invoke 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%, so the description must compensate, and it does for 3 of 4 params: notebook (name or ID), document_id (file id or share URL, with concrete /d/<id>, /file/d/<id>, ?id= patterns), and wait (block until READY). The 'title' parameter is never mentioned, 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+resource with mechanism: 'Add a Google Drive file by downloading it server-side and uploading it'. It also enumerates supported formats and clearly distinguishes itself from source_add(source_type='drive') and source_add(source_type='file'), which is exactly the sibling disambiguation an agent needs.

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 rules: use source_add(source_type='drive') for Google-native Docs/Slides/Sheets (or a Drive PDF by reference), and source_add(source_type='file') when the bytes are held locally. When-to-use and when-to-use-something-else are both spelled out.

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: publisher-blocked titles rejected, resulting source type (expert_intelligence), asynchronous processing, wait=true blocking until READY, and the web-backend-only restriction. These are exactly the operational facts an agent needs before invoking.

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 required id are front-loaded in sentence one, with prerequisite, refusal guardrail, source type, async behavior and backend limit following in tight order. No sentence is redundant.

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 payloads need not be described, and the description still notes the read-back type. Between the id prerequisite, publisher-block refusal, async/wait semantics and backend limitation, 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 coverage is 0%, yet all three parameters are explained in prose: content_id is a volume id sourced from source_list_play_books, notebook accepts either a name or an ID, and wait blocks until the source reaches READY. 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?

The first sentence gives a precise verb+resource+discriminator: adding a Google Play Book as a source, identified by content id, resulting in an expert_intelligence source. This clearly separates it from the generic source_add and from source_add_drive_file among the 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?

The description routes the agent to the prerequisite sibling by stating content_id 'is a volume id from source_list_play_books', and adds a guardrail that publisher-blocked titles are refused up front. It does not explicitly contrast with the generic source_add or say when this tool is the wrong choice, so it stops short of full when/when-not 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?

Annotations declare destructiveHint=true, so safety is covered. The description adds genuine behavioral value beyond that: the two-phase preview-then-confirm pattern, the XOR constraint between source and sources, and the requirement to use the preview's canonical notebook_id, which guards against confirming on stale data.

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 tight sentences with the core action front-loaded ('Delete sources'). The preview/confirm guidance is dense but earns its place; the RST-style double backticks add minor noise without bloat.

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 destructive tool with annotation coverage and an existing output schema, the description supplies the essential missing context: the preview/confirm safety workflow and the parameter exclusivity rule. An agent has enough to invoke it correctly without explaining return values.

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 explain the key semantics: source XOR sources (mutual exclusivity), omit both for preview, and the need for canonical notebook_id plus source id(s) to confirm. The confirm boolean itself is only implied rather than named, 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 ('Delete sources'), clearly distinguishing it from siblings like source_add, source_rename, and source_read. It does not explicitly name an alternative, but the delete action 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?

Gives a clear operational workflow: omit both parameters to preview, then confirm with the preview's canonical notebook_id and source id(s). This tells the agent when it is in preview vs. destructive mode, though it does not reference sibling tools as 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?

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description goes beyond that with a genuinely useful caveat: drive_status_label is a separate axis and can read deleted/inaccessible/syncing while status_label stays 'ready', meaning answers may be stale. Pagination behavior (limit/offset) is not disclosed.

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 content is dense but organized into clearly front-loaded paragraphs by parameter, and each sentence adds distinct information (mode semantics, staleness caveat, filter composition). It is longer than a one-liner but earns most of its length.

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 shapes need not be re-explained, yet the description still clarifies the meaning of key fields like kind and the two status labels. What remains missing is pagination guidance for limit/offset.

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 for four of six parameters: notebook (name or ID), detail (full vs compact field lists), status (with the 'error' = ghost-row meaning), and label. It leaves limit and offset pagination entirely 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') plus the accepted identifier form. It does not explicitly distinguish itself from the sibling source_list_play_books, leaving the agent to infer that this returns all sources rather than only play books.

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 semantics of the detail, status, and label filters and notes that status and label compose, which is real usage guidance. However, it never routes the agent between this tool and its alternatives (e.g. source_read for content, source_list_play_books for a subset), so when-to-use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond that: US-only, 18+ eligibility, that export_disabled/non-exportable titles cannot be added, empty result for no library, and web-backend-only. It omits pagination/rate behavior but otherwise goes well beyond 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?

Front-loaded with purpose and eligibility, then the return fields and the follow-up action. Dense and information-rich with no filler; every clause (US only, 18+, export_disabled/reason, empty case) 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?

An output schema exists, so return-value detail is technically redundant, yet the description still names the row fields, which helps the agent chain to source_add_play_book. The only gap is the unexplained limit/offset parameters, which is minor for a standard paginated list.

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 description never mentions limit or offset. Both are standard pagination parameters an agent can infer, but with zero schema documentation and no compensating text, the definition does nothing to clarify their semantics or defaults.

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 ('List') + precise resource ('Google Play Books eligible to be added as sources'), with the NotebookLM/Expert Intelligence scope named. An agent can distinguish it from source_list (lists existing sources) and source_add_play_book (the follow-up action) 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?

The description establishes clear context: this is the discovery step whose content_id feeds source_add_play_book, and it names that sibling explicitly. It doesn't spell out an explicit 'when not to use' or the full prerequisite chain, but the intended workflow 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), yet the description adds substantial beyond-schema behavior: content is always bounded at 10,000 chars by default, max_chars/offset page as a slice while char_count stays the full length, content is null when the source isn't ready, and output_format=markdown requires the server's markdownify extra. That is far more than the annotations provide; only the return of errors/failure modes is left 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 with the verb and resource, then organized by parameter with the default marked inline. Dense and slightly repetitive ('bounded'/'caps'/'page'), but essentially every sentence carries operational information an agent needs.

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?

No output schema exists, and the description compensates by specifying the exact return shape for both detail levels, including field names, the truncation flag, and the null/zero-char case. For a 6-parameter read tool, 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 description coverage is 0% and there are 6 parameters, so the description must carry the load, and it does for four of them: detail's two return shapes, max_chars' 10k default cap, offset's slice semantics, and output_format's markdownify dependency and restriction to detail=full. The required notebook/source params get only 'accepts a notebook/source name or ID', which is thin but adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb (read) and resource (source) and immediately scopes it to two named detail levels. It also declares the accepted identifier forms (notebook/source name or ID), so an agent can distinguish it from source_list, source_wait, and chat_ask 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?

Explicit routing guidance: summary is for cheap low-token triage across many sources, full is the default for actual content, and the description closes with 'Prefer chat_ask for querying large sources rather than pulling the whole body' — a named alternative plus the condition that selects it.

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 burden of disclosing effects. It states the core rename action but doesn't mention consequences like whether old references are updated, permission requirements, or reversibility—significant gaps 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?

The description is a single, compact sentence that includes both the action and identifier semantics. It earns its place, though the phrase 'notebook/source name or ID' is structurally unclear and could be rephrased for better readability.

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 rename tool with no annotations and incomplete parameter descriptions, the overall context is insufficient. The agent knows what the tool does but lacks the behavioral and usage context needed to invoke it confidently in varied situations.

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. The phrase 'Accepts a notebook/source name or ID' adds partial meaning for identifying the source/notebook, but new_title is left undescribed, and the exact relationship between notebook and source is unclear.

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 action ('Rename a source') with a clear resource, distinguishing it from sibling tools like source_delete or notebook_rename. The verb and object are unambiguous, even if the subsequent identifier phrase is slightly awkward.

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 offers no guidance on when to use this tool versus alternatives, such as source_add or notebook_rename. It neither specifies prerequisites nor mentions exclusions, leaving the agent to infer usage from the tool name alone.

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?

Even with readOnlyHint=true and destructiveHint=false, the description adds substantial behavior beyond annotations: it discloses the exact aggregate return shape, the meaning of 'ok', the contents of error buckets, partial progress semantics, warning behavior for web pages, and the distinction between input errors (NOT_FOUND before wait) and backend-reported failures. This is rich, non-obvious behavior that annotations alone do 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?

The description is organized into clear paragraphs, front-loads the purpose, uses a code block for the output schema, and every sentence adds critical detail (return shape, partial progress, warnings, error semantics). It is dense but not verbose; all content earns its place given the tool's complexity.

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, the description fully specifies the return value (aggregate keys, buckets, counts, ok flag), explains all three input modes, and covers edge cases (unresolved refs, partial progress, advisory warnings). It also references source_read for additional verification. The only minor omission is explicit units for timeout/interval, but this does not undermine overall completeness for an agent.

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 does explain 'sources' (list or comma/JSON string), 'source' (name or ID), and 'notebook' (name or ID). However, 'timeout' and 'interval' are not explained at all—units and semantics are left to inference from their names and defaults. With 5 parameters and 0% schema help, this partial coverage leaves gaps, but the description does meaningfully clarify the core selector parameters.

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: "Wait for sources to finish processing." It clearly identifies the operation and distinguishes it from sibling tools like source_read (which reads content) and source_list (which lists sources). The scope (notebook name or ID) and three waiting modes are all laid out, making the purpose unmistakable.

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 when to use the tool (waiting for sources to finish processing) and details the three modes (sources, source, all), which guides selection. It also provides an exclusion: when a READY web-page entry has a warning, the agent should not trust it unconditionally and instead "verify with source_read (detail='full')" — an explicit alternative for that sub-case. This is strong usage 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?

Annotations already declare destructiveHint=true, but the description goes well beyond them: irreversible deletion, the 1–100 ref batching limit, per-kind routing (text notes batch; artifacts and mind maps route individually), the returned 'deleted'/'not_found' arrays, and the idempotent-success rule for an absent single ID. These are exactly the traits an agent needs before committing a destructive write.

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 delete-and-irreversibility warning, and nearly every clause carries operational weight (XOR rule, batch limits, routing, return shape, idempotency). The telegraphic 'Names/IDs resolve over Studio' sentence is the only fragment that costs a little clarity for compactness.

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 usefully summarizes the batch return shape. Combined with annotations covering safety and the description covering ref limits, routing-by-kind, and idempotency, an agent has everything needed to call 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 description coverage is 0%, so the description must carry the load and largely does: it explains the item XOR items mutual exclusion, the 1–100 reference cap, the meaning of canonical notebook_id and full item IDs, and the confirm flag's requirement of full IDs for batches. Remaining ambiguity is minor (e.g., what 'confirm' defaults to, name-vs-ID resolution failure modes).

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') with the critical scope qualifier 'irreversibly'. The item-XOR-items constraint immediately signals this is the single deletion path for Studio content, distinguishing it from sibling mutation tools like studio_rename, studio_retry, and studio_generate.

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 real operating procedure: 'Preview first; confirm with canonical notebook_id and item ID(s)' plus the batch rule that confirmation requires full IDs. It stops short of naming the preview/list sibling tool explicitly, so the agent must infer the preview step rather than being routed to it.

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 this description carries the full burden and does so richly: it discloses transport-dependent behavior (stdio writes to required path; remote returns a resource_link plus a short-lived signed URL and ignores path), inline text bodies with bounded content/char_count/truncated, and up-front validation of an explicit artifact_id/output_format. These are exactly the behavioral traits structured fields do not provide.

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 action and then uses two tight bullets plus compact paragraphs; every sentence conveys a distinct fact. It runs a little long for a download tool and the transport paragraph is dense, but nothing is redundant 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 six-parameter tool with no annotations and no output schema, the description covers input targeting, transport-dependent return shapes, and validation behavior, leaving no essential gap for an agent 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 coverage is 0%, so the description must compensate and it does: notebook (name or ID), artifact (name-or-id ref resolving to type+id), artifact_type with optional artifact_id (full or unique-prefix), output_format as an override, and path as required over stdio but ignored remotely. It also points the reader to the schema enums for type/format, covering all six parameters.

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 names the required notebook scope, so the purpose is unambiguous against generate/list/status/delete siblings. It references sibling conventions ('the form the other artifact_* tools take') but never contrasts its purpose with those tools directly, so it stops short of full sibling differentiation.

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?

Strong guidance on target selection: exactly one of artifact vs artifact_type (with optional artifact_id), and when to omit artifact_id for the latest artifact. What is missing is explicit when-to-use versus alternatives such as studio_list or studio_status to find an artifact first, so it is clear context without 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 no annotations, the description carries full burden and does so thoroughly: non-blocking behavior, task_id, synchronous exception for mind-map, validation errors, default behavior, and source_ids input formats. It sets clear expectations beyond 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?

The description is long but every segment adds necessary detail for an 18-parameter tool. It is structured with a clear initial statement, a notable behavioral note, and a bulleted artifact-type breakdown, making it scannable despite length.

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 tool's complexity and the presence of an output schema, the description still adds essential return-value context (task_id, mind_map, mind_map_id), error semantics, and per-type options. It is complete for effective invocation.

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%, but the description compensates comprehensively. It explains each artifact_type's associated options, defaults, relationships, and even source_ids format variations (list, JSON string, comma-separated). This adds far more meaning than 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?

The description opens with 'Start generating a studio artifact', a specific verb+resource statement that immediately distinguishes this tool from siblings like studio_status or studio_list. It also lists ten artifact types, reinforcing its scope.

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 explicit usage flow: non-blocking returns task_id, poll studio_status until complete. Notes synchronous exception for mind-map, and warns that per-kind options are invalid for other artifact types. This is clear when-to-use and when-not-to-use 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?

Annotations only cover the safety profile (readOnlyHint/destructiveHint), while the description adds substantial behavioral context: the merged items shape, the detail ladder semantics, that item mode ignores limit/offset/detail, that no match is NOT_FOUND rather than empty, and that unknown metadata/counts return null.

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 purpose, then organizes the ladders and modes into bullets. Dense but every sentence carries operational detail; minor redundancy in the overlapping descriptions of detail and item behavior 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?

For a 6-parameter listing tool with an output schema, the description still covers the important edge cases an agent needs (item-resolution semantics, ignored params, NOT_FOUND behavior, null metadata) and routes body reading elsewhere. 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 carries the full burden and does so: it documents detail levels (summary/full/compact with their exact output), kind as a single-type filter, limit/offset pagination, and item accepting a name or id. Every parameter gains 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?

States a specific verb and resource ('List a notebook's Studio panel') and clarifies scope precisely: both text notes and generated artifacts. This distinguishes it from siblings like studio_status, studio_download, and note_save without needing to open 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?

Routes the agent explicitly: read a report/data-table body via studio_download, and describes when to use the 'item' fetch mode versus the merged list. It has clear contextual guidance but does not draw an explicit boundary against studio_status or source_list, so it falls just 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 provided, the description fully carries the transparency burden. It discloses routing by resolved type (note vs. artifact), the get-then-update mechanism for notes, the artifact rename RPC for all artifact types, the mind-map special case, and the exact return fields (item_id, type, new_title, is_mind_map). This is highly detailed and goes well beyond minimal safety hints.

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 dense but every sentence adds value: purpose, parameter semantics, routing logic, and return values. The main purpose is front-loaded, and there is no filler or repetition of schema 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?

Given the tool's complexity (mixed note/artifact types, routing by type, mind-map special case), the description is complete. It covers all three parameters, the resolution rule, the different backing types, and the return values. The presence of an output schema does not create gaps because the description already explains the output shape.

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 does so thoroughly: notebook is described as accepting a name or ID, item is described as a name-or-id ref resolved over the merged notes+artifacts list, and new_title is clarified by the 'title only' constraint. The routing logic further explains how the item parameter is interpreted.

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 'Rename a Studio item (title only) — a text note OR an artifact,' which clearly identifies the verb (rename), the resource (Studio item), and the scope (title only). It distinguishes the tool from siblings like studio_delete and studio_list by focusing specifically on the rename operation.

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 when to use the tool (renaming any Studio item regardless of its backing type) and references studio_delete for the ref resolution pattern, but it does not explicitly state when not to use it or list alternative tools for similar operations. This is clear context but lacks explicit 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 no annotations, the description fully carries the burden and does an excellent job: discloses non-blocking behavior, return values (task_id, status), that task_id equals artifact id, the need to poll studio_status, and synchronous refusal conditions (rate limit/quota/not-retryable). This exceeds typical transparency expectations.

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 tight paragraphs front-load the purpose and then efficiently pack behavioral details, return values, and error handling into compact, high-value sentences. No filler or repetition.

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 tool with two params, no annotations, and an output schema, the description covers purpose, behavior, return values, polling strategy, and error cases. It provides agents with enough operational detail to invoke and follow up correctly, making it functionally 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 has zero description coverage, but the description states 'Accepts a notebook/artifact name or ID', clarifying that both parameters accept either a name or ID. This adds meaningful semantics beyond the bare string type, though it does not elaborate on what constitutes a notebook or artifact in this context.

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?

Description opens with 'Retry a failed Studio artifact in place', a specific verb+resource that clearly identifies the action and scope. It explicitly references the UI 'Retry' action and distinguishes itself from sibling tools like studio_generate by focusing on retrying existing failed artifacts.

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 clear context for when to use (retrying a failed artifact) and instructs polling via studio_status after acceptance. It does not explicitly state when not to use the tool or name alternative tools for regeneration, 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?

The description adds substantial behavioral context beyond the readOnlyHint/destructiveHint annotations: statelessness, polling lifecycle, return fields, and the critical caveat that a pending URL is provisional until media_ready. No contradiction with annotations exists.

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 with no filler. The purpose is front-loaded, and every sentence adds operational value, including return fields and the provisional URL caveat.

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?

The description fully covers the polling workflow, status fields, trust caveat, and producer relationship. With an output schema present and read-only annotations, no significant gaps remain.

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%, but the description compensates by explaining that notebook accepts a name or ID and that task_id comes from studio_generate. This gives meaningful semantic meaning to both parameters, though it leaves some type/format details to 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?

The description uses a specific verb ('Poll') and clearly identifies the resource ('a generation task's status'), explicitly scoping it to generation tasks and referencing studio_generate. This distinguishes it from sibling status tools like research_status or share_status.

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 tells the agent to pass the task_id from studio_generate and to poll until done, establishing a clear usage context. It does not explicitly name alternatives or exclusions, but the producer relationship and polling pattern are sufficient 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond that: results are 'ready-to-send,' they can be passed to specific generators, and source_ids/query affect the output. This goes beyond a bare read-only declaration, though it does not discuss auth or rate limits.

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 clear opening, a bulleted list for surface options, and a related-tools note. It is longer than average but every sentence adds necessary detail; nothing is redundant.

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?

The tool has rich schema (9 enum values), an output schema, and multiple parameters. The description covers the purpose, parameter meanings, output usage, and a key alternative, providing complete context for correct invocation.

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 full responsibility. It explains every parameter: notebook accepts a name or ID, surface has a default and detailed meanings for each enum, source_ids scopes to specific sources (with 'omit for all'), and query steers suggestions. This fully compensates for the missing 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?

The description starts with a specific verb and resource: 'Get AI-suggested, ready-to-send prompts for a studio surface.' It clearly distinguishes this tool from siblings by framing it as the standalone selector across every surface, and by listing specific surfaces (ask, audio formats, video formats, quiz/flashcards) and matching generators.

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 explicitly names an alternative ('chat_ask(suggest_followups=true)') and explains when that alternative is appropriate versus this standalone tool. It also states that results can be passed to matching generators, giving clear guidance on how to use the tool.

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