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

With no annotations, the description carries the full burden and does so well: it discloses that YouTube transcription is asynchronous, that callers must poll get_notebook until status is 'done', that text is stored immediately, and that the call returns the created source with id and status. These are exactly the behavioral traits an agent needs before invoking it.

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, then per-type requirements, then the exclusion and return value. Every clause carries information 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?

No output schema exists, and the description compensates by describing the return value (created source with id and status) plus the async polling workflow and type-specific requirements. Nothing an agent needs in order to call this correctly 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?

Schema description coverage is 100% and the schema already documents each parameter, including 'required when type is youtube/text'. The description restates those conditional requirements but adds no syntax or format detail beyond the schema (e.g. it never mentions the lang parameter). 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?

The description states a specific verb and resource ('Add a source to a meeting note') and immediately enumerates the two supported source types with their required inputs. It also carves out a distinct boundary by clarifying that a recording comes from the Roomtone app rather than this tool, so an agent will not confuse it with capture 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?

It gives explicit conditions for selecting each mode: 'youtube' requires url and is transcribed asynchronously, 'text' requires text and is stored immediately. It also states a when-not case ('A recording itself always comes from the Roomtone app, not from this tool') and points to get_notebook for polling the async result.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses that answers are grounded in processed-source transcripts, that the return is plain text, and that an empty-source meeting produces an explanatory reply rather than an error. It does not cover persistence of chat history, 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?

Three short sentences, front-loaded with the purpose and grounding guarantee, and the return format is stated only because no output schema exists. 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 two-parameter, no-annotation, no-output-schema tool, the definition covers purpose, grounding behavior, return type, and the degenerate empty-source case. Only deeper operational details (history persistence, auth) are absent, which is acceptable 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 description coverage is 100% for both parameters, so the schema already documents 'message' and 'notebook_id' fully. The description adds no syntax, length, or format constraints beyond what the schema provides, 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+resource ('ask a question about a meeting') and clarifies the grounding source (processed source transcripts), which distinguishes it from siblings like generate_note. It stops short of explicitly naming which sibling to use when, but the action is unambiguous.

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

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

Usage is implied by the phrasing — you use it when you have a question about a meeting — and the no-processed-sources case is called out. However, there is no explicit when-not guidance and no alternative sibling (e.g., get_transcript for raw reads, generate_note for summaries) is 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?

With no annotations, the description carries the full burden and does fairly well: it discloses the return value ('including its id') and a concrete failure mode (free-plan quota exhaustion returning a friendly upgrade message instead of creating the note). It omits auth/permission requirements and other error behavior, so it is solid 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?

Three lean sentences, front-loaded with the core action and followed by return and quota behavior. Every sentence carries information, though the quota sentence is slightly more verbose than necessary.

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

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

For a 2-parameter creation tool with no output schema and no annotations, the description covers the action, the return value, and a notable quota-based failure mode. Remaining gaps (auth requirements, other error cases) are minor given the tool's simplicity.

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 title and emoji (including the default emoji). The description adds no format, constraint, or uniqueness detail beyond what the schema provides, 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 ('Start a new meeting note') and names the configurable fields (title, emoji). It is clearly distinguishable from read-oriented siblings like list_notebooks/get_notebook and from generate_note, though it does not name those siblings explicitly.

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

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

Usage is only implied via the workflow hint 'ready for a source to be added to it', which suggests calling this before add_source. There is no explicit when-to-use/when-not statement and no named alternative for different creation paths.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the tool runs in the background, returns {status: 'generating', type} rather than the finished artifact, and that the write-up appears later in the note's content list. It doesn't cover cost, rate limits, or failure/error behavior, which keeps it below 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 sentences, zero filler, with the async contract front-loaded before the follow-up instruction. Every sentence contributes a distinct operational fact.

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 must explain the return value — it does so precisely ({status: 'generating', type}) plus the retrieval path via get_notebook. Combined with the stated precondition, an agent has everything needed to invoke and follow up 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 notebook_id, lang, and type are already documented in the schema. The description adds no syntax or default detail beyond it; per the rules, a 100%-covered schema sets a baseline of 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 and resource ('Generate (or regenerate) the write-up for a meeting from its sources'), including the regeneration case. It also names the sibling to read the result with (get_notebook), so an agent can distinguish this from the read-side 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 an explicit precondition ('Requires the meeting to have at least one processed source') and routes the agent to the follow-up tool after the async call. It does not state any when-not conditions or contrast with other generation options, so it falls short of full 5-level guidance.

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

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

With no annotations present, the description carries the full disclosure burden, and it does add real behavioral context: the shape of the returned payload and the meaning of the four source status values, including the gating rule that transcripts require 'done'. It omits error behavior for an unknown/invalid id and any permission requirements.

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 sentences, no filler. The retrieval scope is front-loaded and the status/transcript caveat follows as a tight second 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?

For a one-parameter read tool with no output schema, the description compensates well by describing the return payload itself and the status enum. Only the failure mode for a nonexistent id is unaddressed.

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

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

Schema description coverage is 100% and there is a single parameter, so the schema already documents notebook_id and its provenance ('as returned by list_notebooks'). The description adds no format, validation, or id-sourcing detail beyond that, 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+resource ('Get one meeting by id') and enumerates the payload (sources with their fields, plus the generated note), which clearly separates it from the sibling list_notebooks. An agent knows exactly which tool retrieves a single meeting vs. enumerating them.

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

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

Usage is implied rather than stated: you fetch by id, and the note about transcripts only being available when a source is 'done' implies a polling/wait condition. It never names alternatives (get_transcript, chat_with_sources) or says when not to call it, so this is minimum-viable guidance.

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

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

With no annotations, the description carries the full burden; it does disclose the return format (plain text) and the important readiness caveat (empty/null until the source finishes processing). It does not cover permissions, behavior for non-transcript sources, or size/pagination 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?

Two tight sentences with no filler; the primary purpose leads and the readiness caveat follows as a useful caveat.

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

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

Since there is no output schema, the description helpfully explains the return value and its null-until-processed state. For a simple two-parameter read tool this is nearly complete, though a note on failure modes or empty transcript sources 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?

Schema description coverage is 100%, so both parameters are already documented, and the description only restates that source ids come from get_notebook. Baseline 3 is appropriate since 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 and resource ('Get the raw transcript text of a single source on a meeting note') and scopes it to one source, distinguishing it from sibling tools like get_notebook and chat_with_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?

Implies when the tool is useful by pointing to get_notebook as the source of ids and warning the transcript is empty until processing finishes, but never states when to prefer this over chat_with_sources or get_notebook itself.

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

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

With no annotations, the description carries the full burden and does disclose ordering ('newest first') and timestamp units ('unix seconds'), which is real behavioral value. It omits pagination/result-limit behavior and any auth or permission context, so it is not fully self-sufficient.

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 scope, then the return contract, then the follow-up action. Nothing is padded or repeated.

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 enumerating returned fields, their units, and sort order. Only pagination/result-size behavior is left unstated, which is a minor gap for a zero-param read tool.

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

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

The schema has zero parameters, so the baseline is 4. The description usefully documents the returned field set (id, title, emoji, sources_count, updated_at), which is beyond anything the empty input schema conveys.

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 meeting in the user's Roomtone account') and reconciles the name/title mismatch between 'notebooks' and 'meetings'. It distinguishes itself from get_notebook by being the bulk enumerator, but never names the sibling tools it feeds.

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 the returned id with the other tools' gives a clear downstream entry-point role, but there is no explicit when-to-use vs when-not guidance and no alternative named (e.g. get_notebook for a single item). Usage is only implied.

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