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

With no annotations, the description carries the transparency burden. It discloses that each profile has its own quota and specifies the return fields (profile, account, authenticated, default). It also notes that adding accounts requires a separate CLI command, providing operational context beyond a simple list operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the main purpose. Every sentence earns its place: the first states what it does, the second explains the profile/quota context, and the third provides the alternative for adding accounts. 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 has no parameters, an output schema exists, and the description covers return fields and usage context, the tool is fully specified. The quota note adds useful operational context, and the CLI guidance fills a likely user need.

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 has zero parameters, so the baseline is 4. The description adds no parameter-specific details because none are needed; the schema is already empty and complete.

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 ('Lista') and clearly identifies the resource ('cuentas de Google (perfiles) disponibles para NotebookLM'). It distinguishes itself from sibling tools like account_use by focusing on listing available profiles rather than using them.

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 clarifies that this tool is for listing accounts and provides an explicit alternative workflow for adding accounts via a CLI command. While it doesn't mention sibling alternatives like account_use, the instruction to run `notebooklm login` for adding implies this tool is not for that purpose.

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 disclosure. It notably reveals a key behavioral consequence: switching accounts releases the active notebook and that notebooks are not shared between accounts. This is valuable side-effect information beyond the basic action. It does not describe error conditions or return format, but for a simple selection tool, this is adequate.

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 extremely concise: two sentences, no filler. The first sentence states the purpose, and the second provides the parameter source and a critical side-effect. It earns its place with zero waste.

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

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

For a tool with one simple parameter and an output schema, the description is quite complete. It explains the action, the parameter semantics, and a key side-effect. It doesn't elaborate on output, but the output schema covers that. It could mention error cases or prerequisites, but these are not critical for account selection.

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 only a bare string parameter 'profile' with no description (0% coverage). The description compensates by explaining that profile is the name returned by account_list, giving the agent a clear source for the value. This is sufficient for a single parameter, though it lacks examples or format details.

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 begins with a specific verb ('Elige') and resource ('cuenta'), clearly stating the action: selecting the account for the rest of the session. It also distinguishes itself from sibling account_list by referencing the profile name as the return value of account_list, establishing a clear relationship and 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?

The description provides clear context for when to use this tool: when you need to switch to or select an account for the session. It also implicitly instructs to get the profile name from account_list. It does not explicitly state when not to use it or mention alternatives, but the session-scoping and notebook side-effect give the agent practical 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?

Despite annotations declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral detail: polling mechanism, timeout behavior, resumability across transport resets, and the three possible statuses. This goes far beyond the annotation and gives the agent a precise mental model.

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 structured with a brief intro, a parameter instruction, and a bulleted list of status outcomes. Every sentence is purposeful, no filler, and formatting aids quick comprehension.

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

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

Despite having an output schema (true), the description goes beyond it by explaining the full workflow: when to call, what to pass, what each status means, and how to handle pending/expired cases. It is complete for a polling tool with this 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?

With 0% schema description coverage, the description must compensate. It does so by explaining upload_link (from source_add return) and timeout indirectly ('after ~timeout s'). The default value is in the schema, so no issue. This is solid compensation for 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?

Description opens with a specific verb+resource: 'Wait for a file uploaded via a source_add(source_type="file") link to land.' This clearly distinguishes it from siblings like source_add or source_wait by focusing on the file-upload link wait workflow.

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 clear context: pass the human_upload.url from source_add, re-invoke on pending, and mint a fresh link on expired_or_invalid. It does not explicitly mention alternatives like source_wait, but the usage context is well-defined.

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 excels: it discloses edge-case behaviors (comma-form source_ids limitation, 'no unbounded all' history), output details (raw_response never included, suggested_prompts key omitted when false), and side effects of a recall-only call echoing conversation_id. This is exemplary 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 long but every sentence earns its place, using bold parameter names and clear sub-clauses. It front-loads the core purpose before diving into parameter details, and avoids repetition or filler.

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

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

Given the tool's complexity (7 parameters, multiple modes, and an output schema), the description covers all necessary usage details: parameter interactions, defaults, output guarantees, and rejection conditions. The existence of an output schema means return-value details are not required, so the added output behavior notes are a bonus.

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 adds rich semantics for every parameter: notebook, conversation_id continuation, source_ids accepted formats, history default and meaning, references enum, and suggest_followups behavior. It even explains a subtle comma-embedded-title limitation, fully compensating for the schema's lack of 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 opens with a specific action ('Ask a notebook's sources a question, and/or recall prior turns') and names the resource ('a notebook's sources'). It also covers the tool's dual modes, clearly distinguishing it from sibling tools like suggest_prompts (which only suggests follow-ups) and source_read (which reads sources).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use each parameter: continuing vs starting a conversation, scoping with source_ids, recall-only usage with history, and standalone suggestion mode. It also states a rejection condition ('Pass neither and the call is rejected'). However, it does not explicitly compare against sibling tools such as suggest_prompts, leaving some alternative-selection ambiguity.

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?

With no annotations provided, the description carries the burden of transparency. It discloses that it checks auth, config, and routes for each profile, and that the output includes 'ok' and 'fix' fields when something fails. The word 'Diagnostico' implies a read-only operation, though it doesn't explicitly state that no changes are made.

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: three short sentences, each adding value. The first sentence states the purpose, the second provides usage context, and the third explains output behavior. No unnecessary words 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 simple, parameter-less diagnostic tool with an output schema, the description is complete. It explains what the tool does, when it can be used, what it checks, and how to interpret the output. The output schema handles the detailed return structure, so the description need not repeat it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there is no schema to explain. The description adds appropriate context about its operation, matching the baseline for parameter-less tools.

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 it is a diagnostic tool that reports what works and what doesn't, and provides fix instructions. The verb 'diagnostico' and resource ('health' of profiles) are specific, and the mention of checking auth, config, and paths distinguishes it from sibling status tools like 'studio_status' or 'session_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 provides clear context for when to use the tool: it can be called without selecting an account, and it checks profiles' auth, config, and paths. However, it does not explicitly mention alternatives or when not to use it, which keeps it from 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 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?

Adds significant context beyond annotations: describes irreversibility and the exact two-step confirmation flow, including the fact that default call returns a preview without deleting. Annotations only declare destructiveHint, so this description enriches agent understanding of safety and side effects.

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 compact paragraphs with the core action front-loaded. Every sentence adds essential behavioral detail; 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?

For a two-step delete tool with an output schema, the description fully explains the default preview behavior, the confirmation parameter, and irreversibility. It is complete for an agent to use correctly without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% coverage, but description compensates by explaining that 'notebook' accepts a name or ID and that 'confirm' is a boolean defaulting to false, triggering preview vs actual delete. This gives functional meaning to both 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?

Begins with a specific verb+resource: 'Delete a notebook (irreversible).' Clearly distinguishes from siblings like notebook_create, notebook_list, and notebook_rename by stating the delete action. Also clarifies input type ('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?

Provides clear contextual guidance on the two-step confirmation process and how confirm=False vs true changes behavior. Does not explicitly name alternative tools for exclusion, but the resource-specific nature makes the use case 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, the description carries the burden of disclosing behavior. It reveals that the tool changes session state (active notebook) and affects subsequent tool calls by auto-filling the notebook parameter. It also acknowledges that passing another value changes the active notebook. This is sufficient transparency for a state-setting tool, though it does not mention validation or error conditions.

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 short sentences. The first sentence states the core purpose and input format; the second explains the behavioral consequence and how to change. Every word earns its place, with no redundancy or irrelevant detail.

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

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

Despite having only one parameter and no annotations, the description fully covers the tool's purpose, input semantics, and behavioral effects on subsequent tool usage. The existence of an output schema reduces the need to document return values, and no critical information appears missing for an agent to invoke this 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?

The schema only provides a required string parameter 'notebook' with no description. The description adds meaning by specifying that it accepts a title, unique prefix, or ID, which is crucial for understanding what values are valid. 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's purpose: 'Fija el notebook activo' (sets the active notebook), with a specific verb and resource. It also clarifies accepted input formats (title, unique prefix, or id), distinguishing it from sibling tools like notebook_create or notebook_delete.

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 conveys when to use the tool: before other tool calls to avoid specifying the notebook parameter each time. It states that after using this tool, 'puedes omitir `notebook` en las demas tools' and that passing another notebook changes the active one, giving clear context. It does not explicitly name alternative tools, but the usage pattern is clear.

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

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

With no annotations 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?

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?

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description richly discloses behavior: default omission of report/source markdown, truncation behavior, source pagination, ambiguous task pinning, and the deprecated task_id alias. This goes 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?

The description is organized into short, information-dense sentences. It front-loads the core purpose, then systematically covers return values, optional parameters, and edge cases. No sentence is wasted; it is appropriately sized for 7 parameters.

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 covers all relevant use cases: polling, report inclusion/truncation, pagination, ambiguous task pinning, and deprecation. Since an output schema exists, it does not need to re-explain return structures, but it still adds useful field-level context (e.g., report_char_count, report_truncated).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description compensates fully. It explains notebook (name or ID), poll_task_id (pinning), include_report, report_max_chars (truncation), source_limit/source_offset (pagination), and task_id (deprecated alias). Every parameter is given meaningful semantics.

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 clear verb+resource: 'Check a notebook's research status.' It specifies what the tool does (returns status) and differentiates it from sibling tools like research_start, research_cancel, and research_import by focusing on the status-checking and polling workflow.

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 polling workflow: 'Poll until completed, then pass poll_task_id to research_import.' It also gives parameter-level usage guidance (e.g., 'omit it for a single task (ambiguous with two+ running)') and distinguishes from the next step, research_import.

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?

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description reveals significant behavioral details: default call is a fast network-free probe, quota fields degrade gracefully when the session is stale instead of failing, and the deliberate omission of the on-disk storage path for security reasons. This level of depth exceeds 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?

The description is long but very well-structured, with clear sections for return values, the include_account behavior, and a security note. Every sentence adds value, but it could be slightly more concise without losing critical detail. The front-loaded purpose sentence helps orientation.

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 comprehensively covers the tool's behavior: return fields, parameter effects, default vs. extended modes, degradation logic, and security rationale. It also references the output schema implicitly by detailing the auth and account blocks, making it self-sufficient for an agent to choose and invoke the 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?

The input schema only lists 'include_account' with no description (0% coverage). The description fully compensates by explaining what setting it to True fetches, the structure of the account block, and the trade-off (live session needed for quota fields). This gives the agent complete understanding of the parameter's purpose and consequences.

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

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

The description opens with a specific verb and resource: 'Report the server version and local authentication health.' It clearly separates this tool from siblings by focusing on authentication status and account information, making it distinct from health or session_status 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 explicitly states when to use the tool: 'Use it to confirm the server is logged in before driving notebook tools.' It even provides a remediation step if authentication fails (run notebooklm login). However, it doesn't directly compare with alternatives like health or session_status, nor explicitly state when not to use 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, the description carries the full burden. It indicates a read-only informational role, which is transparent, but it does not clarify what 'active' means, whether authentication is required, or whether it only reports the current session. This is minimal but not misleading.

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 with no waste. It front-loads the action and resource, but the informal phrasing and lack of context around 'active' reduce its polish 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?

For a zero-parameter tool with an output schema, the description covers the core purpose but leaves ambiguity about the meaning of 'active' and whether it reports all accounts or just the current one. The output schema likely fills return format details, so a 3 is appropriate.

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 has zero parameters, so the baseline is 4. The description adds semantic value by specifying the scope of the result (which account and notebooks), which is essential since the schema is empty.

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 reports which account and notebooks are active, using a specific verb and resource. It differentiates from sibling status tools (studio_status, research_status) by explicitly naming account and notebook scope, though it could be more formal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The phrase 'ahora mismo' implies current status, but there is no exclusions or mention of complementary tools, leaving the agent without clear selection criteria.

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 though annotations already mark the tool as destructive (destructiveHint: true), the description adds crucial behavioral context beyond that: the default call is non-mutating and returns a preview, and only explicit confirmation triggers the actual removal. This explains the safety mechanism and what happens in each mode, which annotations cannot convey. No contradiction with 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?

The description is concise and well-structured: it leads with the primary purpose, then immediately explains the confirm-gating behavior in a separate paragraph. Every sentence adds value with no redundancy or filler.

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

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

Given the tool's complexity (confirm-gating, destructive action) and the presence of an output schema, the description covers the essential behavioral aspects and the key parameter semantics. The output schema presumably documents return values, so return description is not required. The description is sufficiently complete for an agent to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It explains that 'notebook' accepts a name or ID, and clarifies the 'confirm' parameter's role in preview vs. actual removal. The 'email' parameter is not explicitly described, but its purpose (user email) is self-evident. This adds meaningful semantics for the non-obvious parameters, though not for all.

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: 'Remove a user's access to a notebook.' It specifies the resource (notebook) and the action (remove user access), and it accepts a notebook name or ID, distinguishing it from sibling tools like share_set_user or share_status that serve different purposes.

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 clear usage context by explaining the confirm-gated behavior: calling with confirm=False (default) returns a needs_confirmation preview, while confirm=True is required to actually mutate. It does not explicitly name alternatives or exclusions, but the confirmation mechanism is a strong practical guideline for when and how to use the tool safely.

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 responsibility for behavioral disclosure and excels: it reveals the needs_confirmation preview for public widening, that restricting and view_level changes are not gated, that view_level is only echoed when set, and that fields apply in order with fail-closed behavior. This is exemplary 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 compact yet information-dense. Each sentence covers a distinct aspect—operation, parameters, gating behavior, return value, and edge-case ordering—without any filler. The primary purpose is front-loaded, making it easy to scan.

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 moderate complexity and the absence of annotations, the description is remarkably complete: it explains return values (status or preview), partial-failure semantics, ordering of field application, and field-echo quirks. The existence of an output schema further reduces the need to detail return structure.

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% description coverage, so the description must compensate, and it does thoroughly: public is defined as True/False for anyone-with-link/restricted, view_level as full/chat, confirm as the override to the preview, and notebook as name or ID. Every parameter gains semantic meaning beyond 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 uses a specific verb ('Set') and resource ('a notebook's link-access settings'), clearly distinguishing it from sibling tools like share_set_user and share_remove_user which manage user-specific access. It precisely defines the scope of the 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 provides clear context for when to use this tool (to modify link-access settings) and explains the confirm gate for public widening. However, it does not explicitly name alternative tools or state when not to use it, 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?

With no annotations provided, the description carries the full burden and does so admirably. It discloses the confirm-gated nature (needs_confirmation preview unless confirm=True), the upsert behavior, the notify email side effect with default, and the fact that permission cannot be OWNER. This goes well beyond minimum 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?

The description is concise yet information-dense. The first sentence states the core purpose, followed by a compact paragraph covering key behaviors and parameter semantics. No wasted words; each line adds value.

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

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

Given the tool's complexity (6 parameters, confirmation flow, upsert semantics) and the absence of annotations, the description is remarkably complete. It explains key behavioral traits, parameter constraints, return values, and optional behaviors. The output schema further supplements return-value details, making this a well-rounded description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must explain all parameters. It covers notebook (name or ID), email (upsert key), permission (editor/viewer), notify (default False, emails user), message (optional welcome note), and confirm (gating behavior). Defaults are stated and parameter roles are clear.

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 verb+resource statement: 'Grant or change a user's access to a notebook.' It further specifies the scope by mentioning notebook name/ID and permission values (editor/viewer), effectively distinguishing from relevant siblings like share_remove_user. The purpose is unambiguous and specific.

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 clear context for when to use the tool: it handles grants and permission changes via an upsert, and describes the confirmation flow. It stops short of explicitly naming alternative tools or stating when not to use this tool, but the guidance is sufficient for most cases.

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 fully carries the burden and does so thoroughly: discloses async import behavior, partial-failure isolation in batch, upload_required flow, transport-specific filesystem limits, base64 size cap, title override behavior, and error signaling (inline warnings, status_label). Even details timeout/interval polling semantics.

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?

Although long, the description is well-structured with headers, bullet lists, and a code block for the batch response. Every section adds distinct, non-redundant value. Issue references add traceability without bloating. The front-loaded purpose makes the tool immediately understandable despite its 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?

Given 15 parameters, no output schema, and no annotations, the description is remarkably complete: covers return formats for both modes, error handling, async status, size limits, transport differences, and wait polling. It leaves no significant gap for an agent to invoke the 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%, yet every parameter is explained in context: source_type picks required inputs, wait/timeout/interval, notebook, mime_type, document_id, bytes_base64, filename, urls, allow_internal, title. Constraints like mutual exclusivity and base64 length limits are explicitly stated, which is essential for correct invocation.

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: 'Add a source to a notebook — single, batch, or in-channel bytes.' Clearly identifies the action and scope, and distinguishes from siblings like source_delete/source_list. Accepts a notebook name or ID, which is a necessary qualifier.

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 mode selection rules: single vs batch, when wait should be used, and clear exclusions (e.g., wait is not for remote file signed-URL uploads; batch rejects non-URL entries). References source_wait and source_list as complements. Does not explicitly mention the sibling source_add_drive_file, but the drive mode is fully covered via source_type='drive'.

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 behavioral disclosure burden. It discloses async processing, the wait flag, server-side fetch, pointer-error routing, and remote-connector compatibility. It doesn't detail permissions or side effects beyond 'add', but the most critical non-obvious behaviors are clearly stated.

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 dense paragraphs each serve a distinct purpose: definition, routing/alternatives, and input formats plus async behavior. Every sentence adds useful information without redundancy or 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 output schema exists, return-value documentation is unnecessary. The description covers tool-specific routing, supported formats, async semantics, wait behavior, and error-confirmation via source_wait/source_list. This is complete for a tool with this 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 coverage is 0%, so the description must compensate. It clearly explains that notebook accepts a name or ID, document_id accepts a Drive file ID or share URL in multiple formats, and wait controls blocking behavior. The optional title parameter is not explicitly described, but its purpose is inferable from 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?

The description opens with a specific verb and resource: 'Add a Google Drive file by downloading it server-side and uploading it.' It clearly distinguishes this tool from siblings by naming source_add(source_type='drive', mime_type=…) and source_add(source_type='file') as alternatives for different cases.

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 explicit when-to-use and when-not-to-use guidance: Google-native Docs/Slides/Sheet should use source_add(source_type='drive', mime_type=…), and local bytes should use source_add(source_type='file'). It also explains when to pass wait=true and how to verify async completion.

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 though annotations already indicate destructiveHint=true, the description adds critical behavioral details: the confirmation flow, that the default call is a non-destructive preview, and that irreversible deletion only occurs with confirm=True. This goes well beyond the annotations and is essential for safe usage.

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-load the core purpose and then provide necessary usage detail. No wasted words, every sentence contributes to understanding the tool's 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?

For a destructive tool, the description explains the essential confirmation workflow and irreversibility, which is the most critical context. It does not mention error conditions or the exact format of the preview, but given the output schema exists and the two-step process is clear, it is reasonably complete. The slight ambiguity around identifier formats keeps it from being perfect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 0%, the description compensates by explaining that `source` can be a name or ID and that `confirm` controls the two-step behavior. However, the phrase 'notebook/source name or ID' is slightly ambiguous regarding whether `notebook` is also a name or ID, so it does not fully clarify all parameter nuances.

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 'Delete a source (irreversible)', which is a specific verb and resource that clearly distinguishes this from sibling tools like source_read or source_rename. It also clarifies that it accepts a name or ID, further eliminating 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?

The two-step confirmation process is clearly described, giving explicit instructions on how to use the tool safely (preview with confirm=False, then delete with confirm=True). However, it does not explicitly contrast with alternatives or state when not to use the tool, so it's slightly below a perfect score.

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 indicate a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds value by explaining the difference between 'full' and 'compact' detail, the meaning of status 'error' as a ghost row, and how labels compose with status. This goes beyond the structured 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?

The description is efficiently structured: it opens with the primary purpose, then uses a compact code-block style to explain parameters. Every sentence adds meaningful detail, avoiding redundancy. It is well-sized for 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?

Given the output schema exists and annotations cover safety, the description sufficiently covers the tool's behavior and filtering options. It lacks explicit mention of pagination behavior (limit/offset) and does not enumerate all status values, but these are present in the schema. Overall, it provides a solid understanding without over-explaining.

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 explains the 'detail' parameter (full vs compact), the 'status' filter (including 'error' semantics), the 'label' parameter, and the 'notebook' parameter in prose. The 'limit' and 'offset' pagination parameters are not explicitly described, but they are standard and have defaults in 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 clearly states the tool's function: 'List a notebook's sources.' This uses a specific verb and resource, and the additional note about accepting a notebook name or ID clarifies the input. It distinguishes itself from sibling tools like source_read or source_delete by focusing on the listing 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 provides clear context on how to use the tool, including filter options (status, label) and detail levels. However, it does not explicitly mention exclusions or alternatives like 'use source_read for a single source's content.' It still offers sufficient guidance for typical use cases.

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 indicate readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that. It discloses content length limits (default 10,000 chars), pagination via offset/max_chars, that char_count stays full length, content null when not ready, and that output_format markdown requires a server extra. No contradiction with 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?

The description is long but densely structured with bullet points and code blocks. Every sentence earns its place, delivering detailed parameter semantics and return shapes without redundancy. It is front-loaded with a clear purpose statement and then organized detail.

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 explains return values thoroughly, including both detail shapes and edge cases like truncated content and null content. It also covers the 'markdownify' dependency and refers to chat_ask for large sources, making the tool's behavior fully understandable in context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description fully compensates. It explains each parameter: detail chooses the return shape, offset/max_chars slice the content, output_format controls formatting, and provides the exact return keys for summary and full. This goes far beyond the schema's bare enum/type definitions.

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

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

The description states a specific verb and resource: 'Read a source at one of two detail levels.' It clearly differentiates from sibling tools like source_list, source_delete, and source_wait by focusing on reading the content/metadata at chosen detail levels. The two detail shapes (summary vs full) further clarify the tool's 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 explicit usage guidance: 'summary' is recommended for low-token triage across many sources, 'full' for detailed content, and it explicitly says 'Prefer chat_ask for querying large sources rather than pulling the whole body.' This names an alternative and provides context on when to choose one approach over others.

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?

The description goes far beyond the annotations by detailing the two-step confirmation flow, idempotency for absent full IDs, routing behavior, and the artifact-delete nuance that it clears a note-backed mind map rather than hard-removing it. This adds significant insight into the tool's runtime behavior and edge cases.

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 necessary information: purpose, routing, confirmation flow, idempotency, and artifact-specific behavior. It is well-structured, starting with the core purpose and then escalating into edge cases without any 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 (two-step confirmation, type routing, idempotency, and artifact clearing semantics), the description is exceptionally complete. It covers the full workflow, expected inputs, and subtle behaviors. The presence of an output schema means return values need not be detailed, but even without it, the description is self-sufficient.

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 zero parameter descriptions, but the description explains all three parameters: 'notebook' as a name or ID, 'item' as a name-or-id ref resolved over the merged notes+artifacts list, and 'confirm' with its default false behavior leading to a preview. This fully compensates for the schema's lack of description.

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 'Delete a Studio item (irreversible) — a text note OR an artifact.' This specifies the exact action (delete), the resource (Studio item), the scope (notes or artifacts), and the irreversible nature. It distinguishes the tool from sibling delete tools by focusing on Studio items and their dual types.

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 clear operational context: it accepts notebooks and items, routes by resolved type, and explains the two-step confirmation. However, it does not explicitly state when to prefer this tool over alternatives or mention exclusion conditions (e.g., 'use source_delete for sources instead'). The context is strong but lacks explicit naming of alternatives.

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

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

With no annotations, the description carries the full burden: it discloses that over remote the path is ignored and a signed URL is returned, that text kinds return truncated inline content, and that explicit artifact_id is validated up front. This exceeds typical behavioral disclosure.

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 structured with a one-sentence summary, bullet lists, and transport sections. Every sentence adds functional information; the length is justified by 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?

It covers dialog semantics, return values for remote and text kinds, error validation, and output format support. The absence of an output schema is mitigated by explicit response 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?

Despite 0% schema description coverage, the description explains all six parameters—notebook name/ID, artifact ref, artifact_type with enum values, artifact_id prefix, output_format mappings, and transport-dependent path. It adds meaning far beyond 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 'Download a generated artifact,' a specific verb+resource pairing. It further details the two targeting modes, distinguishing it from sibling tools like studio_list 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?

It gives explicit instructions on exactly-one targeting between artifact and artifact_type, and explains when to use each with artifact_id. Transport-specific guidelines (stdio vs remote) and output_format overrides provide clear context, though it doesn't explicitly compare against alternative 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, 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 already set readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail: pagination bounds (limit/offset, total, has_more), the detail ladder (summary, full, compact), item-specific behavior (returns 1-element list with full content, NOT_FOUND on no match, ignores limit/offset/detail), and kind scoping. No contradictions with 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?

The description is long but densely informational, with a clear first line, then structured paragraphs and bullet-style lists for detail and item behaviors. Every sentence contributes meaning; there is no fluff or repetition. The front-loading of the core purpose and the organized breakdown of parameter interactions make it highly effective.

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 parameters, multiple behaviors, output schema exists), the description is remarkably complete. It covers pagination, the detail ladder, kind filtering, single-item fetches, and error behavior (NOT_FOUND). Since an output schema exists, return values need not be fully re-explained, but the description still outlines item fields. No critical 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%, so the description must carry the full burden. It explains every parameter: notebook (name or ID), item (name or id), kind (filters to one type), limit/offset (pagination), detail (three levels with exact field differences), and notes interactions such as 'kind scopes resolution' and 'limit/offset/detail are ignored with item.' 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 description opens with a specific verb+resource: 'List a notebook's Studio panel — text notes AND generated artifacts.' It clearly distinguishes this tool from siblings like studio_generate (creates) and studio_download (fetches artifact bodies) by stating it lists both notes and artifacts in a merged list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance for when to use studio_download instead ('read a report/data-table body via studio_download'), and clarifies that item fetches a specific item, ignoring other params. It provides context about the detail ladder and kind filtering, but could more explicitly contrast with studio_status or studio_generate. Overall, it offers clear context with one explicit alternative.

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

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

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.