Gemini Notebook (NotebookLM) MCP Server by useapi.net (third-party)

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

Annotations declare non-readOnly, non-idempotent, open-world, non-destructive; the description goes further by disclosing the asynchronous processing model ('Google processes a source before chat and Studio can use it... status ready'), the returned fields (id, title, kind, status), and the concrete duplicate-source risk on retry. That is exactly the context annotations cannot carry.

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

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

Front-loaded with what the tool does, then the return shape, then the sibling exclusion, then the retry hazard — each in a single dense clause with no filler. The trailing 'POST /sources' is the only near-redundant element and is trivial.

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

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

No output schema exists, and the description compensates by naming the returned fields and the status lifecycle the agent must poll. Combined with the retry warning and the sibling routing, an agent has everything needed to call this correctly on the first attempt.

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 100%, so baseline is 3, but the description adds a real constraint the schema cannot express: at least one source-bearing parameter must be supplied even though only 'notebook' is required. It also states the 1-50 URL ceiling and that YouTube links are auto-classified, reinforcing rather than duplicating schema text.

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 sources to a notebook in one call') and enumerates the accepted source kinds: URLs/YouTube, pasted text, Drive files, Play Books ebooks. It explicitly names the sibling it is not (notebook_upload_source for file uploads), so the boundary is unambiguous.

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

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

Gives the selection rule against the alternative ('For a file (PDF, audio, image...) use notebook_upload_source') and an in-band constraint ('give at least one'). It also prescribes a timeout recovery procedure ('check notebook_get_notebook before retrying, or sources may be added twice'), which is explicit when-and-how 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 establish the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real value beyond them: the source preserves its id, labels and citations, and the return value carries a new word count. It stops short of noting any re-indexing or citation-refresh behavior, so it is not exhaustive.

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

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

Three tight sentences, front-loaded with the append semantics before the alternative and the return note. The trailing 'POST /sources/append' is marginally useful API detail but not wasteful.

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 helpfully states what comes back (the updated source with its new word count), and the append-vs-add distinction is covered. For a simple 3-parameter mutation with full annotation coverage, this is nearly complete; only the effect on indexing/citations over time is unstated.

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

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

Schema description coverage is 100%, so all three parameters are already documented (including that title is an optional heading). The description restates the title/optional-heading point rather than adding syntax or constraint detail, so baseline 3 applies.

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

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

States a specific verb ('Add text to the end') and resource ('an existing source'), scopes it to pasted text or web pages, and explicitly contrasts with notebook_add_sources for new sources. An agent can distinguish it from siblings like notebook_add_sources without opening the schema.

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

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

Explicitly routes the agent: use this to append to an existing source, use notebook_add_sources to add a separate source. The condition that selects the alternative is stated directly, leaving nothing to inference.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, non-idempotent), and the description adds genuinely new behavioral context: a 5-40s latency budget and the readiness precondition that gates the call. It stops short of describing cost, quota, or failure modes beyond the 'no source ready' case, so it is strong but not maximal.

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

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

Dense but zero waste: return shape, latency, precondition, configuration sibling, and alternative sibling are all front-loaded in a few clauses. Every sentence carries distinct information.

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

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

With no output schema, the description carries the return contract itself (answer plus numbered citations with source ids, plus a conversation id) and pairs it with latency, preconditions, and routing to alternatives. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, making 3 the baseline. The description reinforces the semantics of 'sources' (every ready one by default, or the given ids) and 'conversation' (pass the returned id back for a follow-up), but adds no format or syntax detail the schema lacks.

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

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

States a specific verb and resource: asking a question answered from the notebook's sources. It names two siblings (notebook_set_chat_settings, notebook_search_sources) and delineates its scope as answer-generation versus raw passages, so an agent can distinguish it without opening any schema.

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

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

Explicitly routes the agent: use notebook_search_sources for raw passages without an answer, and configure behavior via notebook_set_chat_settings. It also states the precondition ('refused while no source is ready') so the agent knows when the call will fail.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds substantial context beyond them: the exact resulting state (failed, code cancelled), that usage is spent regardless, that a research run stops at Google while a Studio artifact may still finish locally, and that the operation is irreversible.

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

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

Four tight sentences, front-loaded with the core action and effect, then the Google/Studio nuance, then the irreversibility warning. Every sentence carries distinct, decision-relevant information with no padding.

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

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

No output schema exists, and the description compensates by describing the return (the job, now failed with code cancelled). Combined with the state-change and irreversibility details, an agent has everything needed to call this 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?

With a single parameter at 100% schema description coverage, the schema already documents jobid, so baseline is 3. The description adds no syntax or format detail for the identifier and merely references 'the job' in the return-value discussion.

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

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

States a specific verb+resource (cancel a running job) and adds precise scope: it stops tracking and frees the maxJobs slot, leaving the job failed with code cancelled. This clearly distinguishes it from siblings like notebook_get_job (read) and notebook_retry_artifact (re-run).

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

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

Gives clear when-to-use context (stopping a running job) and an explicit when-not/alternative direction: 'Cannot be resumed: start a new job instead.' It does not name the specific sibling tool for starting a job (e.g. notebook_research), but the routing guidance is unambiguous.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive write with open-world scope. The description adds real value beyond that by stating generation is NOT repeated and originals stay, which explains the non-destructive, non-idempotent profile, and by describing the return payload since no output schema 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 tight sentences, front-loaded with the core action and constraints, then sibling routing, then return shape and endpoint. No sentence is redundant.

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

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

With no output schema, the description compensates by describing the returned fields (id, type, title, status, source id). Combined with the mutation semantics, originals-preserved guarantee, and sibling pointer, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters (target notebook id, artifact ids) are already documented in the schema. The description only reinforces that the ids come from a single notebook and must be finished artifacts, adding marginal meaning beyond the schema baseline.

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

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

States a specific verb+resource+scope: copying finished artifacts of one notebook into another notebook of the same account. It explicitly names the sibling notebook_copy_notebook as the alternative for whole-notebook copies, letting an agent separate the two without opening schemas.

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

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

Gives clear context (finished artifacts, same account, originals preserved) and routes the agent to notebook_copy_notebook for the whole-notebook case. It does not address exclusions such as unfinished artifacts or cross-account targets, but the positive guidance is explicit.

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

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

Annotations only carry the generic profile (readOnly=false, idempotent=false, destructive=false). The description adds substantial non-obvious behavior: new ids are assigned, nothing is regenerated, the original is unchanged, the return value is the new notebook id, and the timeout/duplicate-copy hazard that explains the non-idempotent hint.

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

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

Front-loaded with the core purpose and the return value, then the timeout caveat and sibling alternatives. It is dense but each clause carries actionable information; the parentheticals (new ids, nothing regenerated) are informative rather than wasteful.

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 2-parameter copy tool with no output schema, the description covers purpose, scope, return value, constraints on the original, and failure handling. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, including the title default. The description restates the title default ('the original's, with " (copy)"'), adding no syntax or meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (duplicate/copy) and resource (notebook) plus exact scope: 'with its sources and Studio artifacts into a new notebook on the same account'. It explicitly contrasts with the partial-copy siblings notebook_copy_sources and notebook_copy_artifacts, so the agent can distinguish it without opening any schema.

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

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

Gives explicit routing: use this for a full copy, but use notebook_copy_sources or notebook_copy_artifacts 'to copy only some items'. It also adds a concrete when-to-check rule after a timeout ('check notebook_list_notebooks before retrying, or you may get two copies').

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds real behavioral context: no re-fetch or re-upload, new ids are minted, and originals remain intact. It stops short of warning that repeated calls are not idempotent and will produce duplicate copies.

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

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

Three tight sentences plus the endpoint path, with the core behavior and the return-value note front-loaded and no filler. Every sentence carries either behavior, routing, or output information.

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

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

With no output schema, the description compensates by describing the return value (each copy's id paired with its origin id). Combined with the routing hint and the preservation semantics, an agent has what it needs to invoke this correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the 'all from one notebook' constraint. The description adds only the 'same account' constraint, which is marginal beyond what the schema and structured fields provide.

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

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

States a specific verb and resource with precise scope: copy sources from one notebook to another with new ids, originals preserved. The description also distinguishes itself from notebook_copy_notebook by name, so an agent can route correctly without opening either schema.

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

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

Explicitly names notebook_copy_notebook as the alternative for whole-notebook copies, with the selecting condition stated. It does not, however, address the closer sibling notebook_add_sources, so the copy-vs-add boundary is left to inference.

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

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

Annotations already declare the write/read/non-idempotent/destructive profile, so the description's added value is the partial-success behavior: if the emoji fails, the collection is still created and a warning is returned. It also discloses the return value (collection id). This is genuinely useful beyond structured data, though it doesn't discuss permissions 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?

Front-loads the core purpose and keeps the follow-up and edge-case sentences short. Every sentence earns its place, though 'POST /collections' is minor implementation detail that adds little for the agent.

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

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

No output schema exists, but the description states what is returned (collection id) and covers the emoji partial-failure case. Combined with 100% schema coverage and annotations, an agent has enough to call it correctly; only auth/permission expectations are unaddressed.

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

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

Schema coverage is 100% and each parameter (name, email, emoji) is documented in the schema itself. The description adds only marginal context (account scoping, emoji-failure handling) and does not add syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (Create) and resource (collection), and even defines the resource as 'a named folder for notebooks,' which removes ambiguity. It also names the tool that adds notebooks (notebook_update_collection), distinguishing it from sibling update/list/delete variants.

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

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

Gives clear operational context: create empty first, then populate via notebook_update_collection, and notes the account scope ('on one account'). It lacks an explicit when/when-not framing against alternatives, but the routing to the follow-up tool is clear.

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

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

Annotations grant no destructive/idempotent detail beyond hints; the description adds real behavioral context by noting that auto:all *replaces* existing labels and that the call returns the notebook's whole label set. It also discloses the POST endpoint. Minor gap: it doesn't warn that this is non-idempotent (re-running auto:all re-triggers labeling).

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

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

Front-loads the three usage modes in one dense sentence, then tacks on two short, high-value sentences (return value, next-step tool, endpoint). The heavy parentheticals make the first sentence a bit packed, but every clause carries information.

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

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

For a 4-param write tool with no output schema, the description covers the modes, the key constraint, the return value ('whole label set'), and the follow-up tool. Complete enough to call correctly; only the non-idempotency caveat 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 100%, so baseline is 3, but the description adds meaning beyond the schema: it explains the enum values' effect (all vs. unlabeled) and states the mutual-exclusion constraint between auto and name that the schema's additionalProperties=false does not enforce.

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

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

States a specific verb (create labels) and resource (source labels) and enumerates the three distinct modes: auto-all, auto-unlabeled, and a named label. It even names the sibling used to fill labels, so an agent can separate this from notebook_update_label without opening either schema.

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

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

Explicitly frames the when-to-use branch: 'all of them (auto: all, replacing the existing labels) or only unlabeled ones (auto: unlabeled), or create one empty label of your own (name...)'. It also gives the exclusivity rule 'give auto or name, not both' and points to the alternative tool for populating a label.

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 annotations it discloses that this is synchronous ("Not a job"), a ready-source precondition, and the return shape (note id + JSON tree). These are useful since sibling tools involve jobs. It doesn't discuss idempotency or cost, but annotations already cover the safety profile (readOnly/destructive/idempotent).

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

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

Front-loaded with the action, then precondition, then the alternative, then the endpoint. Every clause carries distinct information with no filler; two compact sentences do a lot of work.

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?

Although there is no output schema, the description explains the return value ({ name, children } JSON tree plus note id), the failure mode, and the routing alternative. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the sources default. The description's "ready sources (or the ones given)" lightly reinforces the sources default but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ("Generate a mind map of the notebook's ready sources... saved as a note") and distinguishes it from the similar-sounding notebook_generate_artifact/type mindmap sibling. An agent can tell exactly what it produces without opening a schema.

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

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

Names the alternative explicitly ("For Studio's interactive mind map artifact use notebook_generate_artifact with type mindmap instead") and states the precondition under which the call fails ("refused while no source is ready"). Both when-to-use and when-not are covered.

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

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

Annotations cover the safety profile (write, non-destructive, non-idempotent, open-world), so the bar is lower. The description adds genuine context beyond that: default titles, the return value ('Returns the note id'), and the downstream source-conversion workflow. It does not surface the idempotency implication (calling twice creates duplicates), leaving a minor gap.

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

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

Information-dense and front-loaded: the core verb and the two creation modes lead, followed by defaults, return value, and next-step hint. Parenthetical asides make it slightly dense, but every clause carries actionable information.

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

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

For a four-parameter creation tool with no output schema, the description covers the essentials an agent needs: the exclusivity constraint, defaults, the return value (note id), and the follow-up workflow. Nothing critical to correct invocation 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 100%, so the baseline is 3. The description goes beyond the schema by explaining the behavior of 'conversation' (its turns become Q/A Markdown) and reinforcing that content is your own Markdown, adding semantic meaning to two parameters rather than merely restating them.

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

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

States a specific verb (Create) and resource (a note in a notebook) plus the two distinct modes of creation (own Markdown vs. a whole conversation). It distinguishes itself from siblings like notebook_create_mindmap_note and notebook_update_note by naming what it does and how chat content is handled.

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

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

Explicitly states the mutual-exclusion rule ('give exactly one of the two') and routes the agent to notebook_note_to_source as the next step when the note must be usable by chat and Studio. It lacks an explicit when-not-to-use-this rule versus other create paths, but the context is clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds behavioral value beyond them by stating the notebook is created empty and that its id is returned, and by noting the alternative tool can create the notebook implicitly. It stops short of permissions or rate-limit context.

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

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

Three sentences, front-loaded with the core action and return value, followed by workflow routing. Every sentence carries distinct information; even the trailing 'POST /notebooks' is a compact endpoint pointer.

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

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

There is no output schema, so the description correctly compensates by stating the return value (notebook id). Combined with the next-step routing and the annotations covering safety, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and both parameters (email, title) are documented in the schema itself. The description only echoes the optional title ('optionally titled') and adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Create an empty notebook, optionally titled') and explicitly states the return value ('return its notebook id'). It is clearly distinguishable from sibling creation tools like notebook_generate_artifact and notebook_create_note.

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?

Names the exact follow-up tools by name and the content each handles (notebook_add_sources for URLs/YouTube/text/Drive/Play Books, notebook_upload_source for files), and gives a concrete condition for choosing the alternative route ('To make one Studio artifact straight from URLs or text, notebook_generate_artifact can create the notebook itself'). This is explicit when/when-else routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is covered structurally; the description adds the important irreversible consequence ('Cannot be undone') and clarifies the dual dismiss/delete behavior that annotations do not capture.

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

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

Three tight sentences, front-loaded with the destructive action, followed by the alternative tool and endpoint. Only the raw 'DELETE /artifacts/{artifact}' path is somewhat expendable, but it is compact.

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 single-parameter mutation with full annotation coverage and no output schema, the description covers destructiveness, irreversibility, dual semantics, and sibling routing. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the sole parameter is already documented with its sources (notebook_list_artifacts, job result). The description adds only the extra source case (a report's embedded list), which is useful but marginal over the schema baseline.

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

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

States a specific verb (delete/dismiss) and resource (Studio artifact / interactive report suggested item), and explicitly distinguishes itself from the job-cancellation sibling notebook_cancel_job. An agent can tell exactly what this does without opening the schema.

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

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

Explains the two distinct use cases (delete an artifact vs dismiss a report's suggested item) and names the alternative tool for stopping a running job. It lacks an explicit statement of when not to delete, but the routing context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds value beyond that: irreversibility, the consequence that the next notebook_ask starts a fresh conversation, and the explicit scope that sources/notes/artifacts are untouched.

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

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

Front-loads the key action ('Permanently delete') and packs consequence, scope, alternative and error condition into one tight paragraph with no wasted sentences.

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

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

For a destructive tool with no output schema, the description discloses irreversibility, what is and is not affected, the follow-on behavior, the failure condition, and a preservation path. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including the conversation default ('the latest'). The description restates 'the conversation given, or the latest one' but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a notebook's chat history') and scopes it precisely to the conversation, distinguishing it from whole-notebook deletion by noting sources, notes and artifacts are untouched. An agent can tell it apart from siblings like notebook_delete_notebook without opening either schema.

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

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

Gives clear context: use it to drop a conversation, and 'To keep it, save it first with notebook_create_note (conversation).' It also states the precondition ('Fails when the notebook has no conversation'). No explicit when-not or comparison against other deletion siblings, so it stops short of a full routing guide.

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

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

Annotations already declare destructiveHint/idempotentHint, but the description adds the crucial blast-radius detail that only the folder is removed and notebooks retain sources and artifacts, plus irreversibility ('Cannot be undone'). It also discloses the return shape, which no output schema provides.

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

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

Three tight sentences: destructive scope first, then irreversibility, then sibling disambiguation and return value. Every clause carries information and 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?

For a single-param destructive tool with no output schema, the description covers the side effects, irreversibility, alternatives, return value, and even the HTTP verb/path. Nothing an agent needs to call it safely 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?

Only one parameter and the schema already documents it at 100% coverage ('Collection id, from notebook_list_collections'). The description adds no format, ID-syntax, or sourcing guidance beyond the schema, so the baseline 3 is correct.

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

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

States a specific verb+resource ('permanently delete a collection') and immediately scopes it to the folder only, noting notebooks survive. This distinguishes it from sibling delete tools without the agent needing to open a schema.

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

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

Explicitly routes to alternatives: notebook_update_collection when you want to remove notebooks but keep the folder, and notebook_delete_notebook to delete a notebook itself. Both the when and the when-not are named.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=true, so the safety profile is covered. The description still adds real value beyond that: it specifies that underlying sources are preserved (only the grouping is removed), that the operation is irreversible, and even the return shape ('label id with deleted: true') and route. This is above the annotation baseline, though 'cannot be undone' largely restates destructiveHint.

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

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

Three tight sentences, front-loaded with the effect and the preservation guarantee, then alternatives, then return value and route. Every clause earns its place and nothing is 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?

No output schema exists, but the description discloses the return ('label id with deleted: true') and the API route. For a single-parameter destructive delete whose annotations cover safety, nothing an agent needs to call it correctly is missing.

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

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

One parameter with 100% schema description coverage; the schema already documents 'label' as 'Label id, from notebook_list_labels'. The description adds no format, example, or constraint details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource and scope: 'Permanently delete one source label from its notebook'. It immediately clarifies what is and isn't affected ('the sources under it stay in the notebook, only the grouping goes') and names the siblings it differs from, so an agent can distinguish it from notebook_update_label and notebook_create_labels without reading further.

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

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

Explicitly routes the agent: use notebook_update_label to rename the label or move sources off it, and notebook_create_labels with auto: all to relabel every source at once. Conditions and alternatives are stated, not implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered structurally. The description still adds value by stating irreversibility explicitly ('Cannot be undone') and by enumerating the note subtypes affected, though it does not discuss permission requirements or failure modes.

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

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

Three short sentences, all front-loaded: the action and scope first, then the irreversibility warning, then the id source and the sibling alternative. No sentence is filler.

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

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

For a one-parameter destructive tool with no output schema and full annotation coverage, the description supplies everything needed: scope, irreversibility, id provenance, and the sibling alternative. Nothing essential is missing.

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

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

Schema description coverage is 100% for the single 'note' parameter, so the schema already documents the id and its provenance. The description repeats that provenance ('Note ids come from notebook_list_notes') without adding format or constraint detail, so the baseline 3 applies.

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

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

States a specific verb (delete) and resource (one note) and clarifies the resource covers notes, saved answers, and mind map notes. It explicitly distinguishes itself from notebook_delete_notebook, so an agent can select it without comparing schemas.

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?

Names the prerequisite source for the id ('Note ids come from notebook_list_notes') and routes the agent to the alternative ('to delete the whole notebook use notebook_delete_notebook'), covering both when to use it and when to use something else.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the crucial beyond-annotation detail that the deletion cascades to sources, notes, chat history and Studio artifacts and cannot be undone. It does not mention any auth requirements or confirm the idempotentHint behavior, so 4 rather than 5.

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

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

Three short sentences, front-loaded with the destructive scope and irreversibility, then the alternative tools, then the endpoint. No filler or redundant restatement of the tool name.

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 single-parameter destructive tool with no output schema, the description covers impact scope, irreversibility, and sibling routing. Nothing an agent needs before invoking it is missing.

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

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

Schema description coverage is 100% and the sole parameter's id format is fully documented in the schema, so the description need not restate it. The trailing 'DELETE /notebooks/{notebook}' adds mild mapping context but no new semantics beyond what the schema provides.

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

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

States a specific verb and resource (permanently delete a notebook) and immediately enumerates the cascade scope: sources, notes, chat history and Studio artifacts. It also names the narrower sibling deletes, so an agent can distinguish whole-notebook deletion from single-item deletion without opening any schema.

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

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

Explicitly routes the agent: 'To remove one item instead use notebook_delete_source, notebook_delete_note or notebook_delete_artifact.' It both states when to use this tool (whole-notebook removal) and when to pick alternatives.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description goes beyond them by stating the deletion is permanent and irreversible, describing the recovery path, and disclosing the side effect that chat and Studio no longer use the source. That is exactly the added context the annotations cannot express.

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

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

Three tight sentences: the destructive action leads, the irreversibility and recovery follow, and the alternative for temporary exclusion closes. No filler, and the most important warning is front-loaded.

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

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

For a single-parameter destructive tool with no output schema and full annotation coverage, the description supplies everything an agent needs: what is destroyed, that it cannot be undone, how to restore, and the non-destructive alternative.

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

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

Schema description coverage is 100% and there is a single parameter, so the schema already documents that 'source' is a source id obtainable from notebook_get_notebook or notebook_add_sources. The trailing 'DELETE /sources/{source}' hints it is a path id but adds little semantic depth, so the baseline 3 applies.

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

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

States a specific verb ('Permanently remove') and resource ('one source from its notebook'), which cleanly separates it from the many sibling delete tools (delete_notebook, delete_note, delete_artifact). It also names the downstream consequence that chat and Studio stop using the source.

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

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

Explicitly routes the agent: use notebook_add_sources or notebook_upload_source to restore, and use notebook_ask with a sources argument when the goal is only to exclude a source from a single answer. That is a clear when-to-use-this vs. when-to-use-an-alternative rule.

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?

Goes beyond the annotations (destructiveHint=false, idempotentHint=false) by disclosing the outcome of non-idempotency: a retry after timeout can create duplicate documents, so the agent must verify Drive first. It also states the return value (document URL) and the rejection behavior for unsupported artifact types.

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 front-loaded sentences plus the endpoint path; every clause carries information (destination mapping, refusal rule, return value, retry hazard) 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?

For a 3-param, no-output-schema export tool, the description covers selection between destinations, artifact eligibility, success output, and failure/retry handling. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema doesn't: the artifact parameter must reference a completed report or data table, tying the artifact's type to the required destination value. Title and id-format semantics are left entirely 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?

States a specific verb ('Export') and resource ('artifact') and precisely maps each destination enum value to the artifact type it accepts, making it distinguishable from siblings like notebook_generate_artifact or notebook_copy_artifacts. The refusal clause ('other types are refused') sharpens scope further.

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

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

Tells the agent which destination to pick for which content type (docs for reports, sheets for tables) and gives a concrete operational rule for timeouts. It stops short of naming an alternative sibling tool for cases where export isn't the right move.

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 (readOnly=false, idempotent=false, openWorld=true), the description discloses genuinely useful behavior: it spends the account's Google usage, occupies a maxJobs slot, and waits only ~50 s before returning a jobid rather than the finished artifact. These cost, concurrency, and async-timing facts are exactly the kind of context annotations cannot express.

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

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

Purpose is front-loaded in the first sentence and the content is packed into a few semicolon-separated clauses with little filler. It is dense and slightly run-on (mixing artifact types, the job model, waiting, cost, and routing in one breath), but no sentence is wasted.

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

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

For a 19-parameter async generator with no output schema, the description is unusually complete: it covers the job model, the ~50 s wait, jobid continuation, and even what a finished job yields (artifact id, download URLs, text or JSON). Only edge cases (failures, retries, cancel semantics) are left to siblings like notebook_cancel_job and notebook_retry_artifact.

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 100%, so every one of the 19 parameters already carries its own description, including enum values and per-type applicability. The description adds only the generic line 'Options apply per type (see each option)', which restates what the schema already encodes, so the baseline 3 is warranted.

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 gives a precise verb and resource and enumerates all ten artifact types it can produce (audio, video, report, table, quiz, etc.), so an agent knows exactly what it generates. It also distinguishes itself as asynchronous ('as a job'). It stops short of naming the nearest sibling, notebook_generate_suggested_item, whose quiz/flashcards/mindmap overlap leaves a small 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?

It clearly explains the two modes ('With notebook' vs 'One-shot: without notebook, a new notebook is made from urls and/or text') and prescribes the follow-up path (continue with notebook_get_job (wait: true)). That is strong when-to-use guidance, though it never explicitly rules out or routes to the overlapping sibling generate_suggested_item.

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=false/openWorldHint=true/idempotentHint=false. The description adds the key non-obvious trait: this is an asynchronous job whose jobid must be polled via notebook_get_job, matching the notebook_generate_artifact pattern. It also discloses the prompt-source behavior (artifact description vs instructions), which goes beyond the annotations.

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

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

Front-loaded with the action and item types, then the prompt semantics, then the async job contract and the alternative tool. Dense but every clause carries information; the telegraphic fragments ('A job, like notebook_generate_artifact: returns the jobid...') are terse but readable.

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 12-parameter async generation tool with no output schema, the description covers the one thing an agent most needs beyond the schema: that the return value is a jobid routed through notebook_get_job. Missing only details of job completion/failure handling, which the sibling job tools presumably cover.

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 100%, so the baseline is 3. The description rises above it by explaining a semantic the schema cannot: there is no free-form prompt parameter, and the suggested item's description acts as the prompt unless 'instructions' replaces it, with that type's other options applying. That is genuine added meaning.

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

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

States a specific verb (generate) and a precisely scoped resource: one item from an interactive report's embedded suggestion list, with the five item types enumerated (infographic, slides, mindmap, quiz, flashcards). This clearly separates it from notebook_generate_artifact, which builds arbitrary 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?

Implies the trigger condition (the item must be in the report's embedded list with status 'suggested') and names notebook_delete_artifact as the tool for dropping a suggestion, plus notebook_get_job for polling the returned job. It does not explicitly state when to prefer this over notebook_generate_artifact, so the routing is inferred rather than spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description still adds useful context by stating it reads 'live from Google' (freshness, not cached) and by detailing the returned usage/cost fields, though it omits auth/rate-limit details.

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

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

Front-loaded with what it returns, then usage guidance and the alternative, closing with the endpoint. Every clause earns its place 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?

Since there is no output schema, the description carries the burden of describing return values, which it does thoroughly (plan, limits, usage windows, cost, output language). For a single-param read tool with strong annotations, nothing needed for correct invocation 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 100% and the single email parameter is fully documented in the schema, so the description needn't restate it. It only implies the identifier via the GET /accounts/{email} path, adding nothing beyond the schema — baseline 3.

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

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

States a specific verb (Read) and resource (one account) and enumerates the returned fields (plan/tier, limits, 5-hour and weekly usage windows, per-action cost, output language). It explicitly distinguishes itself from the sibling notebook_list_accounts as 'the overview of every account'.

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

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

Gives explicit when-to-use guidance ('Check it before a heavy Studio run') and names the alternative tool (notebook_list_accounts) with the condition that separates them. Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further by disclosing the return shape (verbatim content per artifact type), that files include download urls, and the notable quirk that an infographic or first slide returns as an image rather than text — genuinely useful behavior an agent cannot infer from 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?

Dense but front-loaded: the core read action and its payloads come first, followed by the slide caveat and endpoint. Every clause carries information, though the long enumeration of artifact types borders on list-like density.

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 carries the return-value burden and largely discharges it by enumerating payload types and noting the image-return edge case. It stops short of covering error/empty-artifact behavior or response sizing, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100% and the single 'artifact' parameter is fully documented in the schema (id, sourced from notebook_list_artifacts or a job result). The description adds no syntax, format, or id-resolution detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb (read) and resource (one artifact) and then enumerates exactly what content types come back (files with download urls, report text, quiz JSON, flashcards, mind map, table, slide texts, suggested items). It explicitly distinguishes itself from the sibling notebook_get_slide for accessing slides beyond the first.

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?

Names the alternative for a specific case: 'to see another slide use notebook_get_slide,' and the endpoint hint GET /artifacts/{artifact} clarifies scope. It does not address when to prefer notebook_get_source or notebook_get_note for overlapping content, so routing guidance is present but not exhaustive.

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/idempotentHint/destructiveHint, so safety is covered. The description adds real behavioral context beyond them: turn ordering, the 100-turn ceiling, which conversation is selected by default, and the returned fields. It doesn't say what happens past the 100-turn cap, but the added context is substantive.

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

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

Front-loaded with the core action and scope, then return values, then the alternative. No filler sentences; the trailing 'GET /chat' is a minor technical tag that earns its place by anchoring the endpoint.

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

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

No output schema exists, and the description compensates by naming the returned fields (conversation id, per-turn role and text). Combined with the read-only annotations, an agent has what it needs, though the 100-turn truncation implies pagination that is never addressed.

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

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

Schema description coverage is 100% and both parameters are documented there, including the same 'Default: the latest' note. The description's mention of the latest-conversation default duplicates rather than extends the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read one conversation of a notebook'), plus the scope/ordering ('oldest turn first, up to 100 turns') and the default-selection rule. An agent can distinguish it from notebook_delete_chat, notebook_set_chat_settings, and notebook_ask without opening the schema.

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

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

Gives a clear default rule ('the latest conversation when none is given') and routes to an alternative for a related task ('to keep it as a note use notebook_create_note with conversation'). It does not explicitly contrast with notebook_ask, which is the nearest sibling for conversation-style access, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is largely covered; 'Read-only' is somewhat redundant. The description adds real value beyond annotations by disclosing the prerequisite that chat questions appear only once sources are ready, and by explaining how the returned suggested-report prompts chain into notebook_generate_artifact and notebook_ask.

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

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

A single dense, front-loaded sentence opens with the resource and its contents, then adds the sibling disambiguation and endpoint. Nothing is wasted, though the parenthetical chaining detail makes it slightly heavy for one sentence.

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 carries the burden of describing the return value, and it does so concretely (summary, suggested reports with title/prompt, suggested chat questions). An agent knows what it will receive and how to use it downstream.

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 100% with a single well-documented 'notebook' parameter, so the schema already carries full parameter semantics. The description adds no format or sourcing detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb+resource (get the notebook guide) and enumerates its contents: a cross-source summary, suggested reports with title/prompt, and suggested chat questions. It explicitly differentiates itself from the sibling notebook_get_source, so an agent can pick it correctly without opening schemas.

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?

Names the alternative tool for a related but different need ('For one source's summary and key topics use notebook_get_source') and states a runtime prerequisite ('only once sources are ready'). Both the when-to-use and when-to-use-something-else conditions are covered.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral detail: the ~50 s wait cap and the instruction to call again while the job is still running, which tells the agent this is a polling endpoint rather than a blocking one.

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

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

Front-loaded with the core action and return payload, with the polling guidance and the GET path trailing. The parenthetical artifact enumeration is dense but informative; the sentence is long but 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?

With no output schema, the description carries the return-value burden and does so by listing status, artifact forms, and research results. It does not say what a failed/cancelled job returns or point at notebook_retry_artifact for that case, which is the remaining gap.

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

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

Schema coverage is 100%, so both parameters are already documented (baseline 3). The description goes beyond the schema by explaining the polling pattern implied by `wait` ('call again while it is still running'), which is operational meaning the schema's one-line hint does not convey.

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

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

States a specific verb (read) and resource (a Studio or research job), then enumerates what comes back: status, artifacts with download URLs, text/structured content, images, or research results. This distinguishes it cleanly from notebook_list_jobs (plural, listing) and notebook_get_artifact (single artifact).

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?

'Use it for every jobid another tool hands back' gives an explicit trigger condition, and the wait guidance tells the agent how to poll. There is no explicit when-not or named alternative (e.g. list_jobs vs this), 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing the content format (Markdown text vs. a mind map's JSON tree) and the possible type values, which the annotations cannot convey.

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

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

Two dense sentences, front-loaded with the action and its result set, with no filler. Slightly overpacked with the type enumeration and endpoint reference, but nothing wasted.

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

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

There is no output schema, so the description carries the burden of describing return values and does so by enumerating the fields and their formats. For a single-parameter read tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% for the single 'note' parameter, so the baseline is 3. The description only restates that the id comes from notebook_list_notes and adds the REST path GET /notes/{note}, which is marginal extra meaning.

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

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

States a specific verb and resource ('Read one note by its id') and enumerates the returned fields (title, content, type, timestamps). It also names the sibling it relates to (notebook_list_notes), so an agent can separate retrieval-by-id from listing.

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 reference to notebook_list_notes 'which lists them all and gives the ids' makes the lookup workflow clear: list to discover ids, then get by id. It stops short of an explicit when-not-to-use statement, but the routing to the sibling is strong.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's added value is the payload shape — it lists returned sub-fields and the underlying route GET /notebooks/{notebook}. Since there is no output schema, this return-format disclosure is genuinely useful; it stops short of describing pagination or error behavior, so not a 5.

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

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

Two tight sentences plus the endpoint, front-loaded with the action and payoff ('Read one notebook: ...'). Every clause carries information; 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?

With no output schema, the description compensates by enumerating return fields, and it explains the workflow dependency that motivates the call. For a single-parameter read tool with annotations already covering safety, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single 'notebook' parameter is fully documented in the schema with its id format and provenance (notebook_list_notebooks / notebook_create_notebook). The description adds nothing about the parameter, so the baseline 3 applies.

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?

'Read one notebook' gives a precise verb+resource, then enumerates exactly what comes back (title, sources with id/title/kind/status/words, Studio artifacts with id/type/status/title). That level of detail lets an agent distinguish it from notebook_list_notebooks and notebook_get_source without opening a schema.

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

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

It states concrete use cases: retrieving source ids and verifying new sources reached status 'ready' before calling notebook_ask or notebook_generate_artifact. That is a real when-to-use with named downstream tools, but it gives no explicit exclusion (e.g. when to prefer notebook_get_source or notebook_list_notebooks instead).

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the response shape (per-person email/role/name, link access, allowCopies) and the underlying GET /sharing endpoint, which the annotations cannot convey.

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

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

One front-loaded sentence covering purpose and returns, followed by a short routing clause to the alternative. Every clause earns its place with no padding.

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

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

With no output schema, the description correctly carries the burden of describing return values and does so concretely. For a single-parameter read tool whose annotations cover safety, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the single notebook parameter is fully documented in the schema, including its id format and source tools. The description adds no further parameter detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Read who a notebook is shared with') and enumerates the exact fields returned (email, role, name, link access, allowCopies). It is immediately distinguishable from the sibling notebook_set_sharing, which it explicitly names as the mutation counterpart.

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?

Clear context for use and names the alternative explicitly ('change it with notebook_set_sharing'). It does not spell out a when-not condition beyond the read/write split, so it falls just short of the explicit when/when-not/alternatives bar.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine value by clarifying the return is the image itself and not a url, plus the underlying GET endpoint. It omits auth or rate-limit details.

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

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

Front-loaded with the core action, then the infographic variant, then the return-format caveat and the sibling pointer. Slightly dense with the trailing endpoint string, but every sentence earns its place.

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

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

No output schema exists, so the description correctly states what comes back (image, not url). Combined with annotations covering the safety profile and the schema covering params, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents slide ('Omit for an infographic'), width, and artifact. The description only reinforces the infographic/width relationship, adding little beyond structured fields, so baseline 3 applies.

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

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

States a specific verb and resource: 'See one slide of a slide deck as an image.' It also explicitly distinguishes itself from the sibling notebook_get_artifact ('for the deck's files and every slide's text use notebook_get_artifact'), so an agent can route without opening either schema.

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

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

Gives a clear trigger ('after notebook_revise_slide') and names the alternative sibling for the other use case (getting files and slide text). It stops short of a full when-not set or prerequisites, but the routing context is explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new context: the guide is only populated 'once it is ready', inSync applies specifically to Drive sources, and content: true can return very long text. It does not mention pagination or truncation on the long-text path, which is the one remaining gap.

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

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

Front-loaded with the resource and what is returned, followed by the routing hint and the endpoint. Dense but not padded; it is a single long sentence with a parenthetical, so it reads slightly run-on without any wasted clauses.

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 carries the return-value burden and does so by naming the fields returned (title, kind, status, word count, guide topics, inSync). Combined with the safety annotations and full parameter coverage, an agent has everything needed to call this 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 100%, so both parameters are already documented, but the description adds value the schema does not: it implies the default response is metadata-only and explains that the content flag yields 'the full text Google indexed (can be long)', flagging a size/cost consideration the schema omits.

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

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

States a specific verb and resource ('Read one source') and enumerates exactly what comes back: title, kind, status, word count, guide, inSync, and optional full text. It also names the sibling it is not (notebook_search_sources), so an agent can distinguish it without opening any schema.

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

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

Explicitly routes the agent elsewhere for the adjacent use case: 'To find passages matching a query use notebook_search_sources instead.' It also states the condition that changes behavior (content: true), so both the when and the how are 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 non-idempotent, non-readonly, open-world behavior, and the description reinforces this with the concrete consequence 'Importing twice adds the sources twice' plus a timeout/retry protocol. It also promises the return value (new source ids). Auth/permission requirements are not covered, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the core action and followed by return value and the critical non-idempotency warning. The trailing 'POST /research/import' is low-value API trivia but negligible overhead.

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 usefully states the return (new source ids) and covers the main hazard (duplicate imports on retry). For a 3-param mutation tool this is nearly complete; only auth/permission context is absent.

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

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

Schema description coverage is 100%, so the schema already defines jobid, urls, and report defaults. The description paraphrases 'all, or the urls you pick' and the Deep Research report case without adding format or syntax detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (add/import) and resource (sources a completed research job found, plus a Deep Research report). This is clearly distinguishable from siblings like notebook_add_sources, notebook_upload_source, and notebook_research, since it consumes the output of a completed job.

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?

Scopes usage to 'a completed research job' and gives a concrete operational rule (check notebook_get_notebook on timeout before retrying). It stops short of explicitly naming alternatives such as notebook_add_sources or notebook_upload_source for manually adding sources.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint false), so the description does not need to restate them. It adds useful scope and output context by saying it lists every account for the token and enumerates returned fields (health, plan limits, maxJobs, running jobs, last known usage), which is valuable because there is no output schema. It does not address pagination or rate limits, so it falls short of a 5.

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

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

The description is three compact sentences, front-loading what the tool returns and the scope before routing guidance. Every sentence earns its place, including the concise 'GET /accounts' endpoint note.

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 no parameters, no output schema, and rich read-only annotations, the description provides everything an agent needs: the account scope, the returned fields, the sibling alternative, and the HTTP endpoint. Nothing critical is missing for a simple list operation.

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

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

The tool takes zero parameters, so the schema cannot carry parameter semantics. Per the rubric, a parameterless tool has a baseline of 4, and the description appropriately does not invent parameter details that do not exist.

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 and resource ('List every Google account') and scopes it to accounts added to the current useapi.net API token for Gemini Notebook. It also explicitly distinguishes this bulk-list operation from the single-account sibling notebook_get_account.

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 direct usage guidance: 'Start here to find the email other tools take,' which tells the agent when this is the right entry point. It also names the alternative for a different need: 'for one account's live plan and usage windows use notebook_get_account.'

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value beyond them by disclosing that only metadata is returned (no content) and that suggested items live elsewhere, plus the underlying endpoint. It stops short of describing ordering or pagination behavior.

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 sentences: purpose and field list first, then the alternative for content, then the report exception. Every clause carries distinct information with no padding.

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

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

For a simple metadata list tool with one fully documented parameter, this is complete. Although there is no output schema, the description itself enumerates the returned fields, so an agent knows what the response will contain.

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 100% and the single notebook parameter is fully documented in the schema, including its id format and where to obtain it. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource (List a notebook's Studio artifacts) and enumerates exactly which fields come back (artifact id, type, status, title, created). It is immediately distinguishable from the sibling notebook_get_artifact, which returns content rather than metadata.

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

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

Explicitly routes the agent: 'No content: use notebook_get_artifact for files, text and JSON.' It also carves out the edge case that an interactive report's suggested items are not listed here and must be fetched via notebook_get_artifact on the report. When-to-use and when-to-use-something-else are both stated.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered by structured data. The description goes beyond them with genuinely useful context: it explains what a collection is, what fields come back, and explicitly reassures that 'nothing in a notebook changes' when listing collections. It omits pagination and volume behavior, so not a full 5.

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

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

A single compact sentence, front-loaded with the verb and a definition of the resource, then the returned fields, the scope, and the non-mutation guarantee. Every clause earns its place; the trailing 'GET /collections' is a cheap, mildly useful anchor.

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

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

There is no output schema, so the description compensates by enumerating the fields returned (collection id, name, emoji, notebook ids). Combined with annotations that cover the safety and idempotency profile and a fully documented single parameter, an agent has everything needed to call this 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?

Only one parameter exists and schema description coverage is 100% ('The account. Default: every account.'), so the schema already carries the semantics. The description restates the same one-account-or-all-accounts scope without adding format, accepted identifiers, or lookup guidance, making it largely redundant. Baseline 3 applies.

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

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

States a specific verb (list) and resource (collections), then defines the resource itself ('the folders an account groups its notebooks in') and enumerates the returned fields (id, name, emoji, notebook ids). The 'list vs create/update/delete collection' distinction is unambiguous against the sibling tools without opening any schema.

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

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

The description tells the agent the scope choice ('for one account or every account'), which is the only real decision point for this call. However, it names no alternatives or exclusions and gives no guidance on when a caller should prefer notebook_list_notebooks or notebook_get_notebook instead; usage is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds useful behavioral context beyond that: it enumerates what is returned per job and per account and explicitly states that finished jobs are excluded. Missing only edge details like pagination or auth scope.

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

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

Front-loads the action and scope in the first clause before adding return-field detail, then closes with the exclusion and the alternative. Two dense sentences 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?

With no output schema, the description compensates by enumerating returned fields (jobid, type, start time, artifact, account health, maxJobs, running count, usage). It is complete enough to call correctly, though a note on result size or pagination would round it out.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a 0-param tool is 4, and the description correctly implies the endpoint takes no filtering arguments (GET /jobs).

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

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

States a specific verb (List) and resource (jobs) with explicit scope: jobs the token is running now, grouped per account. It enumerates the returned fields and names the sibling for the excluded case (finished jobs → notebook_get_job), so an agent can distinguish it from neighbors without opening a schema.

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

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

Clearly scopes usage to currently-running jobs and routes finished-job reads to notebook_get_job with a condition. However, it does not address potential overlap with notebook_get_account, which also exposes account health/maxJobs/usage fields, so one sibling overlap is left unaddressed.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and openWorld, so the safety profile is established. The description adds genuinely useful context beyond that: the exact fields returned and the underlying endpoint (GET /labels), which matters since there is no output schema.

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

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

Three tight sentences, front-loaded with purpose, followed by the cross-references and endpoint. Every clause earns its place with no 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 read-only list tool with no output schema, the description covers purpose, returned fields, and alternatives adequately. It could note ordering or pagination behavior, but nothing essential to invocation is missing.

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

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

Schema description coverage is 100%, and the single 'notebook' parameter is fully documented in the schema with format and source tool. The description adds no parameter syntax or format details beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('labels'), then defines them functionally: 'labels that group a notebook's sources by topic,' and enumerates returned fields (id, name, emoji, source ids). It also names the sibling write tools, so an agent can distinguish it from create/update without opening a schema.

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

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

Provides clear context for when to use it (to list labels for a notebook) and routes to notebook_create_labels and notebook_update_label for the mutation cases. It stops short of an explicit 'when not to use' or pagination caveat, so it is clear but not exhaustively directive.

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

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

Annotations already cover read-only/idempotent/destructive safety, so the description adds genuinely new behavior: no paging, and the important partial-failure contract that an unreadable account is reported under 'Not listed' rather than failing the call. That failure-mode disclosure is non-obvious and valuable.

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

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

Front-loaded with the verb+resource, then scope, then return fields, then the failure contract, then the alternative. Three tight sentences, no filler, every clause carries 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?

No output schema exists, and the description compensates by enumerating returned fields and the partial-failure behavior. For a single-parameter read-only list tool, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and already documents the email parameter with its 'Default: every account' semantics. The description restates that scope but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List notebooks') plus the exact fields returned (id, title, emoji, source count, timestamps), and explicitly distinguishes itself from notebook_get_notebook. An agent can tell it apart from siblings like notebook_list_accounts or notebook_get_notebook without opening a schema.

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

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

Clearly frames scope ('one account or every account of this API token') and routes the agent to notebook_get_notebook for a single notebook's sources and artifacts. It lacks explicit when-not guidance relative to other list tools, but the alternative routing is concrete.

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 readOnly/idempotent/non-destructive, so the bar is lower. The description adds genuinely useful traits beyond that: no pagination, full content included, and the exact shape of the returned content (Markdown vs. mind map JSON tree), which matters for a listing tool that could otherwise be assumed to be summary-only.

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 sentences, front-loaded with the primary action and scope, followed by the alternative. No filler and every clause carries information.

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

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

With one parameter, no nested objects, and no output schema, the description compensates by enumerating the returned fields and content formats. Complete enough to call correctly; slightly richer detail on result volume or ordering would push it higher.

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

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

Schema description coverage is 100% and the schema documents the sole 'notebook' parameter including its id format and provenance. The description contributes nothing beyond what the schema already says, so baseline 3 applies.

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

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

States a specific verb and resource (list every note of a notebook) plus the scope (no paging, full content) and enumerates the returned fields. It clearly distinguishes itself from notebook_get_note, so an agent can route without inspecting schemas.

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

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

Explicitly names the alternative and the condition that selects it: 'Use notebook_get_note to re-read one note you have the id of.' There is no explicit when-to-use trigger for this tool itself (e.g., after listing notebooks), but the sibling routing is unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is to add context — which it does by explaining the 'addable' flag and that books Google refuses as a source include a reason. It also exposes the underlying endpoint (GET /sources/books). No pagination or rate-limit detail, keeping it short of a 5.

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

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

Three tightly packed sentences, front-loaded with purpose and followed by field list, usage routing, and endpoint. Every sentence earns its place, though the field enumeration is slightly dense.

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 carries the return-value burden and does so fully: it names the fields returned and explains the conditional refusal reason. Nothing an agent needs to call and consume this tool correctly is missing.

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

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

Schema coverage is 100% with a single, fully documented optional email parameter. The description adds nothing about the parameter, so the baseline 3 applies — the schema does all the work here.

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

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

States a specific verb (List) and resource (Google Play Books library / ebooks the account owns), and enumerates the returned fields (book id, title, authors, addable, refusal reason). This is clearly distinguishable from sibling list tools like notebook_list_notebooks or notebook_list_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?

Explicitly routes the agent to the right follow-up: 'Pass the ids with addable: true to notebook_add_sources books,' implying the tool is used to discover sources before adding them. No explicit when-not guidance or comparison against alternatives, but the downstream condition is concrete.

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 flag this as a non-idempotent, non-destructive write (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true). The description adds real value beyond that: it says a new Markdown source is created, that title and text are copied from the note, that chat and Studio consume it, and that the response carries the new source id and status — important since there is no output schema. It does not state whether the original note is preserved or what happens on repeated calls.

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 compact sentences, front-loaded with the core transformation, then the return values, then the sibling disambiguation. The trailing 'POST /notes/source' is mild implementation detail that earns little for an agent, but the rest is tight and waste-free.

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 single-parameter conversion tool with annotations present and no output schema, the description covers the operation, the result artifact, the response fields, and the alternative tool. The remaining gap — behavior on repeat calls and whether the note survives — is minor but non-zero for a non-idempotent write.

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

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

Schema description coverage is 100% and the single parameter already documents 'Note id, from notebook_list_notes.' The description adds nothing about the note parameter itself (no format, no mention that the id must belong to the same notebook), so the baseline 3 for schema-covered parameters is appropriate.

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

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

States a specific verb and resource ('turn a note into a source of the same notebook') and immediately explains what the transformation produces (a Markdown source from the note's title and text). It also names the sibling notebook_add_sources and the case where that sibling applies, so the agent can distinguish the two without opening either schema.

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

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

Explicitly routes the agent: use notebook_add_sources when the content 'is not a note yet', implying this tool is for existing notes. That is a clear selection rule, though it stops short of stating prerequisites (e.g. the note must already exist and belong to this notebook) or any exclusions such as repeat-conversion behavior.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the rename is title-only with content unchanged, the character ceiling is 200, and the return payload is the artifact id plus new title. It does not mention auth requirements or failure modes, but for an idempotent rename that is a minor gap.

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

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

Three tight sentences: action and invariant first, then return value, then sibling routing and endpoint. No filler and nothing buried.

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 correctly compensates by stating the return value (artifact id and new title). Two required parameters are fully documented, annotations cover the mutation profile, and sibling disambiguation is present. Nothing needed to call this tool correctly is missing.

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

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

Schema description coverage is 100% and maxLength=200 is already encoded in the schema, so the description's restatement of the limit and 'New title' adds little. The only marginal value is reinforcing that the artifact parameter identifies an existing artifact, which the schema's 'from notebook_list_artifacts or a job result' note already covers. Baseline 3 applies.

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

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

States a specific verb and resource ('Set the title of a Studio artifact') and immediately bounds scope with 'its content is unchanged'. It explicitly distinguishes itself from the two nearest siblings, notebook_rename_notebook and notebook_rename_source, so an agent can route without opening any schema.

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

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

Names the alternative tools by name and states the condition that selects them (notebook or source instead of a generic artifact). The 200-character limit and the fact that only the title changes are stated up front, leaving little to inference.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds value beyond that: it confirms sources and artifacts are untouched (blast-radius scoping) and discloses the return payload (notebook id and new title). It does not mention permission/auth requirements, so it falls short of a 5.

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

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

Three tight clauses, front-loaded with the action and scope, followed by routing and return value. The trailing POST path is minor overhead but no sentence is wasted.

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

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

No output schema exists, yet the description states what is returned (notebook id and new title) and what is not affected. For a simple two-param rename, nothing needed for correct invocation 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 100% and both parameters are documented in the schema, including the notebook id format and the 200-char maxLength. The description repeats the length limit but adds no new syntax or format meaning, so baseline 3 applies.

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

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

States a specific verb+resource (set a notebook's title) with a scope qualifier (200 char limit, sources and artifacts untouched). It explicitly names the two sibling rename tools it is not, so an agent can route without opening schemas.

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

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

Gives explicit alternatives with the selecting condition: 'For a source or an artifact use notebook_rename_source or notebook_rename_artifact.' This resolves the primary ambiguity among the three 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?

Annotations already declare idempotent=true and destructive=false; the description reinforces this by stating content, labels and citations are unchanged, which is valuable reassurance for a title mutation. It also discloses the return value ('Returns the source') despite there being no output schema. It does not mention permission requirements or failure modes.

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 sentences plus an endpoint: the mutation and its scope come first, the alternative routing second, and nothing is wasted. No filler or redundant restatement of the tool name.

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

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

For a two-parameter, non-destructive mutation with no output schema, the description covers the effect, the non-effects, the size limit, the return value, and the alternative tool. Only edge cases like permission failures are absent, which is minor at 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 100% and both parameters carry descriptions, so the schema already does the heavy lifting. The description's 200-character note simply restates the schema's maxLength rather than adding format or syntax guidance, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Set a source's title') plus the scope of the change (up to 200 characters). It also names the sibling it is not (notebook_append_to_source) for text changes, so an agent can distinguish it from the other rename/update tools without opening a schema.

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

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

Gives a clear when-to-use condition and explicitly routes text edits to notebook_append_to_source, which is the most likely confusion point among siblings. It stops short of a full when-not list (e.g., title-only vs. label updates), but the essential alternative is covered.

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

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

Annotations only cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false). The description adds the genuinely non-obvious behavioral facts: this is an asynchronous job, it times out at roughly 50 seconds and returns a jobid to poll, and nothing lands in the notebook until a separate import call. That is exactly the context an agent needs and cannot get from the annotations.

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

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

Front-loaded with the purpose and dense with distinct facts; every clause carries information. The semicolon-heavy, telegraphic packing ('A job: waits up to ~50 s, then returns the jobid') trades a little readability for compactness, keeping it just short of ideal.

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

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

There is no output schema, so the description correctly supplies the return contract (a jobid after up to ~50 s) and the polling path via notebook_get_job. Combined with the import prerequisite, an agent has everything needed to invoke and follow through 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 100%, so the schema already defines the four optional/required parameters, and baseline would be 3. The description earns above baseline by attaching operational meaning to the enum values — Discover timing, the deep-mode written report, and the drive-only-works-with-fast constraint, the latter of which appears nowhere 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?

States a specific verb and resource ('find new sources for a notebook') and immediately qualifies it with the two modes and two source types. It also names the follow-up siblings (notebook_get_job, notebook_import_research), so an agent can place it precisely in the workflow without reading other schemas.

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

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

Gives explicit selection criteria for both enums ('fast ... usually under a minute' vs 'deep ... a few minutes', 'web or drive ... fast only') and names the follow-up tools. It stops short of stating when NOT to use this tool versus alternatives like notebook_add_sources or notebook_search_sources, so it falls just below the top mark.

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?

Goes well beyond the annotations by disclosing wait behavior (~50 s), the exact return value and follow-up call (jobid for notebook_get_job), and two material side effects: it spends the account's usage again and occupies a maxJobs slot. This is the kind of cost/capacity information annotations cannot express.

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 sentences, front-loaded with the core action, then side effects, then the routing alternative; the raw endpoint is appended at the end. 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?

No output schema exists, so the description compensates by explaining the return value (jobid) and the follow-up tool. Preconditions, side effects, and the alternative path are all present, leaving nothing an agent needs to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a meaningful constraint tied to the required artifact parameter ('only status failed is accepted'). The optional replyRef is left to the schema, which is acceptable given full 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?

States a specific verb and resource ('Generate a failed artifact again with its original settings, as a job') and distinguishes itself from the sibling notebook_generate_artifact. The agent can tell exactly what this tool does without opening the schema.

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

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

Explicitly names the precondition ('only status failed is accepted') and the alternative for other needs ('for different options use notebook_generate_artifact'). Both the when and the when-not are covered.

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

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

Annotations already declare the mutation/open-world/non-idempotent profile, and the description adds substantial context on top: it runs as a job, waits ~50 s then hands back a jobid, revisions often take minutes, and critically that Google produces a NEW artifact with its own id while the original stays. This async-job and non-destructive-output detail is exactly the value annotations cannot convey.

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

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

Four dense sentences, each earning its place: core action, artifact-creation semantics, wait/return behavior, and sibling routing plus endpoint. The primary action is front-loaded with zero 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?

With no output schema, the description fully carries the return contract (jobid for polling, job record names the new artifact id) and explains timing expectations. Nothing an agent needs in order to call and follow up correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the change is driven 'from a prompt' and that the job result names the new artifact id, but adds no syntax or format detail for slide/artifact/replyRef beyond what the schema already documents.

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

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

States a specific verb+resource: 'Change one slide of a completed slide deck from a prompt.' It distinguishes itself from siblings by routing to notebook_get_slide to inspect the slide and notebook_get_job for the async result, so an agent can tell it apart without opening the schema.

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

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

Provides clear next-step routing (use notebook_get_job with wait:true, or notebook_get_slide to view). Implies the deck must be 'completed' and that revisions are slow, but does not explicitly state when NOT to use this versus a full regeneration or other artifact tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine return behavior: results come 'best first' and each carries source id, text, and offsets that appear only 'when Google gives them', disclosing variability the annotations cannot. It stops short of rate limits or pagination details, so not a 5.

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

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

Two dense sentences plus the endpoint. The scope/result shape is front-loaded, then the sibling routing, with no filler; every clause carries information.

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

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

For a read-only search with no output schema, the description supplies the essentials an agent needs: what is returned (source id, text, optional offsets), ordering (best first), scoping (notebook's sources), and the sibling alternative. Nothing critical 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 100%, so all four parameters (limit, query, sources, notebook) are documented in the schema and the description need not compensate. The description adds only the best-first ordering and result shape, not parameter syntax or defaults, so the baseline 3 applies.

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

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

States a precise verb (Find) and resource (passages of a notebook's sources) and immediately distinguishes itself from the sibling notebook_ask by scope. An agent can tell it apart from notebook_ask and notebook_get_source without opening any schema.

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

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

Explicitly says 'Raw passages only, no AI answer and no chat usage' and names the alternative and its selecting condition ('for an answer with citations use notebook_ask'). Nothing about when-to-use is left to inference.

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

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

Annotations cover the safety profile (idempotent, non-destructive), but the description adds the non-obvious partial-update rule: the two settings are stored together, so omitting one resets it to default. It also notes the return ('saved settings') and the underlying POST endpoint, giving real behavioral context beyond the annotations.

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

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

Front-loads the purpose, then the settings, then the storage caveat; every clause carries information. Slightly run-on with the parenthetical enum list, but no wasted sentences.

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

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

With no output schema, the description compensates by stating it returns the saved settings. Combined with the reset semantics and endpoint, an agent has enough to call it correctly; only explicit read-back guidance is missing.

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

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

Schema description coverage is 100%, so baseline would be 3. The description exceeds that by explaining a cross-parameter rule the schema cannot: 'custom takes a persona, and a persona alone means custom,' clarifying the goal/persona interaction.

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

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

States a specific verb+resource: setting how notebook_ask answers in this notebook, enumerating exactly the two settings (goal and answer length) it controls. It also names the consuming sibling (notebook_ask), so an agent can distinguish it from the many other notebook_* 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?

Makes the temporal scope explicit ('for the questions that follow'), which tells the agent this must be set before asking. It does not name a read/alternative sibling (e.g., notebook_get_chat) or state exclusions, so it falls 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 declare write/idempotent/non-destructive, and the description adds substantial behavior beyond them: the owner cannot be changed, going restricted resets allowCopies to allowed, added people are emailed unless notify is false, and the current sharing is returned. These are exactly the side effects an agent needs before invoking a mutation.

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

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

One front-loaded sentence plus a return statement and endpoint, with no filler. It is dense with parentheticals, which slightly taxes readability, but every clause carries operational meaning.

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

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

For a 6-parameter mutation tool with no output schema, the description covers what changes, the constraints on each field, the default notification behavior, and what is returned. Nothing an agent needs before calling it 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 100%, so the baseline is 3; the description goes further by stating cross-parameter constraints the schema lacks: allowCopies applies only to public links and resets when restricted, viewLevel 'chat' requires a paid plan, and the owner entry is immutable. Only the notebook id parameter is left 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?

States a specific verb and resource ('Share a notebook or change its sharing') and then enumerates every mutation surface: people roles, link access, allowCopies, viewLevel. An agent can immediately distinguish this from the read-only sibling notebook_get_sharing.

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 context of use is clear: it both creates sharing and changes it, and it returns the resulting state. It does not explicitly name an alternative (e.g., notebook_get_sharing for reading without mutation) or state when not to use it, so it stops short of full routing 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 idempotent, non-destructive, open-world behavior; the description usefully reinforces this by disclosing the no-op return ('synced: false when it was already up to date') and the refusal mode for unsupported source types. It omits permission/auth requirements and whether sync is synchronous or long-running, which would be the remaining valuable context.

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

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

Two tight sentences: the action and its eligibility constraint come first, the return-value edge case second. The trailing 'POST /sources/sync' is minor plumbing but costs almost nothing and aids debugging.

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 does describe the meaningful return value (synced: false on a no-op) and the error case, and annotations carry the safety profile. It leaves the mechanics of a sync and any auth or long-running-job behavior unstated, but nothing essential for a correct call 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?

There is only one parameter and schema coverage is 100%, with the schema already stating where the source id comes from (notebook_get_notebook or notebook_add_sources). The description adds no format, prefix, or validation detail about the id, so baseline 3 applies.

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

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

States a specific verb ('Re-import') and resource ('a Google Drive source') with the constraint that only Docs/Drive files qualify. It is clearly separable from siblings like notebook_upload_source or notebook_add_sources, which create sources rather than refresh an existing one.

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

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

Explicitly gives the triggering condition ('after its file changed in Drive'), the exclusion ('other kinds of source are refused'), and a precondition check ('notebook_get_source shows inSync beforehand'). An agent knows both when to call it and which sibling to consult first.

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 idempotent=true, destructive=false and readOnly=false, so the description carries less burden, yet it still adds value: unspecified fields are preserved, the response is the account's settings, and the endpoint is POST /accounts. It also flags that maxJobs is 'kept by useapi.net', a non-obvious cross-tool side effect.

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?

One dense paragraph, front-loaded with the mutation target and the partial-update rule. Parenthetical glosses earn their place, though the prose is slightly overloaded and could break cleanly into a params line plus a behavior line.

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

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

No output schema exists, but the description states the return ('the account's settings') and the write semantics are covered by annotations plus the partial-update rule. Enough for an agent to call this correctly; only an explicit confirmation of auth/rate-limit expectations is absent.

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 100%, so the baseline is 3, but the description genuinely enriches both optional params: maxJobs is scoped to concurrent Studio+research jobs, and outputLanguage is described as the account-wide Google setting all Studio artifacts inherit, which is more than the schema's terse 'Language code for Studio output'.

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

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

States a specific verb (change/update) and resource (account) and names the exact mutable fields (maxJobs, outputLanguage). An agent can immediately distinguish it from notebook_get_account and notebook_list_accounts, which read rather than mutate.

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?

'Give at least one; the other keeps its value' explicitly defines the partial-update contract, so the agent knows it may supply either or both fields. It doesn't name a sibling alternative, but the when-to-use context is otherwise clear for a partial-updater.

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=false, destructiveHint=false and idempotentHint=true, so safety is largely covered. The description adds real behavioral value beyond that: partial-update semantics ('fields left out keep their values'), a non-obvious side-effect guarantee ('the notebooks themselves are not changed'), and the return payload shape despite there being no output schema.

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

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

Front-loaded with the purpose and tightly packed: multi-field capabilities, patch semantics, return value, id source and the delete alternative are all covered in a few clauses. The trailing 'POST /collections/{collection}' is slightly redundant given the name and prevents a 5.

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

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

For a 5-parameter mutation with no output schema, the description supplies both the return shape and the partial-update contract, and annotations carry the safety profile. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including the same-account constraint on addNotebooks and the non-deletion note on removeNotebooks. The description's 'fields left out keep their values' adds useful optionality semantics, but it is not per-parameter detail beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb (update) plus the exact resource and the distinct field-level operations available: rename, change emoji, add/remove notebooks. This lets an agent separate it from siblings like notebook_create_collection, notebook_delete_collection and notebook_rename_notebook.

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

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

Gives the source of the required id ('from notebook_list_collections'), an explicit alternative for the different intent ('to remove the folder itself use notebook_delete_collection'), and the scope constraint (notebooks must be of the same account). The when-to-use-vs-alternative routing is fully explicit.

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

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

Annotations already cover the safety profile (readOnly=false, idempotent=true, destructive=false), but the description adds materially non-obvious behavior: omitted fields are preserved, mutations apply one-by-one, and a partial failure reports how many succeeded. It does not cover auth or rate limits, so it is strong on the failure semantics but not exhaustive.

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

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

Front-loaded with the verb and resource, then layered with usage, failure behavior, and return value. Dense but each clause carries information; slightly long as a single paragraph but 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?

For a 5-param mutation tool with no output schema, the description covers the operation, optionality, failure semantics, and even states the return shape (name, emoji, source ids). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: 'fields left out keep their values' clarifies the optional/partial-update semantics, and the note that removed sources 'stay in the notebook' disambiguates removeSources from deletion.

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

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

States a precise set of operations (rename, change emoji, add/remove sources) on a specific resource (source label), immediately distinguishing it from create/delete label siblings. An agent can tell it is a partial-update tool without opening the schema.

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

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

Gives concrete use scenarios ('fill a label made with notebook_create_labels name', 'correct Google's auto labels') and names a sibling tool by name. It stops short of explicit when-not/alternative routing (e.g., delete_label vs this), so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, open-world. The description adds real semantics beyond them: omitted fields retain their value, and new content replaces rather than appends. It also states the return payload. No auth/permission or failure behavior is disclosed, so not a 5.

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

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

One tightly packed sentence with zero filler, front-loaded on the mutation itself, followed by the return value and endpoint. Every clause carries distinct information.

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

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

For a three-parameter mutation tool with no output schema, the description covers what changes, how omission is handled, and what is returned, while annotations carry the safety profile. Only permission and error-handling behavior are left unstated, a minor gap at 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 100%, so baseline is 3, but the description adds a constraint the schema does not encode: at least one of title/content must be supplied even though only 'note' is required. It also clarifies replacement semantics that the schema's 'New content' wording leaves ambiguous.

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

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

States a specific verb (change) and resource (a note's title and/or content), plus the transport endpoint POST /notes/{note}. An agent can distinguish this from notebook_create_note, notebook_get_note, and notebook_delete_note without opening any schema.

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

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

Gives the operative invocation condition ('give at least one' of title/content) and frames the tool as a partial update of an existing note, which routes the agent away from create_note. It never names a sibling alternative or a when-not case explicitly, 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 cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), but the description adds genuinely useful behavior the annotations cannot: the call is async, returning a source id in 'preparing' status, and the agent must poll notebook_get_notebook until it is ready. It stops short of describing failure modes 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?

Front-loads the core action and constraints, then sequences the routing advice and the async-follow-up instruction. The file-type enumeration is long but scannable and directly serves selection, so no sentence is wasted.

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

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

For a 5-parameter upload tool with no output schema, the description covers input selection (url vs contentBase64), supported formats, and the return/post-call workflow (source id + preparing status + polling via notebook_get_notebook). Nothing an agent needs to invoke and follow up correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema: the url/contentBase64 pair is mutually exclusive ('not both'), and it flags contentBase64 as the small-file path and url as capped at 50 MB. That constraint is not expressed 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?

States a specific verb and resource ('Add a file as a source') and enumerates exactly what kinds of files qualify (PDF, Word, PowerPoint, EPUB, Markdown, text, CSV, audio, video, image). It also names the sibling notebook_add_sources as the wrong tool for other content, so an agent can disambiguate without opening either schema.

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

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

Explicitly routes the agent: use this tool to add files via url or contentBase64, and use notebook_add_sources for 'web pages, YouTube, text or Drive'. It also gives the mutual-exclusion rule ('not both') and the size hint (up to 50 MB), leaving little to inference.

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