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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description still adds useful context that the call is 'free and quick' and that returned names feed into gemini_code's `agent` parameter. It also discloses the empty-state message, which helps an agent interpret a sparse result.

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

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

Front-loaded with purpose, then usage, then returns; two short paragraphs with little waste. The 'Returns' block is partly redundant with the declared output schema, but the empty-state string and the handoff to gemini_code earn most of its space.

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 parameterless, read-only discovery tool with an output schema, the description covers what it lists, when to use it, and what an empty result looks like. Nothing essential for correct invocation appears to be 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?

Zero parameters, so this dimension is at its baseline; the schema is trivially complete. The description does not need to explain any input, and the note about passing a name as `agent` to gemini_code clarifies downstream usage without inventing input semantics.

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

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

States a specific verb and resource ('List the custom Antigravity agents the user has made or installed') and gives a concrete example ('reviewer' or 'test-writer' agent with its own instructions), which differentiates it from generative siblings like gemini_code.

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 to call it before gemini_code when the user wants a task done by a specific agent, giving a clear trigger and ordering relative to the main sibling. It stops short of stating when not to call it (e.g., no need for discovery if the user already named an agent).

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, but the description adds real behavioral context beyond them: Gemini runs in a sandbox, can read only the supplied paths and search the web, and cannot change files or run commands. It also discloses the cost/quota model (no API cost, consumes the plan's limits), which matters for how freely an agent should call it. It does not discuss latency or nondeterminism, 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?

The core routing information is front-loaded in the first two paragraphs, and the Args/Returns block is cleanly structured. The Args section repeats parameter names already visible in the schema, but in each case it attaches semantics rather than restating types, so almost every line earns its place.

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

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

For a five-parameter delegation tool with no schema descriptions, the definition covers purpose, use cases, alternatives, sandbox constraints, quota implications, every parameter, and the return contract (answer plus a conversation_id for follow-ups). Nothing an agent needs to invoke it correctly is missing, and the output schema handles return structure.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: prompt (the question or task), model (id from gemini_models with a concrete example and the default resolution rule), paths (local files or folders Gemini may read), conversation_id (continue an earlier chat), and effort (enumerated low/medium/high/xhigh/max). Every parameter gains meaning the bare schema titles do not 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?

The description states a specific verb and resource ('Ask Gemini a question or give it a reading task') and immediately names the execution path (Antigravity CLI on the user's Google AI Pro plan). It explicitly distinguishes itself from gemini_research (cited web sources) and gemini_code (editing a folder), so an agent can route without opening sibling 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?

It names concrete use cases ('a second opinion on code or a design, reviewing local files or folders passed in paths, and long reasoning') and gives explicit exclusions with named alternatives: use gemini_research for cited web research, gemini_code to let Gemini edit a folder. It also explains that conversation_id continues an earlier gemini_ask/gemini_research chat, which is when-to-use guidance for that parameter.

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 destructive/openWorld/non-idempotent, and the description adds concrete operator guidance beyond them: tell the user before running, review with `git diff` afterwards, terminal commands are sandboxed, only the given folder is writable, no API cost, and a failure mode (error if the folder does not exist). This is unusually rich behavioral context for a mutating tool.

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

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

Front-loaded with the most important fact (this changes files) followed by safety guidance, then fit, then parameters. Dense and mostly waste-free, though the Returns block partly restates what the output schema already carries.

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?

Covers the mutation risk, sandbox constraints, prerequisites for optional parameters, sibling routing, and error behavior — everything needed to call a destructive six-parameter tool correctly. An output schema exists, so the brief return summary is sufficient rather than a gap.

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

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

Schema coverage is 0%, so the description must carry the full load and does: task is defined as change-plus-done-criteria with an example, folder as an absolute path that Gemini may edit, model and agent are tied to gemini_models/gemini_agents with omission semantics, effort enumerates its five values, and conversation_id explains continuation across both gemini_code and gemini_ask.

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 ('Delegate a coding task to Gemini') plus the exact scope: reads and edits files in one local folder via the Antigravity agent. It explicitly names the siblings it is not (gemini_ask for read-only, jules_start for GitHub PR tasks), so an agent can disambiguate 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 positive guidance ('Good for a well-defined change: fix a bug, add tests, refactor a module') and explicit exclusions routed to named alternatives. The follow-up path via conversation_id is also framed with a concrete use case ('to ask for fixes to the previous change').

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description still adds cost and latency characteristics ("free and quick") plus the crucial chaining instruction that the returned id feeds the `model` parameter of gemini_ask, gemini_research and gemini_code. It stops short of stating pagination, quota, or what happens on an empty model list.

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

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

Front-loaded with purpose, then usage rule, then return shape; two tight sentences plus a Returns block, with zero filler. The Returns block slightly duplicates information an output schema may already carry, but it earns its place by showing the id-to-`model` handoff.

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

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

For a zero-argument, read-only discovery tool with an output schema, this covers purpose, cost/latency, trigger conditions, default fallback, and how the result plugs into sibling tools. Nothing an agent needs to call it correctly and act on the result 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 are zero input parameters, so the baseline is 4 and nothing about inputs needs explaining. The description instead documents output semantics (one "id — name" line per model) and how that id is consumed downstream, which is useful but is output guidance rather than input semantics.

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

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

States a specific verb and resource ("List the models the user's Google account can use through the Antigravity CLI") with concrete scope, so an agent can distinguish it from gemini_ask, gemini_research, gemini_code and the jules_* siblings 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 an explicit trigger ("Call it when the user asks for a specific or stronger model") and an explicit default path ("otherwise the gemini_* tools use agy's default"), which is exactly the when/when-not routing an agent needs.

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 readOnly/openWorld annotations: it discloses the execution path (Antigravity CLI), the billing model (no API cost, consumes the user's Google AI Pro limits), latency (~a minute), and the answer's sourcing behavior (prefers official sources, cross-checks, flags disagreement). The conversation_id handoff to gemini_ask is an extra behavioral fact an agent could not infer.

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

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

Front-loads purpose, then cost/latency/safety, then the sibling pointer, so the most decision-relevant content comes first. The Args/Returns block is standard and tight, though the 'Returns' prose partly restates what the existing output schema already provides.

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 open-world research tool with an output schema and full annotations, nothing material is missing: cost, runtime, trustworthiness of sources, follow-up chaining, and the alternative tool are all covered.

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

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

With 0% schema description coverage, the description fully compensates: it explains that 'question' should include narrowing context and gives a concrete example, that 'model' expects an id from gemini_models with a documented default fallback, and what 'effort' controls.

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

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

States a concrete verb and resource: 'Research a question on the live web with Gemini and Google Search, and get an answer that cites its sources.' It also distinguishes itself from siblings by naming gemini_ask for local files and gemini_models as the source of model ids.

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 conditions ('current facts, releases, prices, docs or comparisons that may be newer than your training data') and an explicit exclusion routing local-file questions to gemini_ask. The model parameter even points at gemini_models for valid ids.

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

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

With no annotations supplied, the description carries the full burden and does most of it: it declares 'Read-only, free and offline' and discloses a real environmental dependency, that Flow/Gemini app/Notebooks/AI Mode entries appear only under GEMINI_PRO_ENABLE_BROWSER=1. It does not say whether the benefit list is static or version-dependent, which is the one behavioral detail left implicit.

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

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

The core purpose and the 'call it first' rule are front-loaded in the first two lines, with the environment caveat and return shape following in priority order. The 'Returns:' block mildly repeats the earlier 'which tool reaches each part' phrasing, but the restatement is short and does clarify the per-benefit entry shape.

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

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

For a zero-parameter discovery tool with an output schema already defined, the description supplies everything else an agent needs: what it enumerates, when to invoke it, its safety/cost profile, and the environment flag that changes its contents. Nothing material 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 are zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. It correctly signals a no-argument call by describing the tool purely in terms of what it enumerates.

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

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

The description opens with a specific verb and resource ('List everything a Google AI Pro plan includes') and immediately clarifies the added value: mapping each benefit to the server tool that reaches it, or the reason it is unreachable. That framing distinguishes it from every sibling, which are action tools (gemini_ask, video_generate, jules_start) rather than a capability-discovery index.

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 an explicit routing rule: 'Call it first when the user asks what their plan can do or which tool to use.' That is a concrete trigger condition plus an ordering instruction, which is exactly the when-to-use guidance an agent needs for a discovery tool.

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

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

Annotations already declare a non-readonly, open-world, non-idempotent write, and the description goes well beyond them: exact per-image pricing by size and model, an explicit 'No free tier' warning, the output directory, and the requirement to confirm with the user first. It also discloses that results are persisted and addressable by id, which 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?

Front-loaded with purpose, then the cost warning, then per-argument notes - a sensible order that puts the highest-stakes information early. It is long, and the 'Returns' line partially duplicates an output schema that already exists, but nearly 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?

For a 7-parameter, costly, open-world generation tool, the description covers cost, model/size tradeoffs, edit-vs-create flow, output location, and the id needed for iterative refinement. With an output schema present, the brief 'Returns' note is sufficient rather than redundant padding.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: every one of the 7 parameters is explained with meaning, allowed values, and defaults, plus tradeoff guidance tying model to cost and image_size. It adds real decision information (e.g. flash-lite is 1K only) that the bare enum in the schema does not convey.

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

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

The first sentence states a specific verb and resource ('Create a new image from a prompt, or edit local images') and names the backend ('Nano Banana through the Gemini API'), which cleanly separates it from the video_* and gemini_ask siblings. It also distinguishes the two modes (fresh generation vs refinement via previous_id) inside the same opening.

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

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

Explicit guidance is given for previous_id ('refine an earlier result step by step ... without starting over'), for model choice ('cheapest, 1K only' vs 'best, for hard tasks'), and a hard gate ('Confirm with the user before calling'). The only gap is that it never names sibling alternatives such as video_generate for non-image media.

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

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

Annotations already declare this is a non-destructive, open-world mutation, and the description adds real context beyond them: the required session state, the fact that approval triggers code writing, and the error case when the session is not awaiting approval. It stops short of saying whether approval can be revoked, but otherwise the behavioral surface is well disclosed.

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

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

The main instruction, precondition, and alternative are front-loaded in the first sentence, with Args/Returns sections following in a scannable format. The Returns block restates behavior already implied, but nothing is padded or repetitive.

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 state-transition tool, the definition covers preconditions, the alternative action, error conditions, and the follow-up tool for tracking progress, while return shape is covered by the existing output schema. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 0% and the single 'session' parameter has no schema description, so the description must compensate. It does by identifying the value as a session id and naming the two sibling tools (jules_start, jules_sessions) that produce it, which is the key information an agent needs to populate the field correctly.

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

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

States a specific verb and resource ('approve the plan Jules proposed') plus the concrete consequence ('starts writing code'). It is clearly separable from the sibling jules_message, which the description explicitly names as the tool for changing the plan.

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

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

Gives an explicit precondition (session started with jules_start(require_plan_approval=True) and state awaiting plan approval), an ordering instruction (read the plan with jules_status first and show it to the user), and the alternative path (jules_message for feedback). Both when-to-use and when-not-to-use 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses the key behavioral trait that Jules replies asynchronously and the answer must be retrieved later with jules_status. That is real context the annotations cannot convey. It stops short of detail such as whether the message is queued immediately or whether multiple messages are allowed, so it is strong but not exhaustive.

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

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

The prose is front-loaded with purpose, alternatives, and the async caveat in three tight sentences. The trailing Args/Returns block is slightly redundant with the prose and with the output schema, but it is short and well-structured 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 two-parameter messaging tool, nothing an agent needs to call it correctly is missing: purpose, prerequisites for the session id, async follow-up, and sibling routing are all covered. A return value note is present even though an output schema already exists, which is harmless redundancy.

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

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

Schema description coverage is 0% and both parameters are required strings, so the description carries the burden. It compensates well: 'session' is defined as the session id obtained from jules_start or jules_sessions, and 'message' is characterized as plain-language content. The only gap is format expectations for the session id (e.g., raw id vs. resource name).

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

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

The description opens with a specific verb and resource: 'Send a message to Jules inside an existing session,' and immediately qualifies the scope as a follow-up within an existing session rather than a new engagement. It also names the sibling it is not (jules_start for new tasks), so an agent can route correctly without inspecting 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?

It enumerates concrete use cases (answer a question it asked, give feedback on plan or code, request a change) and explicitly routes two alternatives: jules_start for a new task and jules_status for reading the reply. Both the when-to-use and when-not-to-use conditions are stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so 'Read-only and free' partly restates structured data, but 'free' adds a cost signal the annotations don't carry. The description also discloses the return shape and enumerates the state values Jules may report, which is real behavioral context.

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

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

Front-loaded with the purpose in the first sentence, then routing, then structured Args/Returns blocks. Slightly padded by the redundant 'Read-only and free' clause, but no sentence is otherwise 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 one-parameter read tool, the description covers purpose, when to use, sibling routing, the parameter, and expected output including the empty case. 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 description coverage is 0%, so the description must supply meaning — it explains that 'limit' controls how many sessions are listed and that it defaults to 10. That fills the documentation gap for the only parameter, though it omits bounds or maximum allowed values.

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 the user's most recent Jules sessions'), plus ordering ('newest first') and the two concrete reasons to call it. It is clearly distinguishable from siblings like jules_status, which returns details for a single id.

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

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

Gives explicit when-to-use conditions (find a session id, see which tasks are running) and routes the agent onward: pass an id to jules_status, jules_approve_plan, or jules_message. The agent can pick the correct tool from this alone.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds behavior the annotations don't cover: it states that the tool is free, that the result feeds jules_start's `repo` argument, and it documents the empty-state case (no repo connected, with the link where the user connects GitHub).

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

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

It is front-loaded with the purpose and prerequisite, then a clearly delineated 'Returns:' block. Some of the return text overlaps with the existing output schema, and 'Read-only and free' partially restates readOnlyHint, so it is not entirely free of redundancy.

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

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

For a zero-parameter, read-only tool, the description covers purpose, prerequisite ordering, the value to hand to the next tool, and the failure/empty state. Nothing an agent needs in order to call it and use its result is missing; the return-format detail is a bonus beyond the output schema.

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

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

There are no input parameters, so the baseline is 4. The description goes a step further by explaining how the returned value maps onto another tool's parameter ('to pass as `repo` to jules_start'), which is meaning the empty input schema cannot 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?

The description opens with a specific verb and resource: 'List the GitHub repositories the user has connected to Jules.' It also identifies Jules as Google's cloud coding agent, which distinguishes this tool from the gemini_* siblings and from jules_start/jules_status without opening any schema.

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

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

It states the exact call ordering ('Call it before jules_start') and the condition that enforces it ('Jules can only work on repositories listed here'), plus the reason for calling ('to get the exact repo name'). This is explicit when-to-use and a hard prerequisite, with the consumer tool 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 only declare readOnly=false, openWorld=true, destructive=false. The description adds substantive context beyond that: cloud/asynchronous execution, the fact that Jules can push a branch and open a pull request (a real side effect worth warning about), that it operates under the Google AI Pro plan's Jules limits at no extra cost, and that require_plan_approval gates code changes. It also notes error behavior for unknown repositories.

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 the safety warning, then workflow, then alternatives, then parameters — a sensible ordering. It is somewhat longer than strictly necessary, and the Returns block partially restates what the output schema already provides, though the session-link format is a small extra. Minor redundancy, not bloat.

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

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

For a six-parameter, open-world, non-destructive-but-side-effectful tool, nothing an agent needs is missing: cost/quota context, side-effect warning, approval gating mechanism, sibling routing, parameter sourcing, and error cases. Since an output schema exists, the extra return-value sentence is harmless surplus rather than a gap.

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

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

Schema description coverage is 0%, so the description must carry the full burden, and it does: every one of the six parameters is explained with meaning, a concrete example ('Add input validation to the /signup endpoint...'), the source for valid values ('Repository from jules_sources, e.g. github/owner/repo'), stated defaults, and the null/omit case for repo.

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

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

States a specific verb and resource ('Start a Jules session') and immediately explains what the underlying agent does: Google's coding agent working on a task in one of the user's GitHub repos, in the cloud asynchronously. It also differentiates from the sibling gemini_code for local-folder changes, so the 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 the alternative ('For a change in a local folder use gemini_code instead'), prescribes the follow-up workflow (poll with jules_status, answer questions with jules_message, approve with jules_approve_plan), and flags the prerequisite of confirming the task with the user before starting. When-to-use, when-not-to-use, and sequencing are all 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 readOnlyHint=true and openWorldHint=true, and the description reinforces this with 'Read-only and free' while adding genuinely new context: the polling behavior for in-progress sessions. It stops short of stating rate limits or what happens for a nonexistent/expired session id, so it adds value but not full behavioral coverage.

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 opening sentence is front-loaded with purpose and scope, and the routing sentence follows logically. The Args/Returns docstring formatting is slightly verbose, and the Returns block partially restates what the output schema already provides, costing a bit of economy.

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

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

For a two-parameter read tool with annotations and an output schema, nothing an agent needs to invoke it correctly is missing: accepted id formats, default activity count, sibling routing, and polling guidance are all present.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: 'session' accepts a bare id from jules_start or jules_sessions, a full 'sessions/<id>' name, or a web link; 'activities' is the count of latest activities shown with a stated default of 15. This meaning is unavailable anywhere 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 ('Check on a Jules session started with jules_start') and enumerates what is retrieved: state, recent activities (plan, progress, questions, completion), and any pull request. This is clearly distinguishable from sibling tools like jules_sessions and jules_start.

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 jules_sessions to find an id, jules_approve_plan when the state awaits plan approval, and jules_message to answer a question. It also states the polling pattern ('call it again to poll a session that is still working'), which is the key alternative to a one-shot check.

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

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

The description adds behavior beyond the annotations: it discloses the cost model ('Free: the video was paid for when it was started, and checking costs nothing') and the polling semantics that justify idempotentHint=true. It also describes both success and failure outcomes (saved path vs. status/failure reason). It does not discuss filesystem write location details or timeout interaction with wait_seconds, which keeps it from a 5.

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

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

Front-loaded with the core action, followed by cost and retry notes, then parameter and return details. The Args/Returns blocks are slightly redundant with the schema and the existing output schema, but they are short and each sentence 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 two-parameter polling tool with an output schema already defined, the description covers the essential context: what it retrieves, why it's free to re-poll, how to poll, and what the response contains. Remaining gaps (units/ranges for wait_seconds, where the .mp4 is saved) are minor given the output schema.

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

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

Schema coverage is 0%, so the description carries the full burden and mostly succeeds: it explains that 'id' is 'The id returned by video_generate or video_edit' and that 'wait_seconds' is how long 'to keep waiting in this call (default 120) before returning the current status'. Units, valid ranges, and what happens at wait_seconds=0 are not stated, leaving a small gap.

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

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

States a concrete verb+resource pair ('Fetch a video ... and save it as an .mp4') and ties it to the specific producer tools (video_generate / video_edit) whose outputs it resolves. An agent can distinguish this from video_stitch, video_edit, and jules_status 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 trigger ('a video that video_generate or video_edit started but had not finished rendering when they returned') and explicit retry guidance ('Call it again with the same id if the video is still rendering'). It stops short of naming explicit exclusions or routing to a specific alternative sibling for the not-yet-ready case, so it is strong 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 flag this as a non-read-only, non-idempotent, open-world mutation, and the description adds the material facts they cannot express: the operation costs money and is billed like video_generate, output is written to a new file rather than mutating the input, and there is a wait/poll split with video_check. The input-video length ceiling (10 s) is another behavioral constraint disclosed up front.

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 cost warning and the mutual-exclusivity rule before the arg list, so the highest-risk information is read first. The Args/Returns block is compact, every line adds a fact not present in the schema, and there is no filler.

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

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

For a seven-parameter, costly, async-capable mutation this covers the decision points an agent needs: which input to supply, size limits, cost gating, and how to retrieve results later. The return shape is summarized briefly and an output schema exists, so nothing further is required there.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: each of the seven parameters gets meaning plus examples (instruction like "Make it night", extension phrasing), the enum values for aspect_ratio are restated, resolution defaults are named, and the mutual exclusivity between previous_id and video_path is stated. This is meaningfully more than the bare property names 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?

Opens with a specific verb and resource: "Change or extend a video; the result is saved as a new file." That single clause separates it from video_generate (creation) and video_stitch (joining), and the extend case is spelled out with concrete limits (adds 3-10 s, up to 40 s total).

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 routing: "Give exactly one of previous_id ... or video_path", names where previous_id comes from, and points to video_check for polling when wait_seconds expires. It also states a hard precondition — confirm with the user because it is billed — which is exactly the kind of gating an agent needs.

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-readonly, non-idempotent, open-world, non-destructive write, and the description goes well beyond them: real billing (~$0.10/sec of 720p, no free tier), required user confirmation, the 8-second clip limit, the wait_seconds timeout path, and where the file lands. The only missing piece is what happens on failure or whether a timed-out render is still billed.

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, cost warning, and chaining rule before the Args block; the Args/Returns structure is easy to scan and each parameter line adds new information. Minor drag from the model/provider name ('Gemini Omni Flash through the Gemini API'), which doesn't help an agent decide or call.

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 costly, slow, open-world generation tool, the description covers cost, latency/timeout, output location, follow-up tools, and every parameter. An output schema exists, so the brief Returns summary is sufficient rather than redundant.

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

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

Schema description coverage is 0%, so the description must carry all eight parameters — and it does, with meaning the schema cannot convey: prompt structure with a worked example and timecode sequencing syntax, first_frame/last_frame as start/end anchors, reference_images capped at 3 for character consistency, and the default file-name rule.

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 short video with native sound from a text prompt') plus the concrete output (an .mp4 in GEMINI_PRO_OUTPUT_DIR). It explicitly separates itself from siblings by naming video_edit for extension and flow_make_video as the credit-based alternative.

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 conditions (one call = ~8s clip; chain video_edit for longer), names a concrete alternative (flow_make_video, gated on browser tools being enabled), and adds a mandatory pre-call step: confirm cost with the user. Exclusions and routing are both present.

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: discloses local execution with no cost, that same-format clips are joined losslessly while mixed formats are re-encoded to H.264/AAC, that output lands in GEMINI_PRO_OUTPUT_DIR, and that a numeric suffix is appended on filename collision. It does not mention failure/partial-output behavior when a clip mid-list is corrupt or unsupported, which is the main residual gap for a write-producing tool.

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

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

Front-loaded with the core action in the first sentence, followed by behavior, then routing guidance, then compact Args/Returns sections. Given the 0% schema coverage, the parameter lines are load-bearing rather than redundant, and 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?

Despite an output schema existing, the description still sketches the return string ('Saved: <path>' or an error), and it covers cost, encoding strategy, output location, and sibling boundaries. For a two-parameter local tool, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it largely does: clips are paths in first-to-last order with a minimum of one, and file_name is saved into GEMINI_PRO_OUTPUT_DIR with collision-avoidance renaming. It stops short of specifying accepted input formats or whether paths must be absolute, which would fully close the gap.

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

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

States a specific verb and resource ('Join local video clips ... into one .mp4 with ffmpeg') plus ordering semantics, so the operation is unmistakable. It also distinguishes itself from flow_make_video, which already joins its own clips, and names the sibling producers whose output it consumes.

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 upstream tools whose clips it should combine (video_generate, video_edit, flow_collect) and gives a clear exclusion ('flow_make_video already joins its own clips'). Both the when-to-use and when-not-to-use conditions are stated rather than implied.

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